start to document Hash

Author: moritz

lib/Hash.pod

@@ -0,0 +1,72 @@
+=begin pod
+
+=TITLE class Hash
+
+    class Hash is EnumMap { }
+
+A Hash is a mutable mapping from keys to values (called I<dictionary>,
+I<hash table> or I<map> in other programming languages). The values are
+all scalar containers, which means you can assign to them.
+
+Hashes are usually stored in variables with the percent C<%> sigil.
+
+Hash elements are accessed by key via the C<{ }> postcircumfix operator:
+
+    my $home = %*ENV{'HOME'};
+
+For literal string keys without whitespace, C<< < > >> can be used instead:
+
+    my $home = %*ENV<HOME>;
+
+You can add new pairs simply by assigning to such an element access:
+
+    my %h;
+    %h{'new key'} = 'new value';
+
+=head1 Hash assignment
+
+Assigning a list of elements to a hash variable first empties the variable,
+and then iterates the elements of right-hand side. If an element is an
+L<Enum> (or of a subclass like L<Pair>), its key is taken as a new hash key,
+and its value as the new hash value for that key. Otherwise the value
+is coereced to L<Str> and used as a hash key, while the next element of the
+list is taken as the corresponding value.
+
+    my %h = 'a', 'b', c => 'd', 'e', 'f';
+    # same as
+    my %h = a => 'b', c => 'd', e => 'f';
+    # or
+    my %h = <a b c d e f>;
+
+If an L<Enum> is enocuntered where a value is expected, it is used as a
+hash value:
+
+    my %h = 'a', 'b' => 'c';
+    say %h<a>.WHAT;     # Pair();
+    say %h<a>.key;      # b
+
+If the same key appears more than once, the value associated with its last
+occurence is stored in the hash:
+
+    my %h = a => 1, a => 2;
+    say %h<a>;          # 2
+
+=head1 Methods
+
+=head2 push
+
+    multi method push(Hash:D: *@new)
+
+Adds the C<@new> elements to the hash with the same semantics as hash
+assignment, but with three exceptions:
+
+=item the hash isn't emptied first, ie old pairs are not deleted
+
+=item if a key already exists in the hash, and the corresponding value is an
+L<Array>, the new value is pushed onto the arary (instead of replacing it).
+
+=item if a key already exists in the hash, and the corresponding value is not
+an L<Array>, old and new value are both placed into an array in the place
+of the old value.
+
+=end pod