# -*- cperl -*-

=head1 Perl Hash PMC

=head2 Synopsis

  ...


=head2 Creation

As with other PMC's, create the hash with

    new P0, .PerlHash

=head2 Accessing Elements

To store elements on the hash use

    set P0["key"], "value"

Note that you can use registers in the same way:

    new P0, .PerlHash
    set S0, "one"
    set S1, "two"
    set P0[S0], 1     # $P0{one} = 1
    set P0[S1], 2     # $P0{two} = 2

To get the element use it in the opposite way:

    set I1, P0["one"]   # $I1 = $P0{one}

Notice that hashes are polymorphic on the value it holds.

When using a key which does not exist in the hash, the value returned
depends on the register used to retrieve the element.

  set I0, P1["qwerty"]  # I0 = 0
  set N0, P1["qwerty"]  # N0 = 0.000
  set S0, P1["qwerty"]  # S0 = ""
  set P0, P1["qwerty"]  # typeof(P0) = PerlUndef

You can check if an hash element exists before accessing it, using the
C<exists> command:

  exists I0, P0["a"]

This example will set the value one in register C<I0> if the key
exists, the value zero if it does not exist.

Notice that this tests if there is anything. In fact, the C<exists>
command will return true if the element in that position if a
PerlUndef PMC. To check if that element is defined, use the C<defined>
command:

  defined I0, P0["a"]

=head2 Removing Elements

You can remove (or delete) an element from the hash using the
C<delete> command:

  delete P0["a"]

This means that:

  new P0, .PerlHash
  set P0["a"], 2
  delete P0["a"]
  exists I0, P0["a"]

will put the value zero on register C<I0>.

=head2 Size of the Hash

To get the number of keys (size of the hash) use

    set I0, P0

where C<P0> is the Perl Hash PMC and C<I0> the register where to store
the hash size. You can use an Perl Hash PMC on an C<if> or C<unless>
command, where it will be checked for the number of elements.

=head2 Cloning

As other PMCs, you can clone Perl hashes. If you try something like

    new P0, .PerlHash
    set P0["a"], 1
    set P0["b"], 2

    clone P1, P0

C<P1> is a copy of C<P0>, where you can do whatever you want without
changing the other hash.


=head2 TODO

 - Compound keys
 - Write Synopsis

=cut