NAME

Array::Virtual - Provides disk based arrays implemented via tied hashes

VERSION

This documentation covers version 0.04 of Array::Virtual released May, 2002.

SYNOPSIS

   use Array::Virtual;

   tie @myarray, "Array::Virtual", "diskname", 0664;
   push @myarray, "value";
   my $stackpop = pop @myarray;
   unshift @myarray, "value1";
   my $queuefront = shift @myarray;
   .
   .
   .
   etc.

DESCRIPTION

This module allows a user to tie an array to a disk file. The actual storage scheme is a hash tied via SDBM_File.

The module optimizes push, pop, shift, and unshift for speed. For SPLICE, it uses the method inherited from Tie::Array. Splicing requires moving elements around. Since there is really no short cut for that, there is not a real way to optimize this routine, thus it is borrowed. Genuine DELETE is not yet supported. Attempting to call DELETE will result in the inherited croak from Tie::Array.

Once you issue a line like tie @myarray, "Virtual", "diskname", 0664; you may use @myarray just as you would any other array. The array will be stored in a pair of files called diskname.array.dir and diskname.array.pag. Any path is preserved through the call, but .array.... is always appended. (This module puts on the array extension, SDBM_File puts on the other extensions.)

If the disk files for the array already exists, the array is opened and its contents are the same as the last time the disk array was used. If you want to purge the disk array, simply unlink its files either inside or outside of perl. Say something like unlink \<diskname.array.*\>.

If the files cannot be found, they are created with the given permissions if supplied (or with 0666 modified by your umask by default).

DEPENDENCIES

This package inherits from Tie::Array from the standard distribution.

It uses the standard pragma strict.

In addition, it uses Fcntl out of laziness, and SDBM_File out of necessity. Both of these are from the standard distribution.

BUGS

Normally when you down size an array, you permanently loose the elements which are outside the new range. Later enlarging is not supposed to recover the lost elements. Array::Virtual restores them as if they were never lost. You might consider this a feature. It does save time.

This module never uses arrays in its implementation. It does not pay any attention to the deprecated $[ variable which allows arrays to begin at non-zero indices. If you use this variable, Array::Virtual will likely become confused.

CORRECTED BUGS

Negative indices were not handled at all. All attempts to say things like $array[-1] yielded unpredictable results. Corrected in version 0.04.

Storing in slots outside the current range failed in most cases. For example, if an array was empty the following commands didn't work as expected: push @array, 1; push @array, 2; $array[7] = 3; The results of the last statement were unexpected and unpredictable. Corrected in version 0.04.

EXPORT

This module exports nothing. Everything in it is called transparently by the tie magician.

AUTHOR

Phil Crow philcrow2000@yahoo.com

COPYRIGHT

Copyright (c) 2001-2002 Philip Crow. All rights reserved. This program is free and may be redributed under the same terms as Perl itself.