Attempt to document List.categorize, most of the text from https://raw.githubusercontent.com/perl6/specs/master/S32-setting-library/Containers.pod

gistfile1.txt

=head2 routine categorize

Defined as:

    multi sub    categorize(&mapper, *@values) returns Hash:D
    multi method categorize(List:D: &mapper)   returns Hash:D

Usage:

    categorize MAPPER, LIST
    LIST.categorize(MAPPER)

Transforms a list of values into a hash representing the categorizations
of those values according to a mapper; each hash key represents one possible
categorization for one or more of the incoming list values, and
the corresponding hash value contains an array of those list values
categorized by the mapper into the category of the associated key.

Note that, unlike L<classify>, which assumes that the return value
of the mapper is a single value, C<categorize> always assumes that
the return value of the mapper is a list of categories that are
appropriate to the current value.

Example:

    sub mapper(Int $i) returns List {
        $i %% 2 ?? 'even' !! 'odd',
        $i.is-prime ?? 'prime' !! 'not prime'
    }
    say categorize &mapper, (1, 7, 6, 3, 2);   # {even => [2], odd => [7 3], prime => [7 3 2]}