
    Tie::Multidim - "tie"-like multidimensional data structures
    (Version 0.03 -- August 1999)


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


    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'.
     }



    The constructor: new

    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.


    You can get the hash reference that was passed as the first
    argument to the constructor, by calling the "object" method:

            my %h;
            my $foo = new Tie::Multidim, \%h, '@@';
            my $hashref = $m->object;
            # same effect as
            my $hashref = \%h;


    jdporter@min.net (John Porter)

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

