/ 
Tie-Multidim-0.04
River stage zero No dependents
/ Tie::Multidim

NAME

Tie::Multidim - "tie"-like multidimensional data structures

SYNOPSIS

use Tie::Multidim;
my $foo = new Tie::Multidim \%h, '%@%';
$foo->[2]{'die'}[4] = "isa";

DESCRIPTION

This module implements multi-dimensional data structures on a hash. $foo->[2]{'die'}[4] gets "mapped" to $bar{"2;die;4"}, where the ';' is actually $SUBSEP ($;), and %bar is a hash you provide.

It is particularly useful in two, not disjoint, situations:

1. the data space (matrix, if you prefer) is sparsely populated;
2. the hash into which the data is mapped is tied.

This illustrates (1):

my %matrix; # hash to store the data in.
local $; = ' ';
my $foo = new Tie::Multidim \%matrix, '@@'; # array-of-arrays.

print $foo->[5432][9876];
# prints the value of  $matrix{"5432 9876"}.

This illustrates (2):

my %matrix;
tie %matrix, 'Matrix';  # some hashtie-able class.
local $; = ";"; # gets remembered by the object.
my $foo = new Tie::Multidim \%matrix, '%@%';
# 3-level structure: hash of arrays of hashes.

$foo->{'human'}[666]{'beast'} = "value";

# causes a call to
sub Matrix::STORE {
  my( $self, $index, $value ) = @_;
  my( $x, $y, $z ) = split $;, $index;
  # with $x = 'human', $y = 666, and $z = 'beast'.
}

METHODS

new

This is the constructor.

The first argument is a hash-reference. This hash will be used by the Tie::Multidim object to actually store the data. The reference can be to an anonymous hash, to a normal hash, or to a tied hash. Tie::Multidim doesn't care, as long as it supports the normal hash get and set operations (STORE and FETCH methods, in TIEHASH terminology).

The second argument is a string containing '@' and '%' characters (a al function prototypes). The multidimensional data structure will be constructed to have as many dimensions as there are characters in this string; and each dimension will be of the type indicated by the character. '@%' is an array of hashes; '%@' is a hash of arrays; and so on.

storage

This returns the same hash reference that was passed as the first argument to the constructor. Not exactly a method, it must be called as a package function, and passed the multidim reference.

$foo = new Tie::Multidim, \%h, '@@';
$hashref = Tie::Multidim::storage( $foo );
# same effect as:
$hashref = \%h;

AUTHOR

jdporter@min.net (John Porter)

COPYRIGHT

This module is free software; you may redistribute it and/or modify it under the same terms as Perl itself.