NAME

Array::Base - array index offseting

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.

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 mainly influences array indexing, both for
single elements and for array slices.  It also affects the value returned
by "$#array": this returns the index of the last element of the array,
taking the offset into account.  Only forwards indexing, relative to the
start of the array, is handled.  End-relative indexing, normally done
using negative index values, is not supported when an index offset is
in effect, and 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 likely to be removed in Perl 5.12.  This module reimplements the
index offset feature without using the deprecated mechanism.  Unlike $[,
this module does not affect indexing into strings with index or substr.
It also does not show the offset value in $[.

INSTALLATION

	perl Build.PL
	./Build
	./Build test
	./Build install

AUTHOR

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

COPYRIGHT

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

LICENSE

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