NAME

Sort::Key - sorts objects by one or several keys really fast

SYNOPSIS

use Sort::Key qw(keysort nkeysort ikeysort);

@by_name = keysort { "$_->{surname} $_->{name}" } @people;
@by_age = nkeysort { $_->{age} } @people;
@by_sons = ikeysort { $_->{sons} } @people;

DESCRIPTION

Sort::Key provides a set of functions to sort object arrays by some (calculated) key value.

It is faster (usually much faster) and uses less memory than other alternatives implemented around perl sort function (ST, GRM, etc.).

Multikey sorting functionality is also provided via the companion modules Sort::Key::Maker and Sort::Key::Register.

EXPORT

None by default.

FUNCTIONS

keysort { CALC_KEY } @array

returns the elements on @array sorted by the key calculated applying { CALC_KEY } to them.

Inside { CALC_KEY }, the object is available as $_.

For example:

@a=({name=>john, surname=>smith}, {name=>paul, surname=>belvedere});
@by_name=keysort {$_->{name}} @a;

This function honours the use locale pragma.

nkeysort { CALC_KEY } @array

similar to keysort but compares the keys numerically instead of as strings.

This function honours the use integer pragma, i.e.:

use integer;
my @s=(2.4, 2.0, 1.6, 1.2, 0.8);
my @ns = nkeysort { $_ } @s;
print "@ns\n"

prints

0.8 1.6 1.2 2.4 2

rnkeysort { CALC_KEY } @array

works as nkeysort, comparing keys in reverse (or descending) numerical order.

ikeysort { CALC_KEY } @array

works as keysort but compares the keys as integers.

rikeysort { CALC_KEY } @array

works as ikeysort, but in reverse (or descending) order.

keysort_inplace { CALC_KEY } @array

nkeysort_inplace { CALC_KEY } @array

ikeysort_inplace { CALC_KEY } @array

rkeysort_inplace { CALC_KEY } @array

rnkeysort_inplace { CALC_KEY } @array

rikeysort_inplace { CALC_KEY } @array

work as the corresponding keysort functions but sorting the array inplace.

multikeysorter(@types)

multikeysorter_inplace(@types)

multikeysorter(\&genkeys, @types)

multikeysorter_inplace(\&genkeys, @types)

are the low level interface to the multikey sorting functionality (normally, you should use Sort::Key::Maker and Sort::Key::Register instead).

They get a list of keys descriptions and return a reference to a multikey sorting subroutine.

Types accepted by default are:

string, str, locale, loc, integer, int, number, num

and support for additional types can be added via the non exportable register_type subroutine (see below) or the more friendle interface available in Sort::Key::Register.

Types can be preceded by a minus sign to indicate descending order.

If the first argument is a reference to a subroutine it is used as the multikey extraction function. If not, the generated sorters expect one as their first argument.

Example:

my $sorter1 = multikeysorter(sub {length $_, $_}, qw(int str));
my @sorted1 = &$sorter1(qw(foo fo o of oof));

my $sorter2 = multikeysorter(qw(int str));
my @sorted2 = &$sorter2(sub {length $_, $_}, qw(foo fo o of oof));

Sort::Key::register_type($name, \&gensubkeys, @subkeystypes)

registers a new datatype named $name defining how to convert it to a multikey.

&gensubkeys should convert the object of type $name passed on $_ to a list of values composing the multikey.

@subkeystypes is the list of types for the generated multikeys.

For instance:

Sort::Key::register_type Person =>
               sub { $_->surname,
                     $_->name,
                     $_->middlename },
               qw(str str str);

Sort::Key::register_type Color =>
               sub { $_->R, $_->G, $_->B },
               qw(int int int);

Once a datatype has been registered it can be used in the same way as types supported natively, even for defining new types, i.e.:

Sort::Key::register_type Family =>
               sub { $_->man, $_->woman },
               qw(Person Person);

SEE ALSO

perl sort function, integer, locale.

Companion modules Sort::Key::Register and Sort::Key::Maker.

And alternative to this module is Sort::Maker.

AUTHOR

Salvador Fandiño, <sfandino@yahoo.com>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Salvador Fandiño

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.