1Array::Base(3) User Contributed Perl Documentation Array::Base(3)
2
6 Array::Base - array index offseting
7
9 use Array::Base +1;
10 no Array::Base;
12
14 This module implements automatic offsetting of array indices. In
15 normal Perl, the first element of an array has index 0, the second
16 element has index 1, and so on. This module allows array indexes to
17 start at some other value. Most commonly it is used to give the first
18 element of an array 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 The array 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 Using an array index offset
28 An array index offset is set up by a "use Array::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 Array::Base
31 1"", will be interpreted as a version number to require of
32 "Array::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 An array 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 array index offset declaration. A declared
40 offset always replaces the previous offset: they do not add. ""no
41 Array::Base"" is equivalent to ""use Array::Base +0"": it returns to
42 the Perlish state with zero offset.
43 A declared array index offset influences these types of operation:
45 • array indexing ($a[3])
47 • array slicing (@a[3..5])
49 • array pair slicing (%a[3..5])
51 • list indexing/slicing ("qw(a b c)[2]")
53 • array splicing ("splice(@a, 3, 2)")
55 • array last index ($#a)
57 • array keys ("keys(@a)") (Perl 5.11 and later)
59 • array each ("each(@a)") (Perl 5.11 and later)
61 Only forwards indexing, relative to the start of the array, is
63 supported. End-relative indexing, normally done using negative index
64 values, is not supported when an index offset is in effect. Use of an
65 index that is numerically less than the index offset will have
66 unpredictable results.
67 Differences from $[
69 This module is a replacement for the historical $[ variable. In early
70 Perl that variable was a runtime global, affecting all array and string
71 indexing in the program. In Perl 5, assignment to $[ acts as a
72 lexically-scoped pragma. $[ is deprecated. The original $[ was
73 removed in Perl 5.15.3, and later replaced in Perl 5.15.5 by an
74 automatically-loaded arybase module. This module reimplements the
75 index offset feature without any specific support from the core.
76 Unlike $[, this module does not affect indexing into strings. This
78 module is concerned only with arrays. To influence string indexing,
79 see String::Base.
80 This module does not show the offset value in $[ or any other
82 accessible variable. With the array offset being lexically scoped,
83 there should be no need to write code to handle a variable offset.
84 $[ has some predictable, but somewhat strange, behaviour for indexes
86 less than the offset. The behaviour differs slightly between slicing
87 and scalar indexing. This module does not attempt to replicate it, and
88 does not support end-relative indexing at all.
89 The last-index operator ($#a), as implemented by the Perl core,
91 generates a magical scalar which is linked to the underlying array.
92 The numerical value of the scalar varies if the length of the array is
93 changed, and code with different $[ settings will see accordingly
94 different values. The scalar can also be written to, to change the
95 length of the array, and again the interpretation of the value written
96 varies according to the $[ setting of the code that is doing the
97 writing. This module does not replicate any of that behaviour. With
98 an array index offset from this module in effect, $#a evaluates to an
99 ordinary rvalue scalar, giving the last index of the array as it was at
100 the time the operator was evaluated, according to the array index
101 offset in effect where the operator appears.
102
104 These methods are meant to be invoked on the "Array::Base" package.
105 Array::Base->import(BASE)
107 Sets up an array index offset of BASE, in the lexical environment
108 that is currently compiling.
109 Array::Base->unimport
111 Clears the array index offset, in the lexical environment that is
112 currently compiling.
113
115 B::Deparse will generate incorrect source when deparsing code that uses
116 an array index offset. It will include both the pragma to set up the
117 offset and the munged form of the affected operators. Either the
118 pragma or the munging is required to get the index offset effect; using
119 both will double the offset. Also, the code generated for an array
120 each ("each(@a)") operation involves a custom operator, which
121 B::Deparse can't understand, so the source it emits in that case is
122 completely wrong.
123 The additional operators generated by this module cause spurious
125 warnings if some of the affected array operations are used in void
126 context.
127 Prior to Perl 5.9.3, the lexical state of array index offset does not
129 propagate into string eval.
130
132 String::Base, arybase, "$[" in perlvar
133
135 Andrew Main (Zefram) <zefram@fysh.org>
136
138 Copyright (C) 2009, 2010, 2011, 2012, 2017 Andrew Main (Zefram)
139 <zefram@fysh.org>
140
142 This module is free software; you can redistribute it and/or modify it
143 under the same terms as Perl itself.
144perl v5.32.1 2021-01-26 Array::Base(3)