Document Hash.classify-list

Closes #916

Author: zoffixznet

doc/Type/Hash.pod6

@@ -311,6 +311,74 @@ It is not, however, possible to do in-place editing of hash keys, even in the ca
 
 =head1 Methods
 
+=head2 method classify-list
+
+Defined as:
+
+    multi method classify-list(&mapper, *@list, :&as) returns Hash:D
+    multi method classify-list(%mapper, *@list, :&as) returns Hash:D
+    multi method classify-list(@mapper, *@list, :&as) returns Hash:D
+
+Populates a L«C<Hash>|/type/Hash by classifying the
+possibly-empty C<@list> of values using the given C<mapper>, optionally
+altering the values using the C<:&as> L«C<Callable>|/type/Callable». The
+C<@list> cannot be lazy.
+
+The mapper can be a L«C<Callable>|/type/Callable» that takes a single argument,
+an L«C<Associative>|/type/Associative», or an L«C<Iterable>|/type/Iterable».
+With L«C<Associative>|/type/Associative» and an L«C<Iterable>|/type/Iterable»
+mappers, the values in the C<@list> represent the key and index of the mapper's
+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
+
+In simple classification mode, each mapper's value is any non-Iterable and
+represents a key to classify C<@list>'s item under:
+
+    say % .classify-list: { $_ %% 2 ?? 'even' !! 'odd' }, ^10;
+    # OUTPUT: {even => [0 2 4 6 8], odd => [1 3 5 7 9]}
+
+    my @mapper = <zero one two three four five>;
+    my %hash = foo => 'bar';
+    say %hash.classify-list: @mapper, 1, 2, 3, 4, 4;
+    # OUTPUT: {foo => bar, four => [4 4], one => [1], three => [3], two => [2]}
+
+The mapper's value is used as the key of the L«C<Hash>|/type/Hash» to
+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
+
+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
+C<@list>'s item under:
+
+    say % .classify-list: {
+        [
+            (.is-prime ?? 'prime' !! 'non-prime'),
+            ($_ %% 2   ?? 'even'  !! 'odd'      ),
+        ]
+    }, ^10;
+    # OUTPUT:
+    # {
+    #     non-prime => {
+    #         even => [0 4 6 8],
+    #         odd  => [1 9]
+    #     },
+    #     prime => {
+    #         even => [2],
+    #         odd  => [3 5 7]
+    #     }
+    # }
+
+B<NOTE:> each of those L«C<Iterables>|/type/Iterable»
+must have the same number of elements, or the method will throw an exception.
+This restriction exists to avoid conflicts when the same key is a
+leaf of one value's classification but a node of another value's classification.
+
 =head2 method push
 
 Defined as: