Documentation for method categorize-list assembled from the following types:

class Hash

From Hash

(Hash) method categorize-list

Defined as:

multi method categorize-list(&mapper, *@list, :&as --> Hash:D)
multi method categorize-list(%mapper, *@list, :&as --> Hash:D)
multi method categorize-list(@mapper, *@list, :&as --> Hash:D)

Populates a Hash by classifying the possibly-empty @list of values using the given mapper, optionally altering the values using the :&as Callable. The @list cannot be lazy.

The mapper can be a Callable that takes a single argument, an Associative, or an Iterable. With Associative and an Iterable mappers, the values in the @list represent the key and index of the mapper's value respectively. A Callable mapper will be executed once per each item in the @list, with that item as the argument and its return value will be used as the mapper's value.

Simple categorization

The mapper's value is expected to be a possibly empty list of non-Iterables that represent categories to place the value into:

say % .categorize-list: {
    gather {
        take 'prime'   if .is-prime;
        take 'largish' if $_ > 5;
        take $_ %% 2 ?? 'even' !! 'odd';
    }
}, ^10;
 
# OUTPUT: 
# { 
#     prime   => [2 3 5 7] 
#     even    => [0 2 4 6 8], 
#     odd     => [1 3 5 7 9], 
#     largish => [6 7 8 9], 
# }

Notice how some items, e.g. 6 and 7, are present in several categories.

Multi-level categorization

In multi-level categorization, the categories produced by the mapper can are Iterables and categorization combines features of classify, by producing nested hashes of classifications for each category.

say % .categorize-list: {
    [
        $_ > 5    ?? 'largish' !! 'smallish',
        .is-prime ?? 'prime'   !! 'non-prime',
    ],
}, ^10;
 
# OUTPUT: 
# { 
#     largish => { 
#         non-prime => [6 8 9], 
#         prime     => [7] 
#     }, 
#     smallish => { 
#         non-prime => [0 1 4], 
#         prime     => [2 3 5] 
#     } 
# }

The mapper in above snippet produces single-item list (note the significant trailing comma) with a two-item Array in it. The first item in that array indicates the first level of classification: the largish/smallish categories the routine produces. The second item in that array indicates further levels of classification, in our case the classification into prime/non-prime inside of each category.

NOTE: each of category Iterables 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.

:&as value modifier

If :&as Callable argument is specified, it will be called once per each item of @list, with the value as the argument, and its return value will be used instead of the original @list's item:

say % .categorize-list: :as{"Value is $_"}, { $_ %% 2 ?? 'even' !! 'odd' }, ^5;
# OUTPUT (slightly altered manually, for clarity): 
# { 
#     even => ['Value is 0', 'Value is 2', 'Value is 4'], 
#     odd  => ['Value is 1', 'Value is 3'] 
# }

role Baggy

From Baggy

(Baggy) method categorize-list

Defined as:

multi method categorize-list(&mapper, *@list --> Baggy:D)
multi method categorize-list(%mapper, *@list --> Baggy:D)
multi method categorize-list(@mapper, *@list --> Baggy:D)

Populates a mutable Baggy by categorizing the possibly-empty @list of values using the given mapper. The @list cannot be lazy.

say BagHash.new.categorize-list: {
    gather {
        take 'largish' if $_ > 5;
        take .is-prime ?? 'prime' !! 'non-prime';
        take $_ %% 2   ?? 'even'  !! 'odd';
    }
}, ^10;
# OUTPUT: BagHash.new(largish(4), even(5), non-prime(6), prime(4), odd(5)) 
 
my %mapper = :sugar<sweet white>, :lemon<sour>, :cake('sweet', 'is a lie');
say MixHash.new.categorize-list: %mapper, <sugar lemon cake>;
# OUTPUT: MixHash.new(is a lie, sour, white, sweet(2))

The mapper can be a Callable that takes a single argument, an Associative, or an Iterable. With Associative and an Iterable mappers, the values in the @list represent the key and index of the mapper's value respectively. A Callable mapper will be executed once per each item in the @list, with that item as the argument and its return value will be used as the mapper's value.

The mapper's value is used as a possibly-empty list of keys of the Baggy that will be incremented by 1.

Note: unlike the Hash's .categorize-list, returning a list of Iterables as mapper's value will throw, as Baggy types do not support nested categorization. For the same reason, Baggy's .categorize-list does not accept :&as parameter.