NAME

Tie::Array::Packed - store arrays in memory efficiently as packed strings

SYNOPSIS

use Tie::Array::Packed;

my (@foo, @bar);
tie @foo, Tie::Array::Packed::Integer;
tie @bar, Tie::Array::Packed::DoubleNative;

$foo[12] = 13;
$bar[1] = 4.56;

pop @foo;
@some = splice @bar, 1, 3, @foo;

DESCRIPTION

This module provides an implementation for tied arrays that uses as storage a Perl scalar where all the values are packed as if the pack builtin had been used.

All the values on a Tie::Array::Packed array are of the same value (integers, shorts, doubles, etc.)

The module is written in XS for speed. Tie::Array::Packed arrays are aproximately 15 times slower than native ones (for comparison to a pure Perl implementation, arrays tied with Tie::Array::PackedC are around 60 times slower than native arrays).

On the other hand, packed arrays use between 4 and 12 times less memory that the native ones.

USAGE

Tie::Array::Packed defines a set of classes that can be used to tie arrays. The classes have names of the form:

Tie::Array::Packed::<Type>

and are as follows:

                                         pack      C
          class name                    pattern   type
--------------------------------------------------------------------
Tie::Array::Packed::Char                   c     char
Tie::Array::Packed::UnsignedChar           C     unsigned char
Tie::Array::Packed::NV                     F     NV
Tie::Array::Packed::Number                 F     NV
Tie::Array::Packed::FloatNative            f     float
Tie::Array::Packed::DoubleNative           d     double
Tie::Array::Packed::Integer                i     IV
Tie::Array::Packed::UnsignedInteger        I     UV
Tie::Array::Packed::IntegerNative          i!    int
Tie::Array::Packed::UnsignedIntegerNative  I!    unsigned int
Tie::Array::Packed::ShortNative            s!    short
Tie::Array::Packed::UnsignedShortNative    S!    unsigned short
Tie::Array::Packed::LongNative             l!    long
Tie::Array::Packed::UnsignedLongNative     L!    unsigned long
Tie::Array::Packed::UnsignedShortNet       n     -
Tie::Array::Packed::UnsignedShortBE        n     -
Tie::Array::Packed::UnsignedLongNet        N     -
Tie::Array::Packed::UnsignedLongBE         N     -
Tie::Array::Packed::UnsignedShortVax       v     -
Tie::Array::Packed::UnsignedShortLE        v     -
Tie::Array::Packed::UnsignedLongVax        V     -
Tie::Array::Packed::UnsignedLongLE         V     -

if your C compiler has support for 64bit long long integers, then this two classes will be also available:

                                         pack      C
          class name                    pattern   type
--------------------------------------------------------------------
Tie::Array::Packed::LongLong                q     long long
Tie::Array::Packed::UnsignedLongLong        Q     unsigned long long

The tie interface for those clases is:

tie @foo, Tie::Array::Packed::Integer;
tie @foo, Tie::Array::Packed::Integer, $init_string, @values

(Tie::Array::Packed::Integer is used for example, the same applies to the rest of the classes).

When a scalar value $init_string is passed as an argument it is used as the initial value for the storage scalar.

Additional arguments are used to initialize the array, for instance:

tie @foo, Tie::Array::Packed::Char, '', 1, 2, 3;
print "@foo"; # prints "1 2 3"

tie @bar, Tie::Array::Packed::Char, 'hello';
print "@bar"; # prints "104 101 108 108 111"

tie @doz, Tie::Array::Packed::Char, 'hello', 1, 2, 3;
print "@doz"; # prints "1 2 3 108 111";

The underlaying storage scalar can be accessed unreferencing the object returned by tie:

my $obj = tied(@foo);
print "storage: ", $$obj;

METHODS

Those are the methods provided by the classes defined on the module:

Tie::Array::Packed::Integer->make()

Tie::Array::Packed::Integer->make(@init_values)

This class method returns a reference to and array tied to the class.

Note that the returned array is not blessed into any package.

Tie::Array::Packed::Integer->make_with_packed($init_string)

similar to the method before but get an additional argument to initialize the storage scalar.

tied(@foo)->packer

returns the pack template in use for the elements of the tied array @foo.

BUGS

This is an early release, critical bugs may appear.

Only tested on Linux, though it should work on any OS with a decent C compiler.

To report bugs on this module email me to the address that appears below or use the CPAN RT system.

SEE ALSO

Documentation for Perl builtins pack and vec.

Tie::Array::PackedC offers very similar functionality, but it is implemented in pure Perl and so it is slower.

Array::Packed is implemented in C but only supports integer values.

COPYRIGHT AND LICENSE

Copyright (C) 2006 by Salvador Fandiño (sfandino@yahoo.com).

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm Tie::Array::Packed

perl -MCPAN -e shell
install Tie::Array::Packed