| Array::Base - array index offseting |
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])
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 indexing in the program. In Perl 5, assignment to $[
acts as a lexically-scoped pragma. $[ is highly deprecated, and
the mechanism that supports it is due to be removed in Perl 5.15.
This module reimplements the index offset feature without using the
deprecated mechanism.
Unlike $[, this module does not affect indexing into strings
(with index, substr, and
pos): this module is concerned only with arrays.
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.
import(BASE)
Sets up an array index offset of BASE, in the lexical environment that is currently compiling.
Clears the array index offset, in the lexical environment that is currently compiling.
the B::Deparse manpage 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 the B::Deparse manpage
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.
perlvar/$[
Andrew Main (Zefram) <zefram@fysh.org>
Copyright (C) 2009, 2010, 2011 Andrew Main (Zefram) <zefram@fysh.org>
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
| Array::Base - array index offseting |