Start rewriting of the hashmap language page

Follows #1682 advice of moving the top-heavy part of the Hash type to
this page. That part has been rewritten in similarity to Array, by
making references to its general behavior using parallelisms between
them. This also goes towards fulfillment of the roadmap #114

Author: JJ

doc/Language/hashmap.pod6

@@ -8,17 +8,303 @@
 
 TBD
 
-=head1 Mutability of associative data structures
+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.
 
-TBD
+Hashes are usually stored in variables with the percent C<%> sigil.
 
-=head1 Working with associative data structures
+Hash elements are accessed by key via the C<{ }> postcircumfix operator:
 
-TBD
+    say %*ENV{'HOME', 'PATH'}.perl;
+    # OUTPUT: «("/home/camelia", "/usr/bin:/sbin:/bin")␤»
 
-=head1 Defining your own associative structures
+The general L<Subscript|/language/subscripts> rules apply providing shortcuts
+for lists of literal strings, with and without interpolation.
 
-TBD
+    my %h = oranges => 'round', bananas => 'bendy';
+    say %h<oranges bananas>;
+    # OUTPUT: «(round bendy)␤»
+
+    my $fruit = 'bananas';
+    say %h«oranges "$fruit"»;
+    # OUTPUT: «(round bendy)␤»
+
+You can add new pairs simply by assigning to an unused key:
+
+    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 the right-hand side. If an element is a
+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 coerced 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 a L<Pair> is encountered where a value is expected, it is used as a
+hash value:
+
+    my %h = 'a', 'b' => 'c';
+    say %h<a>.^name;            # OUTPUT: «Pair␤»
+    say %h<a>.key;              # OUTPUT: «b␤»
+
+If the same key appears more than once, the value associated with its last
+occurrence is stored in the hash:
+
+    my %h = a => 1, a => 2;
+    say %h<a>;                  # OUTPUT: «2␤»
+
+To assign a hash to a variable which does not have the C<%> sigil, you may use the C<%()> hash
+constructor:
+
+    my $h = %( a => 1, b => 2 );
+    say $h.^name;               # OUTPUT: «Hash␤»
+    say $h<a>;                  # OUTPUT: «1␤»
+
+B<NOTE:> Hashes can also be constructed with C<{ }>.
+It is recommended to use the C<%()> hash constructor, as braces
+are reserved for creating L<Block|/type/Block> objects and therefore braces
+only create Hash objects in specific circumstances.
+
+If one or more values reference the topic variable, C<$_>, the
+right-hand side of the assignment will be interpreted as a L<Block|/type/Block>,
+not a Hash:
+
+=begin code :skip-test
+my @people = [
+    %( id => "1A", firstName => "Andy", lastName => "Adams" ),
+    %( id => "2B", firstName => "Beth", lastName => "Burke" ),
+    # ...
+];
+
+sub lookup-user (Hash $h) { #`(Do something...) $h }
+
+my @names = map {
+    # While this creates a hash:
+    my  $query = { name => "$person<firstName> $person<lastName>" };
+    say $query.^name;      # OUTPUT: «Hash␤»
+
+    # Doing this will create a Block. Oh no!
+    my  $query2 = { name => "$_<firstName> $_<lastName>" };
+    say $query2.^name;       # OUTPUT: «Block␤»
+    say $query2<name>;       # fails
+
+    CATCH { default { put .^name, ': ', .Str } };
+    # OUTPUT: «X::AdHoc: Type Block does not support associative indexing.␤»
+    lookup-user($query);   # Type check failed in binding $h; expected Hash but got Block
+}, @people;
+=end code
+
+This would have been avoided if you had used the C<%()> hash constructor.
+Only use curly braces for creating Blocks.
+
+=head2 Slices
+
+You can assign to multiple keys at the same time with a slice.
+
+    my %h; %h<a b c> = 2 xx *; %h.perl.say;  # OUTPUT: «{:a(2), :b(2), :c(2)}␤»
+    my %h; %h<a b c> = ^3;     %h.perl.say;  # OUTPUT: «{:a(0), :b(1), :c(2)}␤»
+
+=head2 Non-string keys (object hash)
+
+X<|non-string keys>
+X<|object hash>
+X<|:{}>
+
+By default keys in C<{ }> are forced to strings. To compose a hash with
+non-string keys, use a colon prefix:
+
+    my $when = :{ (now) => "Instant", (DateTime.now) => "DateTime" };
+
+Note that with objects as keys, you often cannot use the C«<...>» construct
+for key lookup, as it creates only strings and
+L<allomorphs|/language/glossary#index-entry-Allomorph>. Use the C«{...}»
+instead:
+
+    :{  0  => 42 }<0>.say;   # Int    as key, IntStr in lookup; OUTPUT: «(Any)␤»
+    :{  0  => 42 }{0}.say;   # Int    as key, Int    in lookup; OUTPUT: «42␤»
+    :{ '0' => 42 }<0>.say;   # Str    as key, IntStr in lookup; OUTPUT: «(Any)␤»
+    :{ '0' => 42 }{'0'}.say; # Str    as key, Str    in lookup; OUTPUT: «42␤»
+    :{ <0> => 42 }<0>.say;   # IntStr as key, IntStr in lookup; OUTPUT: «42␤»
+
+Note: Rakudo implementation currently erroneously applies
+L<the same rules|/routine/{ }#(Operators)_term_{_}> for C<:{ }> as it does for C<{ }>
+and can construct a L<Block> in certain circumstances. To avoid that, you can
+instantiate a parameterized Hash directly. Parameterization of C<%>-sigiled variables
+is also supported:
+
+    my Num %foo1      = "0" => 0e0; # Str keys and Num values
+    my     %foo2{Int} =  0  => "x"; # Int keys and Any values
+    my Num %foo3{Int} =  0  => 0e0; # Int keys and Num values
+    Hash[Num,Int].new: 0, 0e0;      # Int keys and Num values
+
+Now if you want to define a hash to preserve the objects you are using
+as keys I<as the B<exact> objects you are providing to the hash to use as keys>,
+then object hashes are what you are looking for.
+
+    my %intervals{Instant};
+    my $first-instant = now;
+    %intervals{ $first-instant } = "Our first milestone.";
+    sleep 1;
+    my $second-instant = now;
+    %intervals{ $second-instant } = "Logging this Instant for spurious raisins.";
+    for %intervals.sort -> (:$key, :$value) {
+        state $last-instant //= $key;
+        say "We noted '$value' at $key, with an interval of {$key - $last-instant}";
+        $last-instant = $key;
+    }
+
+This example uses an object hash that only accepts keys of type L<Instant> to
+implement a rudimentary, yet type-safe, logging mechanism. We utilize a named
+L<state|/language/variables#The_state_Declarator>
+variable for keeping track of the previous C<Instant> so that we can provide an interval.
+
+The whole point of object hashes is to keep keys as objects-in-themselves.
+Currently object hashes utilize the L<WHICH|/routine/WHICH> method of an object, which returns a
+unique identifier for every mutable object. This is the keystone upon which the object
+identity operator (L<===>) rests. Order and containers really matter here as the order of
+C<.keys> is undefined and one anonymous list is never L<===> to another.
+
+    my %intervals{Instant};
+    my $first-instant = now;
+    %intervals{ $first-instant } = "Our first milestone.";
+    sleep 1;
+    my $second-instant = now;
+    %intervals{ $second-instant } = "Logging this Instant for spurious raisins.";
+    say ($first-instant, $second-instant) ~~ %intervals.keys;       # OUTPUT: «False␤»
+    say ($first-instant, $second-instant) ~~ %intervals.keys.sort;  # OUTPUT: «False␤»
+    say ($first-instant, $second-instant) === %intervals.keys.sort; # OUTPUT: «False␤»
+    say $first-instant === %intervals.keys.sort[0];                 # OUTPUT: «True␤»
+
+Since C<Instant> defines its own comparison methods, in our example a sort according to
+L<cmp> will always provide the earliest instant object as the first element in the L<List>
+it returns.
+
+If you would like to accept any object whatsoever in your hash, you can use L<Any>!
+
+    my %h{Any};
+    %h{(now)} = "This is an Instant";
+    %h{(DateTime.now)} = "This is a DateTime, which is not an Instant";
+    %h{"completely different"} = "Monty Python references are neither DateTimes nor Instants";
+
+There is a more concise syntax which uses binding.
+
+    my %h := :{ (now) => "Instant", (DateTime.now) => "DateTime" };
+
+The binding is necessary because an object hash is about very solid, specific objects,
+which is something that binding is great at keeping track of but about which assignment doesn't
+concern itself much.
+
+=head2 Constraint value types
+
+Place a type object in-between the declarator and the name to constraint the type
+of all values of a C<Hash>. Use a L<subset|/language/typesystem#subset> for
+constraints with a where-clause.
+
+    subset Powerful of Int where * > 9000;
+    my Powerful %h{Str};
+    put %h<Goku>   = 9001;
+    try {
+        %h<Vegeta> = 900;
+        CATCH { when X::TypeCheck::Binding { .message.put } }
+    }
+
+    # OUTPUT:
+    # 9001
+    # Type check failed in binding assignval; expected Powerful but got Int (900)
+
+=head1 Looping over hash keys and values
+
+A common idiom for processing the elements in a hash is to loop over the
+keys and values, for instance,
+
+    my %vowels = 'a' => 1, 'e' => 2, 'i' => 3, 'o' => 4, 'u' => 5;
+    for %vowels.kv -> $vowel, $index {
+      "$vowel: $index".say;
+    }
+
+gives output similar to this:
+
+=for code :skip-test
+a: 1
+e: 2
+o: 4
+u: 5
+i: 3
+
+where we have used the C<kv> method to extract the keys and their respective
+values from the hash, so that we can pass these values into the loop.
+
+Note that the order of the keys and values printed cannot be relied upon;
+the elements of a hash are not always stored the same way in memory for
+different runs of the same program.  Sometimes one wishes to process the
+elements sorted on, e.g. the keys of the hash.  If one wishes to print the
+list of vowels in alphabetical order then one would write
+
+    my %vowels = 'a' => 1, 'e' => 2, 'i' => 3, 'o' => 4, 'u' => 5;
+    for %vowels.sort(*.key)>>.kv -> ($vowel, $index) {
+      "$vowel: $index".say;
+    }
+
+which prints
+
+=for code :skip-test
+a: 1
+e: 2
+i: 3
+o: 4
+u: 5
+
+and is in alphabetical order as desired.  To achieve this result, we sorted
+the hash of vowels by key (C<%vowels.sort(*.key)>) which we then ask for its
+keys and values by applying the C<.kv> method to each element via the unary
+C< >> > hyperoperator resulting in a L<List> of key/value lists.  To extract
+the key/value the variables thus need to be wrapped in parentheses.
+
+An alternative solution is to flatten the resulting list.  Then the key/value
+pairs can be accessed in the same way as with plain C<.kv>:
+
+    my %vowels = 'a' => 1, 'e' => 2, 'i' => 3, 'o' => 4, 'u' => 5;
+    for %vowels.sort(*.key)>>.kv.flat -> $vowel, $index {
+      "$vowel: $index".say;
+    }
+
+You can also loop over a C<Hash> using
+L<destructuring|/type/Signature#Destructuring_Parameters>.
+
+=head2 In place editing of values
+
+There may be times when you would like to modify the values of a hash while iterating over them.
+
+    my %answers = illuminatus => 23, hitchhikers => 42;
+    # OUTPUT: «hitchhikers => 42, illuminatus => 23»
+    for %answers.values -> $v { $v += 10 }; # Fails
+    CATCH { default { put .^name, ': ', .Str } };
+    # OUTPUT: «X::AdHoc: Cannot assign to a readonly variable or a value␤»
+
+This is traditionally accomplished by sending both the key and the value as
+follows.
+
+    my %answers = illuminatus => 23, hitchhikers => 42;
+    for %answers.kv -> $k,$v { %answers{$k} = $v + 10 };
+
+However, it is possible to leverage the signature of the block in order to
+specify that you would like read-write access to the values.
+
+    my %answers = illuminatus => 23, hitchhikers => 42;
+    for %answers.values -> $v is rw { $v += 10 };
+
+It is not, however, possible to do in-place editing of hash keys, even in the
+case of object hashes.
 
 
 =end pod