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

NAME

6       Array::Base - array index offseting
7

SYNOPSIS

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

DESCRIPTION

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
22       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
27   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
37       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
44       A declared array index offset influences these types of operation:
45
46       •   array indexing ($a[3])
47
48       •   array slicing (@a[3..5])
49
50       •   array pair slicing (%a[3..5])
51
52       •   list indexing/slicing ("qw(a b c)[2]")
53
54       •   array splicing ("splice(@a, 3, 2)")
55
56       •   array last index ($#a)
57
58       •   array keys ("keys(@a)") (Perl 5.11 and later)
59
60       •   array each ("each(@a)") (Perl 5.11 and later)
61
62       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
68   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
77       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
81       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
85       $[ 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
90       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

PACKAGE METHODS

104       These methods are meant to be invoked on the "Array::Base" package.
105
106       Array::Base->import(BASE)
107           Sets up an array index offset of BASE, in the lexical environment
108           that is currently compiling.
109
110       Array::Base->unimport
111           Clears the array index offset, in the lexical environment that is
112           currently compiling.
113

BUGS

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
124       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
128       Prior to Perl 5.9.3, the lexical state of array index offset does not
129       propagate into string eval.
130

SEE ALSO

132       String::Base, arybase, "$[" in perlvar
133

AUTHOR

135       Andrew Main (Zefram) <zefram@fysh.org>
136
138       Copyright (C) 2009, 2010, 2011, 2012, 2017 Andrew Main (Zefram)
139       <zefram@fysh.org>
140

LICENSE

142       This module is free software; you can redistribute it and/or modify it
143       under the same terms as Perl itself.
144
145
146
147perl v5.34.0                      2022-01-20                    Array::Base(3)
Impressum