Array::Base - array index offseting

Author

       Andrew Main (Zefram) <zefram@fysh.org>

Bugs

       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.

Copyright

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

Description

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.

Usinganarrayindexoffset
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.

Differencesfrom$[
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.

License

       This module is free software; you can redistribute it and/or modify it  under  the  same  terms  as  Perl
       itself.

perl v5.40.1                                       2025-04-13                                   Array::Base(3pm)

Name

       Array::Base - array index offseting

Package Methods

       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.

Synopsis

           use Array::Base +1;

           no Array::Base;