NAME

List::Part - Partition one array into several

SYNOPSIS

use List::Part;
($good, $bad)=part { !/substring/ } @array; #store arrayrefs into $good and $bad
(*good, *bad)=part { !/substring/ } @array; #store into @good and @bad

ABSTRACT

List::Part implements the part function, allowing one array to be "partitioned" into several based on the results of a code reference.

DESCRIPTION

There are many applications in which the items of a list need to be categorized. For example, let's say you want to categorize lines in a log file:

my($success, $failure)=part { /^ERR/ } <LOG>;

Or, suppose you have a list of employees, and you need to determine their fate:

my($lay_off, $give_raise, $keep)=part {
      $_->is_talented  ? 0 
    : $_->is_executive ? 1 
    :                    2
} @employees;

Actually, the second one is better suited to part's alternate form, parta:

my($lay_off, $give_raise, $keep)=parta
    [ sub { $_->talented }, sub { $_->is_executive }, qr// ]
    @employees;

Functions

part

part takes a code reference and an array and returns a list of array references. The coderef should examine the value in either $_ or its argument list and return a (zero-based) index indicating which array the value should go into. Built-in Perl functions that emit booleans, such as regular-expression matches or file operators, are also suitable for this--but note that the second array is the one that receives true values, not the first. Returning undef will cause part to throw away the value, so that none of the arrays will receive it.

The function is prototyped (&@), which means that, like the built-in map and grep, you can pass it a bare block without using sub.

Tip: As mentioned before, this function returns a list of array references; if you want the results to be assigned to (global) arrays, then assign to typeglobs:

(*a, *b, *c)=part { ... } @list;

parta

parta is a wrapper around part which can reduce the amount of code under certain circumstances. Instead of taking a code reference, parta takes an array reference containing strings or certain types of references; the index of the first item an incoming value "matches" is the index of the list it ends up in. For example:

($a, $b, $c)=part [ qr/a/, qr/b/, qr/c/ ] => qw(a b c aa ab bc);
# $a=[ qw(a aa ab) ], $b=[ qw(b bc) ], $c=[ qw(c) ]

The match rules are fairly sophistocated, and vary based on the type of item in the arrayref:

• Strings (and other plain scalars) are compared using eq.

• Array references match if any of their elements matches the value.

• Hash references match if their associated value in the hash, i.e. $hashref-{$value}>, is true.

• Code references match if, when invoked on the item, they return true.

• Regexen (such as those produced by qr//) match if the item matches them.

• Other references are compared using eq.

parta carries the prototype ($@).

Tip: If you want the results to include a "rejects" array, add an empty regex (qr//) to the end of the arrayref.

Exporting

part is exported by default; parta can be exported specifically.

DIAGNOSTICS

parta does not know how to match against an object of type %s

This exception is thrown when an item in the array reference is of a type that parta's matching rules don't cover. The only valid types are plain scalars, array references, hash references, code references, precompiled regular expressions, and objects with a matches method.

BUGS and ENHANCEMENTS

There are no known bugs, and since the code for this module is fairly simple, I don't expect there will be any.

Bug reports and enhancement requests are welcome, but I'm far more likely to act on them if they're accompanied by a patch fixing/implementing them. Also, if you get this to work on older versions of Perl without changing any functionality, I will happily apply your patch. Send reports/requests to <brent@brentdax.com>.

SEE ALSO

The Perl 6 design, which includes a more powerful version of part.

AUTHOR

Brent Dax <brent@brentdax.com>

COPYRIGHT

Copyright (C) 2003 Brent Dax. All Rights Reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm List::Part

perl -MCPAN -e shell
install List::Part