File Coverage

blib/lib/String/Base.pm
Criterion Covered Total %
statement 11 11 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 15 15 100.0


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             String::Base - string index offseting
4              
5             =head1 SYNOPSIS
6              
7             use String::Base +1;
8              
9             no String::Base;
10              
11             =head1 DESCRIPTION
12              
13             This module implements automatic offsetting of string indices. In normal
14             Perl, the first character of a string has index 0, the second character
15             has index 1, and so on. This module allows string indexes to start at
16             some other value. Most commonly it is used to give the first character
17             of a string the index 1 (and the second 2, and so on), to imitate the
18             indexing behaviour of FORTRAN and many other languages. It is usually
19             considered poor style to do this.
20              
21             The string index offset is controlled at compile time, in a
22             lexically-scoped manner. Each block of code, therefore, is subject to
23             a fixed offset. It is expected that the affected code is written with
24             knowledge of what that offset is.
25              
26             =head2 Using a string index offset
27              
28             A string index offset is set up by a C directive, with
29             the desired offset specified as an argument. Beware that a bare, unsigned
30             number in that argument position, such as "C", will
31             be interpreted as a version number to require of C. It is
32             therefore necessary to give the offset a leading sign, or parenthesise
33             it, or otherwise decorate it. The offset may be any integer (positive,
34             zero, or negative) within the range of Perl's integer arithmetic.
35              
36             A string index offset declaration is in effect from immediately after the
37             C line, until the end of the enclosing block or until overridden
38             by another string index offset declaration. A declared offset always
39             replaces the previous offset: they do not add. "C"
40             is equivalent to "C": it returns to the Perlish
41             state with zero offset.
42              
43             A declared string index offset influences these types of operation:
44              
45             =over
46              
47             =item *
48              
49             substring extraction (C)
50              
51             =item *
52              
53             substring splicing (C)
54              
55             =item *
56              
57             substring searching (C, C,
58             C, C)
59              
60             =item *
61              
62             string iterator position (C)
63              
64             =back
65              
66             Only forwards indexing, relative to the start of the string, is supported.
67             End-relative indexing, normally done using negative index values, is
68             not supported when an index offset is in effect. Use of an index that
69             is numerically less than the index offset will have unpredictable results.
70              
71             =head2 Differences from C<$[>
72              
73             This module is a replacement for the historical L|perlvar/$[>
74             variable. In early Perl that variable was a runtime global, affecting all
75             array and string indexing in the program. In Perl 5, assignment to C<$[>
76             acts as a lexically-scoped pragma. C<$[> is deprecated. The original
77             C<$[> was removed in Perl 5.15.3, and later replaced in Perl 5.15.5 by
78             an automatically-loaded L module. This module reimplements
79             the index offset feature without any specific support from the core.
80              
81             Unlike C<$[>, this module does not affect indexing into arrays. This
82             module is concerned only with strings. To influence array indexing,
83             see L.
84              
85             This module does not show the offset value in C<$[> or any other
86             accessible variable. With the string offset being lexically scoped,
87             there should be no need to write code to handle a variable offset.
88              
89             C<$[> has some predictable, but somewhat strange, behaviour for indexes
90             less than the offset. The behaviour differs between substring extraction
91             and iterator positioning. This module does not attempt to replicate it,
92             and does not support end-relative indexing at all.
93              
94             The string iterator position operator (C), as implemented
95             by the Perl core, generates a magical scalar which is linked to the
96             underlying string. The numerical value of the scalar varies if the
97             iterator position of the string is changed, and code with different C<$[>
98             settings will see accordingly different values. The scalar can also be
99             written to, to change the position of the string's iterator, and again
100             the interpretation of the value written varies according to the C<$[>
101             setting of the code that is doing the writing. This module does not
102             replicate any of that behaviour. With a string index offset from this
103             module in effect, C evaluates to an ordinary rvalue scalar,
104             giving the position of the string's iterator as it was at the time the
105             operator was evaluated, according to the string index offset in effect
106             where the operator appears.
107              
108             =cut
109              
110             package String::Base;
111              
112 4     4   274579 { use 5.008001; }
  4         17  
113 4     4   1507 use Lexical::SealRequireHints 0.006;
  4         3378  
  4         28  
114 4     4   141 use warnings;
  4         19  
  4         143  
115 4     4   26 use strict;
  4         11  
  4         293  
116              
117             our $VERSION = "0.003";
118              
119             require XSLoader;
120             XSLoader::load(__PACKAGE__, $VERSION);
121              
122             =head1 PACKAGE METHODS
123              
124             These methods are meant to be invoked on the C package.
125              
126             =over
127              
128             =item String::Base->import(BASE)
129              
130             Sets up a string index offset of I, in the lexical environment
131             that is currently compiling.
132              
133             =item String::Base->unimport
134              
135             Clears the string index offset, in the lexical environment that is
136             currently compiling.
137              
138             =back
139              
140             =head1 BUGS
141              
142             L will generate incorrect source when deparsing code that
143             uses a string index offset. It will include both the pragma to set up
144             the offset and the munged form of the affected operators. Either the
145             pragma or the munging is required to get the index offset effect; using
146             both will double the offset. Also, the code generated for a string
147             iterator position (C) operation involves a custom operator,
148             which B::Deparse can't understand, so the source it emits in that case
149             is completely wrong.
150              
151             The additional operators generated by this module cause spurious warnings
152             if some of the affected string operations are used in void context.
153              
154             Prior to Perl 5.9.3, the lexical state of string index offset does not
155             propagate into string eval.
156              
157             =head1 SEE ALSO
158              
159             L,
160             L,
161             L
162              
163             =head1 AUTHOR
164              
165             Andrew Main (Zefram)
166              
167             =head1 COPYRIGHT
168              
169             Copyright (C) 2011, 2012, 2017 Andrew Main (Zefram)
170              
171             =head1 LICENSE
172              
173             This module is free software; you can redistribute it and/or modify it
174             under the same terms as Perl itself.
175              
176             =cut
177              
178             1;