Array::Base - array index offseting
use Array::Base +1;
no Array::Base;
This module implements automatic offsetting of array indices. In normal Perl,
the first element of an array has index 0, the second element has index 1, and
so on. This module allows array indexes to start at some other value. Most
commonly it is used to give the first element of an array the index 1 (and the
second 2, and so on), to imitate the indexing behaviour of FORTRAN and many
other languages. It is usually considered poor style to do this.
The array index offset is controlled at compile time, in a lexically-scoped
manner. Each block of code, therefore, is subject to a fixed offset. It is
expected that the affected code is written with knowledge of what that offset
is.
An array index offset is set up by a "use Array::Base" directive, with
the desired offset specified as an argument. Beware that a bare, unsigned
number in that argument position, such as ""use Array::Base
1"", will be interpreted as a version number to require of
"Array::Base". It is therefore necessary to give the offset a
leading sign, or parenthesise it, or otherwise decorate it. The offset may be
any integer (positive, zero, or negative) within the range of Perl's integer
arithmetic.
An array index offset declaration is in effect from immediately after the
"use" line, until the end of the enclosing block or until overridden
by another array index offset declaration. A declared offset always replaces
the previous offset: they do not add. ""no Array::Base""
is equivalent to ""use Array::Base +0"": it returns to the
Perlish state with zero offset.
A declared array index offset influences these types of operation:
- •
- array indexing ($a[3])
- •
- array slicing (@a[3..5])
- •
- array pair slicing (%a[3..5])
- •
- list indexing/slicing ("qw(a b c)[2]")
- •
- array splicing ("splice(@a, 3, 2)")
- •
- array last index ($#a)
- •
- array keys ("keys(@a)") (Perl 5.11 and
later)
- •
- array each ("each(@a)") (Perl 5.11 and
later)
Only forwards indexing, relative to the start of the array, is supported.
End-relative indexing, normally done using negative index values, is not
supported when an index offset is in effect. Use of an index that is
numerically less than the index offset will have unpredictable results.
This module is a replacement for the historical $[ variable. In early Perl that
variable was a runtime global, affecting all array and string indexing in the
program. In Perl 5, assignment to $[ acts as a lexically-scoped pragma. $[ is
deprecated. The original $[ was removed in Perl 5.15.3, and later replaced in
Perl 5.15.5 by an automatically-loaded arybase module. This module
reimplements the index offset feature without any specific support from the
core.
Unlike $[, this module does not affect indexing into strings. This module is
concerned only with arrays. To influence string indexing, see String::Base.
This module does not show the offset value in $[ or any other accessible
variable. With the array offset being lexically scoped, there should be no
need to write code to handle a variable offset.
$[ has some predictable, but somewhat strange, behaviour for indexes less than
the offset. The behaviour differs slightly between slicing and scalar
indexing. This module does not attempt to replicate it, and does not support
end-relative indexing at all.
The last-index operator ($#a), as implemented by the Perl core, generates a
magical scalar which is linked to the underlying array. The numerical value of
the scalar varies if the length of the array is changed, and code with
different $[ settings will see accordingly different values. The scalar can
also be written to, to change the length of the array, and again the
interpretation of the value written varies according to the $[ setting of the
code that is doing the writing. This module does not replicate any of that
behaviour. With an array index offset from this module in effect, $#a
evaluates to an ordinary rvalue scalar, giving the last index of the array as
it was at the time the operator was evaluated, according to the array index
offset in effect where the operator appears.
These methods are meant to be invoked on the "Array::Base" package.
- Array::Base->import(BASE)
- Sets up an array index offset of BASE, in the
lexical environment that is currently compiling.
- Array::Base->unimport
- Clears the array index offset, in the lexical environment
that is currently compiling.
B::Deparse will generate incorrect source when deparsing code that uses an array
index offset. It will include both the pragma to set up the offset and the
munged form of the affected operators. Either the pragma or the munging is
required to get the index offset effect; using both will double the offset.
Also, the code generated for an array each ("each(@a)") operation
involves a custom operator, which B::Deparse can't understand, so the source
it emits in that case is completely wrong.
The additional operators generated by this module cause spurious warnings if
some of the affected array operations are used in void context.
Prior to Perl 5.9.3, the lexical state of array index offset does not propagate
into string eval.
String::Base, arybase, "$[" in perlvar
Andrew Main (Zefram) <
[email protected]>
Copyright (C) 2009, 2010, 2011, 2012, 2017 Andrew Main (Zefram)
<
[email protected]>
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.