NAME
Tie::Array::PackedC - Tie a Perl array to a C-style array (packed; elements of a single, simple data type)
SYNOPSIS
use Tie::Array::PackedC qw(packed_array packed_array_string);
my $ref=packed_array(1,2,3,4);
my $ref2=packed_array_string(my $s,1,2,3,4);
use Tie::Array::PackedC Double=>'d';
tie my @array,'Tie::Array::PackedC::Double',1..10;
$array[0]=1.141;DESCRIPTION
Provides a perl array interface into a string containing a C style array. In other words the string is equivelent to the string that would be returned from the equivelent pack command (defaulting to pack type "l!") using a normal array of the same values. Eg:
my @foo=(1..10);
my $string=pack "l!*",@foo;leaves $string in basically the same condition as
my (@foo,$string);
tie @foo,'Tie::Array::PackedC',$string,1..10;Its only basically the same and not exactly the same because the tie version may be longer due to preallocation.
USAGE
The basic usage is
tie @array,'Tie::Array::PackedC',$string,@initialize;This will tie @array to $string. So modifying the array will actually cause the string to change. If $string is undef then it will automatically be set to "", otherwise the initial contents of the string will be untouched. (It will however be extended according to the preallocation below.) Any values @initialize are treated as though an immediate
@array[0..$#initilize]=@initialize;occured. This means that
my ($s,@a)=pack "l!*",1..5;
tie @a,'Tie::Array::PackedC',$s,reverse 1..4;wil result in "@a" being "4 3 2 1 5".
If no $string is provided then an anonymous string is used to bind to. This string can be obtained by saying
print tied(@a)->string;Note that the underlying object is a blessed reference to the string passed in. The difference between saying
${tied(@a)}and the string method is that the former will return the string by copy and it will be exactly the size of the array, the latter could be signifigantly longer due to preallocation.
There is also a utility method to dump the string/array in hex that is invoked accordingly
tied(@a)->hex_dump;this dumps the full underlying string in hex bytes grouped according to the size of the packed element, and is in the byte order as packed.
A NOTE ABOUT undef
A normal array returns undef when you access an element that has not been explicitly stored to. Arrays tied using this class do not behave in the same way. If an index is within the size of the array but has not been assigned to will return Tie::Array::PackedC::NULL a constant defined as the result of
pack PACK,"";Any index that is outside of the array will return undef as expected.
PREALLOCATION
In order to avoid having to extend the string too often a preallocation strategy is used. This means that the underlying string is prefilled with a predetermined number of items worth of NULL each time a STORE accesses an element not currently mappable to the string. This allocation happens in terms of blocks which are of a size equal to a predetermined multiple of the size of each element. The number elements added each time the array is extended will be a multiple of the block size and will not be less than %20 of the current size.
NOTE I currently consider the preallocation mechanism to be less than it should be and will most likely figure out a better way to do it later. Please do not assume that the preallocation mechanism will stay the same.
CLASS FACTORY
The class uses a form of templating to provide a way to produce classes that are just as fast as the current version, but use different pack formats, or allocation block size. This is done at compile time by a special import mechanism. This mechanism works like this:
use Tie::Array::PackedC %Name% => %PackType%;Where %Name% must match /[A-Z]/ and %PackType% is one of the pack formats. (The behaviour of the class is only well defined for types that are of fixed size that are byte aligned.)
If the module is used as follows
use Tie::Array::PackedC Double => 'd';then a new class called Tie::Array::PackedC::Double is created that produces a tied array of packed doubles. Thus the default implementation and usage
use Tie::Array::PackedC;is almost exactly equivelent to
use Tie::Array::PackedC NativeLong => 'l!';with the exceptions being its name and its import behaviour, the later of which is different in that it does not support the class factory import.
METHODs
- string()
-
Returns the string represnting the array. This is not necessarily the same as the string passed into the array, which may be longer.
- hex_dump()
-
Prints to STDOUT a hex dump of the underlying string.
- trim()
-
Frees up any preallocated but unused memory. This is useful if you know you will not be performing any more store operations on the string.
PACKAGE CONSTANTS
The base package and each of the children it produces in factory mode have the following constants defined, (adjust name accordingly)
- Tie::Array::PackedC::PACK
-
Returns the pack format used by the class. This will always have a * at the end, regardless as to what was provided by the user.
- Tie::Array::PackedC::SIZE
-
The number of bytes that a single element of PACK takes up.
- Tie::Array::PackedC::ALLOC
-
Used by the preallocation system to determine chunk size of preallocation. Currently the underlying string will always satisfy
length($string) % Tie::Array::PackedC::ALLOC == 0
These are not exportable, but they can be accessed by fully qualified name.
EXPORT
Normally Tie::Array::PackedC and its produced classes do not export. However two utility subroutines are provided which can be exported on request using the conventional syntax.
Note that the class factory approach can not be mixed with the export approach in the same use statement. However this means that you can do this:
use Tie::Array::PackedC Double => 'd';
use Tie::Array::PackedC::Double qw(packed_array);and have the generated class export its utility subs.
- packed_array(LIST)
-
Returns a reference to an array tied to an anonymous string. The LIST is used to initialize the array.
- packed_array_string(STR, LIST)
-
Returns a reference to an array tied to a string provided. The LIST is used to initialize the array.
AUTHOR
demerphq, (yves at cpan dot org).
SEE ALSO
perl, perltie, and Tie::Array
LICENCE
Released under the same terms as perl itself.