File Coverage

blib/lib/List/Categorize.pm

Criterion	Covered	Total	%
statement	18	18	100.0
branch	2	2	100.0
condition			n/a
subroutine	4	4	100.0
pod	1	1	100.0
total	25	25	100.0

package List::Categorize;
#
# ABSTRACT: Categorize list items into a hash of named sublists.
#
# See documentation after __END__ below.
#

use strict;
use warnings;

## Module Interface

use base 'Exporter';

our $VERSION = '0.03';
our @EXPORT = qw();
our @EXPORT_OK = qw(
    categorize
);
our %EXPORT_TAGS = (
    all => \@EXPORT_OK
);


## Subroutines

sub categorize (&@)
#
# Usage:    %hash = categorize {BLOCK} @LIST
# Returns:  a hash of lists
#
# Creates a hash by running a subroutine for each element in a list. The
# subroutine returns a hash key (the "category") for the current
# element. (If the subroutine returns undef for a list element, that
# element is not placed in the resulting hash.)
#
# The resulting hash contains a key for each category, and each key
# refers to a list of the elements that correspond to that category.
#
{
    # Parameters
    #
    my $coderef = shift;

    # @_ is used directly, in the loop below.

    # This is the hash of lists that will be returned to the caller.
    #
    my %sublists = ();

    # Iterate over the provided list, categorizing
    # each element.
    #
    for my $element (@_)
    {
        # Localize $_, then copy the current element into it, so the
        # categorizer subroutine can refer to $_ (in the same way as
        # map, grep, and sort do).
        #
        # Copying the element keeps it from acting as an alias into the
        # @_ list, so the categorizer can modify $_ without damaging the
        # source list.
        #
        local $_ = $element;

        # Execute the categorizer subroutine to determine the category
        # for this element.
        #
        my $category = $coderef->();

        # If a category was returned, use it as a key in the %sublists
        # hash, and add the current element to the list referenced by
        # that key.
        #
        # If the categorizer didn't return a value (or returned undef),
        # then leave this element out of %sublists entirely.
        #
        if (defined $category)
        {
            push @{ $sublists{ $category } }, $_;
        }
    }

    return %sublists;
}


1;

__END__