1String::Base(3)       User Contributed Perl Documentation      String::Base(3)
2
3
4

NAME

6       String::Base - string index offseting
7

SYNOPSIS

9           use String::Base +1;
10
11           no String::Base;
12

DESCRIPTION

14       This module implements automatic offsetting of string indices.  In
15       normal Perl, the first character of a string has index 0, the second
16       character has index 1, and so on.  This module allows string indexes to
17       start at some other value.  Most commonly it is used to give the first
18       character of a string the index 1 (and the second 2, and so on), to
19       imitate the indexing behaviour of FORTRAN and many other languages.  It
20       is usually considered poor style to do this.
21
22       The string index offset is controlled at compile time, in a lexically-
23       scoped manner.  Each block of code, therefore, is subject to a fixed
24       offset.  It is expected that the affected code is written with
25       knowledge of what that offset is.
26
27   Using a string index offset
28       A string index offset is set up by a "use String::Base" directive, with
29       the desired offset specified as an argument.  Beware that a bare,
30       unsigned number in that argument position, such as ""use String::Base
31       1"", will be interpreted as a version number to require of
32       "String::Base".  It is therefore necessary to give the offset a leading
33       sign, or parenthesise it, or otherwise decorate it.  The offset may be
34       any integer (positive, zero, or negative) within the range of Perl's
35       integer arithmetic.
36
37       A string index offset declaration is in effect from immediately after
38       the "use" line, until the end of the enclosing block or until
39       overridden by another string index offset declaration.  A declared
40       offset always replaces the previous offset: they do not add.  ""no
41       String::Base"" is equivalent to ""use String::Base +0"": it returns to
42       the Perlish state with zero offset.
43
44       A declared string index offset influences these types of operation:
45
46       •   substring extraction ("substr($a, 3, 2)")
47
48       •   substring splicing ("substr $a, 3, 2, "x"")
49
50       •   substring searching ("index($a, "x")", "index($a, "x", 3)",
51           "rindex($a, "x")", "rindex($a, "x", 3)")
52
53       •   string iterator position (pos($a))
54
55       Only forwards indexing, relative to the start of the string, is
56       supported.  End-relative indexing, normally done using negative index
57       values, is not supported when an index offset is in effect.  Use of an
58       index that is numerically less than the index offset will have
59       unpredictable results.
60
61   Differences from $[
62       This module is a replacement for the historical $[ variable.  In early
63       Perl that variable was a runtime global, affecting all array and string
64       indexing in the program.  In Perl 5, assignment to $[ acts as a
65       lexically-scoped pragma.  $[ is deprecated.  The original $[ was
66       removed in Perl 5.15.3, and later replaced in Perl 5.15.5 by an
67       automatically-loaded arybase module.  This module reimplements the
68       index offset feature without any specific support from the core.
69
70       Unlike $[, this module does not affect indexing into arrays.  This
71       module is concerned only with strings.  To influence array indexing,
72       see Array::Base.
73
74       This module does not show the offset value in $[ or any other
75       accessible variable.  With the string offset being lexically scoped,
76       there should be no need to write code to handle a variable offset.
77
78       $[ has some predictable, but somewhat strange, behaviour for indexes
79       less than the offset.  The behaviour differs between substring
80       extraction and iterator positioning.  This module does not attempt to
81       replicate it, and does not support end-relative indexing at all.
82
83       The string iterator position operator (pos($a)), as implemented by the
84       Perl core, generates a magical scalar which is linked to the underlying
85       string.  The numerical value of the scalar varies if the iterator
86       position of the string is changed, and code with different $[ settings
87       will see accordingly different values.  The scalar can also be written
88       to, to change the position of the string's iterator, and again the
89       interpretation of the value written varies according to the $[ setting
90       of the code that is doing the writing.  This module does not replicate
91       any of that behaviour.  With a string index offset from this module in
92       effect, pos($a) evaluates to an ordinary rvalue scalar, giving the
93       position of the string's iterator as it was at the time the operator
94       was evaluated, according to the string index offset in effect where the
95       operator appears.
96

PACKAGE METHODS

98       These methods are meant to be invoked on the "String::Base" package.
99
100       String::Base->import(BASE)
101           Sets up a string index offset of BASE, in the lexical environment
102           that is currently compiling.
103
104       String::Base->unimport
105           Clears the string index offset, in the lexical environment that is
106           currently compiling.
107

BUGS

109       B::Deparse will generate incorrect source when deparsing code that uses
110       a string index offset.  It will include both the pragma to set up the
111       offset and the munged form of the affected operators.  Either the
112       pragma or the munging is required to get the index offset effect; using
113       both will double the offset.  Also, the code generated for a string
114       iterator position (pos($a)) operation involves a custom operator, which
115       B::Deparse can't understand, so the source it emits in that case is
116       completely wrong.
117
118       The additional operators generated by this module cause spurious
119       warnings if some of the affected string operations are used in void
120       context.
121
122       Prior to Perl 5.9.3, the lexical state of string index offset does not
123       propagate into string eval.
124

SEE ALSO

126       Array::Base, arybase, "$[" in perlvar
127

AUTHOR

129       Andrew Main (Zefram) <zefram@fysh.org>
130
132       Copyright (C) 2011, 2012, 2017 Andrew Main (Zefram) <zefram@fysh.org>
133

LICENSE

135       This module is free software; you can redistribute it and/or modify it
136       under the same terms as Perl itself.
137
138
139
140perl v5.36.0                      2023-01-20                   String::Base(3)
Impressum