Comments on key/value ordering closes #2182

Author: JJ

doc/Type/Hash.pod6

@@ -12,6 +12,19 @@ C<Hash> implements C<Associative> through its inheritance of C<Map> and as such
 provides support for looking up values using keys, providing support for
 L<associative subscripting|/language/subscripts#Methods_to_implement_for_associative_subscripting>.
 
+Although the order of the hashes is guaranteed to be random in every single
+call, still successive calls to C<.keys> and C<.values> are guaranteed to return
+them in the same order:
+
+    my %orig = :1a, :2b; my %new = :5b, :6c;
+    %orig{ %new.keys } = %new.values;
+    say %orig.perl; # OUTPUT: «{:a(1), :b(5), :c(6)}␤»
+
+In this case, C<b> will always be associated to 5 and C<c> to 6; even if two
+succesive calls to C<keys> will return them in different order. Successive calls
+to any of them separately and repeatedly will always return the same order in
+any program invocation.
+
 =head1 Methods
 
 =head2 method classify-list
@@ -35,7 +48,7 @@ value respectively. A L«C<Callable>|/type/Callable» mapper will be executed
 once per each item in the C<@list>, with that item as the argument and its
 return value will be used as the mapper's value.
 
-=head3 Simple Classification
+=head3 Simple classification
 
 In simple classification mode, each mapper's value is any non-Iterable and
 represents a key to classify C<@list>'s item under:
@@ -53,7 +66,7 @@ which the C<@list>'s item will be L«C<push>ed|/routine/push». See
 L«C<.categorize-list>|/routine/categorize-list» if you wish to classify an item
 into multiple categories at once.
 
-=head3 Multi-Level Classification
+=head3 Multi-level classification
 
 In multi-level classification mode, each mapper's value is an
 L«C<Iterable>|/type/Iterable» that represents a tree of hash keys to classify
@@ -116,7 +129,7 @@ value respectively. A L«C<Callable>|/type/Callable» mapper will be executed
 once per each item in the C<@list>, with that item as the argument and its
 return value will be used as the mapper's value.
 
-=head3 Simple Categorization
+=head3 Simple categorization
 
 The mapper's value is expected to be a possibly empty list of
 non-L«C<Iterables>|/type/Iterable» that represent categories to place the value
@@ -140,7 +153,7 @@ into:
 
 Notice how some items, e.g. C<6> and C<7>, are present in several categories.
 
-=head3 Multi-Level Categorization
+=head3 Multi-level categorization
 
 In multi-level categorization, the categories produced by the mapper can are
 L<Iterables|/type/Iterable> and categorization combines features
@@ -212,11 +225,11 @@ of the old value.
 Example:
 
     my %h  = a => 1;
-    %h.push: (a => 1);                  # a => [1,1]
-    %h.push: (a => 1) xx 3 ;            # a => [1,1,1,1,1]
-    %h.push: (b => 3);                  # a => [1,1,1,1,1], b => 3
-    %h.push('c' => 4);                  # a => [1,1,1,1,1], b => 3, c => 4
-    push %h, 'd' => 5;                  # a => [1,1,1,1,1], b => 3, c => 4, d => 5
+    %h.push: (a => 1);              # a => [1,1]
+    %h.push: (a => 1) xx 3 ;        # a => [1,1,1,1,1]
+    %h.push: (b => 3);              # a => [1,1,1,1,1], b => 3
+    %h.push('c' => 4);              # a => [1,1,1,1,1], b => 3, c => 4
+    push %h, 'd' => 5;              # a => [1,1,1,1,1], b => 3, c => 4, d => 5
 
 Please note that C<Pair>s or
 L<colon pairs|/language/glossary#index-entry-Colon_Pair> as arguments to push
@@ -234,7 +247,7 @@ index:
 
     my %wc = 'hash' => 323, 'pair' => 322, 'pipe' => 323;
     (my %inv).push: %wc.invert;
-    say %inv;                           # OUTPUT: «{322 => pair, 323 => [pipe hash]}␤»
+    say %inv;                     # OUTPUT: «{322 => pair, 323 => [pipe hash]}␤»
 
 Note that such a initialization could also be written as
 
@@ -364,8 +377,8 @@ Note that in the L<Scalar> case you have to use the C<VAR> method in
 order to get correct information.
 
     my $s is dynamic = %('apples' => 5);
-    say $s.dynamic;                          # OUTPUT: «False␤»  (wrong, don't do this)
-    say $s.VAR.dynamic;                      # OUTPUT: «True␤»   (correct approach)
+    say $s.dynamic;                   # OUTPUT: «False␤»  (wrong, don't do this)
+    say $s.VAR.dynamic;               # OUTPUT: «True␤»   (correct approach)
 
 =head1 Subscript Adverbs
 
@@ -375,7 +388,8 @@ for more information).
 
 =head2 C<:exists>
 
-The adverb C<:exists> returns C<Bool::True> if a key exists in the Hash. If more than one key is supplied it returns a C<List> of C<Bool>.
+The adverb C<:exists> returns C<Bool::True> if a key exists in the Hash. If more
+than one key is supplied it returns a C<List> of C<Bool>.
 
     my %h = a => 1, b => 2;
     say %h<a>:exists;   # OUTPUT: «True␤»
@@ -395,7 +409,8 @@ Use C<:delete> to remove a C<Pair> from the C<Hash>.
 
 =head2 C<:p>
 
-The adverb C<:p> returns a C<Pair> or a List of C<Pair> instead of just the value.
+The adverb C<:p> returns a C<Pair> or a List of C<Pair> instead of just the
+value.
 
     my %h = a => 1, b => 2;
     say %h<a>:p;    # OUTPUT: «a => 1␤»