The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.


List::Categorize - Categorize list items into a tree of named sublists


This documentation describes List::Categorize version 0.04.


    use List::Categorize qw(categorize);

    my %odds_and_evens = categorize { $_ % 2 ? 'ODD' : 'EVEN' } (1..9);

    # %odds_and_evens now contains
    # ( ODD => [ 1, 3, 5, 7, 9 ], EVEN => [ 2, 4, 6, 8 ] )

    my %capitalized = categorize {

        # Transform the element before placing it in the tree.
        $_ = ucfirst $_;

        # Use the first letter of the element as the first-level category,
        # then the first 2 letters as a second-level category
        substr($_, 0, 1), substr($_, 0, 2);

    } qw( apple banana antelope bear canteloupe coyote ananas );

    # %capitalized now contains
    # (
    #   A => { An => ['Antelope', 'Ananas'], Ap => ['Apple'], },
    #   B => { Ba => ['Banana'],             Be => ['Bear'],  },
    #   C => { Ca => ['Canteloupe'],         Co => ['Coyote'] },
    # )


A simple module that creates a tree by applying a specified rule to each element of a provided list.


Nothing by default.


categorize BLOCK LIST

    my %tree = categorize { $_ > 10 ? 'Big' : 'Little' } @list;

categorize creates a tree by running BLOCK for each element in LIST. The block should return a list of "categories" for the current element, i.e a list of scalar values corresponding to the sequence of subtrees under which this element will be placed. If the block returns an empty list, or a list containing an undef, the corresponding element is not placed in the resulting tree.

The resulting tree contains a key for each top-level category. Values are either references to subtrees, or references to arrayrefs of elements (depending on the depth of the categorization).

Within the block, $_ refers to the current list element. Elements can be modified before they're placed in the target tree by modifying the $_ variable:

    my %tree = categorize { $_ = uc $_; 'List' } qw( one two three );

    # %tree now contains ( List => [ 'ONE', 'TWO', 'THREE' ] )

NOTE: The categorizer should return a list of strings, or undef. Other values are reserved for future use, and may cause unpredictable results in the current version. When using multi-level categorization, the categorizer should always return the same number of keys.


"part" in List::MoreUtils

Previous versions of this module only handled one-level categorization, while multi-level categorization was implemented in List::Categorize::Multi. Now both modules have been merged into List::Categorize, therefore List::Categorize::Multi is deprecated.


Bill Odom, <wnodom at> (original author), Laurent Dami, <dami at> (added the multi-level categorization)


None known.

Please report any bugs or feature requests to bug-list-categorize at, or through the web interface at


You can find documentation for this module with the perldoc command.

    perldoc List::Categorize

You can also look for information at:

RT: CPAN's request tracker

AnnoCPAN: Annotated CPAN documentation

CPAN Ratings

Search MetaCPAN

Github repository


Copyright (c) 2009 Bill Odom, 2017 Laurent Dami.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses at, and

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.