perlfunc
root
<P>
Tie::Array - base class for tied arrays
<P>
<HR>
<P>
<PRE> package NewArray;
use Tie::Array;
@ISA = ('Tie::Array');
# mandatory methods
sub TIEARRAY { ... }
sub FETCH { ... }
sub FETCHSIZE { ... }
sub STORE { ... } # mandato
<P>
This module provides methods for array-tying classes. See
[perlman:perltie|perltie] for a list of the functions required in order to tie an array to a package.
The basic <STRONG>Tie::Array</STRONG> package provides stub <CODE>DELETE</CODE>
and [perlman:perlguts|perlguts] methods, and implementations of <CODE>PUSH</CODE>, <CODE>POP</CODE>, <CODE>SHIFT</CODE>,
<CODE>UNSHIFT</CODE>, <CODE>SPLICE</CODE> and <CODE>CLEAR</CODE> in terms of basic <CODE>FETCH</CODE>, <CODE>STORE</CODE>,
<CODE>FETCHSIZE</CODE>, <CODE>STORESIZE</CODE>.
<P>
The <STRONG>Tie::StdArray</STRONG> package provides efficient methods required for tied arrays which are
implemented as blessed references to an ``inner'' perl array. It inherits
from <STRONG>Tie::Array</STRONG>, and should cause tied arrays to behave exactly like standard arrays,
allowing for selective overloading of methods.
<P>
For developers wishing to write their own tied arrays, the required methods
are briefly defined below. See the [perlman:perltie|perltie] section for more detailed descriptive, as well as example code:
<DL>
<DT><STRONG><A NAME="item_TIEARRAY">TIEARRAY classname, LIST</A></STRONG><P>
<DD>
The class method is invoked by the command <CODE>tie @array, classname</CODE>. Associates an array instance with the specified class. <CODE>LIST</CODE> would represent additional arguments (along the lines of [perlman:lib:AnyDBM_File|AnyDBM_File] and compatriots) needed to complete the association. The method should
return an object of a class which provides the methods below.
<P><DT><STRONG><A NAME="item_STORE">STORE this, index, value</A></STRONG><P>
<DD>
Store datum <EM>value</EM> into <EM>index</EM> for the tied array assoicated with object <EM>this</EM>. If this makes the array larger then class's mapping of [perlfunc:undef|undef] should be returned for new positions.
<P><DT><STRONG><A NAME="item_FETCH">FETCH this, index</A></STRONG><P>
<DD>
Retrieve the datum in <EM>index</EM> for the tied array assoicated with object <EM>this</EM>.
<P><DT><STRONG><A NAME="item_FETCHSIZE">FETCHSIZE this</A></STRONG><P>
<DD>
Returns the total number of items in the tied array assoicated with object <EM>this</EM>. (Equivalent to [perlfunc:scalar|scalar]).
<P><DT><STRONG><A NAME="item_STORESIZE">STORESIZE this, count</A></STRONG><P>
<DD>
Sets the total number of items in the tied array assoicated with object <EM>this</EM> to be <EM>count</EM>. If this makes the array larger then class's mapping of [perlfunc:undef|undef] should be returned for new positions. If the array becomes smaller then
entries beyond count should be deleted.
<P><DT><STRONG><A NAME="item_EXTEND">EXTEND this, count</A></STRONG><P>
<DD>
Informative call that array is likely to grow to have <EM>count</EM> entries. Can be used to optimize allocation. This method need do nothing.
<P><DT><STRONG><A NAME="item_CLEAR">CLEAR this</A></STRONG><P>
<DD>
Clear (remove, delete, ...) all values from the tied array assoicated with
object <EM>this</EM>.
<P><DT><STRONG><A NAME="item_DESTROY">DESTROY this</A></STRONG><P>
<DD>
Normal object destructor method.
<P><DT><STRONG><A NAME="item_PUSH">PUSH this, LIST</A></STRONG><P>
<DD>
Append elements of
<FONT SIZE=-1>LIST</FONT> to the array.
<P><DT><STRONG><A NAME="item_POP">POP this</A></STRONG><P>
<DD>
Remove last element of the array and return it.
<P><DT><STRONG><A NAME="item_SHIFT">SHIFT this</A></STRONG><P>
<DD>
Remove the first element of the array (shifting other elements down) and
return it.
<P><DT><STRONG><A NAME="item_UNSHIFT">UNSHIFT this, LIST</A></STRONG><P>
<DD>
Insert
<FONT SIZE=-1>LIST</FONT> elements at the begining of the array, moving
existing elements up to make room.
<P><DT><STRONG><A NAME="item_SPLICE">SPLICE this, offset, length, LIST</A></STRONG><P>
<DD>
Perform the equivalent of [perlfunc:splice|splice] on the array.
<P>
<EM>offset</EM> is optional and defaults to zero, negative values count back from the end
of the array.
<P>
<EM>length</EM> is optional and defaults to rest of the array.
<P>
<EM>LIST</EM> may be empty.
<P>
Returns a list of the original <EM>length</EM> elements at <EM>offset</EM>.
</DL>
<P>
<HR>
<H1><A NAME="CAVEATS">CAVEATS</A></H1>
<P>
There is no support at present for tied
<FONT SIZE=-1>@ISA.</FONT> There is a potential conflict between magic entries needed to notice setting of
<FONT SIZE=-1>@ISA,</FONT> and those needed to implement 'tie'.
<P>
Very little consideration has been given to the behaviour of tied arrays
when <CODE>$[</CODE> is not default value of zero.
<P>
<HR>
<H1><A NAME="AUTHOR">AUTHOR</A></H1>
<P>
Nick Ing-Simmons <A
HREF="mailto:<nik@tiuk.ti.com>"><nik@tiuk.ti.com></A>
<HR>