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.