NAME

SYNOPSIS

  use Hash::MultiKey;

  # tie first
  tie %hmk, 'Hash::MultiKey';

  # store
  $hmk{['foo', 'bar', 'baz']} = 1;

  # fetch
  $v = $hmk{['foo', 'bar', 'baz']};

  # exists
  exists $hmk{['foo', 'bar', 'baz']}; # true

  # each
  while (($mk, $v) = each %hmk) {
      @keys = @$mk;
      # ...
  }

  # keys
  foreach $mk (keys %hmk) {
      @keys = @$mk;
      # ...
  }

  # values
  foreach $v (values %hmk) {
      $v =~ s/foo/bar/g; # alias, modifies value in %hmk
      # ...
  }

  # delete
  $rmed_value = delete $hmk{['foo', 'bar', 'baz']};

  # clear
  %hmk = ();

  # syntactic sugar, but see risks below
  $hmk{'foo', 'bar', 'baz', 'zoo'} = 2;

  # finally, untie
  untie %hmk;

DESCRIPTION

Two multi-keys are regarded as being equal if their contents are equal, there is no need to use the same reference to refer to the same hash entry:

    $hmk{['foo', 'bar', 'baz']} = 1;
    exists $hmk{['foo', 'bar', 'baz']}; # different arrayref, but true

A given hash can have multi-keys of different lengths:

    $hmk{['foo']}               = 1; # length 1
    $hmk{['foo', 'bar', 'baz']} = 3; # length 3, no problem

In addition, multi-keys cannot be empty:

    $hmk{[]} = 1; # ERROR

The next sections document how hash-related operations work in a multi-key hash. Some parts have been copied from standard documentation, since everything has standard semantics.

    tie my (%hmk), 'Hash::MultiKey';

    $hmk{['foo', 'bar', 'baz']} = 1;

    $v = $hmk{['foo', 'bar', 'baz']};

    exists $hmk{['foo', 'bar', 'baz']}; # true

    exists $hmk{['foo']}; # false

    while (($mk, $v) = each %hmk) {
        @keys = @$mk;
        # ...
    }

    while (($mk, $v) = each %hmk) {
        print "@$mk\n";
        delete $hmk{$mk}; # this is safe
    }

    foreach $mk (keys %hmk) {
        @keys = @$mk;
        # ...
    }

   s/foo/bar/g foreach values %hmk;       # modifies %hmk's values
   s/foo/bar/g foreach @hash{keys %hash}; # same

    foreach $mk (keys %hmk) {
        delete $hmk{$mk};
    }

    delete @hmk{keys %hmk};

    %hmk = (); # clear %hmk, the efficient way

    untie %hmk;

SYNTACTIC SUGAR

    $hash{'see', '$;', 'in', 'perldoc', 'perlvar'} = 1;

If the key is a string instead of an arrayref the underlying code splits it using $; (see why in MOTIVATION) and from then on the key is an arrayref as any true multi-key. Thus, the assigment above is equivalent to

    $hash{['see', '$;', 'in', 'perldoc', 'perlvar']} = 1;

once it has been processed.

You don't need to split the string back while iterating with "each()" or "keys()", it already comes as an arrayref of strings.

Nevertheless take into account that this is slower, and broken if any of the components contains $;. It is supported just for consistency's sake.

MOTIVATION

    $hash{'foo', 'bar', 'baz'} = 1;

it joins "('foo', 'bar', 'baz')" with $; to obtain the actual key, thus resulting in a string. Then you retrieve the components of the multi-key like this:

    while (($k, $v) = each %hash) {
        @keys = $k eq '' ? ('') : split /$;/, $k, -1;
        # ...
    }

Since $; is "\034" by default, a non-printable character, this is often enough.

Sometimes, however, that's not the most convenient way to work with multi-keys. For instance, that magic join doesn't work with arrays:

    @array = ('foo', 'bar', 'baz');
    $hash{@array} = 1; # WARNING, @array evaluated in scalar context!

You could be dealing with binary data. Or you could be writing a public module that uses user input in such a hash and don't want to rely on input not coming with $;, or don't want to document such an obscure, gratuitous, and implementation dependent constraint.

In such cases, Hash::MultiKey can help.

AUTHORS

THANKS

Philip Monsen reported some tests of Hash::MultiKey 0.05 failed with perl 5.8.4.

COPYRIGHT and LICENSE

SEE ALSO