NAME

Array::Virtual - A perl extension providing disk based arrays implemented via tied hashes

VERSION

This documentation covers version 0.01 of Array::Virtual released July, 2001.

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 NDBM_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 file called diskname.array.db or a pair of files diskname.array.dir and diskname.array.pag, depending on the verion of NDBM_File you are using. Any path is preserved through the call, but .array.... is always appended. (This module puts on the array extension, NDBM_File puts on the other extension(s).)

If the disk file(s) for the array already exists, it 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 file(s) either inside or outside of perl. Say something like unlink \<diskname.array.*\>.

If the file(s) cannot be found, it(they) is(are) created with the given permissions if supplied (or with 0644 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 NDBM_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. This Array::Virtual restores them as if they were never lost. You might consider this a feature. It does save time.

NOTE WELL

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.

EXPORT

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

AUTHOR

Phil Crow crow@qns.com

COPYRIGHT

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