--- name: "Sort::Key" section: "3pm" platform: "linux" package: "perl-sort-key" version: "1.33-16" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Sort::Key" --- # Sort::Key(3pm) the fastest way to sort anything in Perl ## NAME Sort::Key - the fastest way to sort anything in Perl ## SYNOPSIS ``` use Sort::Key qw(keysort nkeysort ikeysort); @by_name = keysort { "$_->{surname} $_->{name}" } @people; # sorting by a numeric key: @by_age = nkeysort { $_->{age} } @people; # sorting by a numeric integer key: @by_sons = ikeysort { $_->{sons} } @people; ``` ## DESCRIPTION Sort::Key provides a set of functions to sort lists of values by some calculated key value. It is faster (usually **much faster**) and uses less memory than other alternatives implemented around perl sort function (ST, GRT, etc.). Multi-key sorting functionality is also provided via the companion modules Sort::Key::Multi, Sort::Key::Maker and Sort::Key::Register. ### FUNCTIONS This module provides a large number of sorting subroutines but they are all variations off the `"keysort"` one: ``` @sorted = keysort { CALC_KEY($_) } @data ``` that is conceptually equivalent to ``` @sorted = sort { CALC_KEY($a) cmp CALC_KEY($b) } @data ``` and where `CALC_KEY($_)` can be any expression to extract the key value from `$_` (not only a subroutine call). For instance, some variations are `"nkeysort"` that performs a numeric comparison, `"rkeysort"` that orders the data in descending order, `"ikeysort"` and `"ukeysort"` that are optimized versions of `"nkeysort"` that can be used when the keys are integers or unsigned integers respectively, etc. Also, inplace versions of the sorters are provided. For instance ``` keysort_inplace { CALC_KEY($_) } @data ``` that is equivalent to ``` @data = keysort { CALC_KEY($_) } @data ``` but being (a bit) faster and using less memory. The full list of subroutines that can be imported from this module follows: - 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 (32 bits or more, no checking is performed for overflows). - rikeysort { CALC\_KEY } @array works as `"ikeysort"`, but in reverse (or descending) order. - ukeysort { CALC\_KEY } @array works as `"keysort"` but compares the keys as unsigned integers (32 bits or more). For instance, it can be used to efficiently sort IP4 addresses: ``` my @data = qw(1.2.3.4 4.3.2.1 11.1.111.1 222.12.1.34 0.0.0.0 255.255.255.0) 127.0.0.1); my @sorted = ukeysort { my @a = split /\./; (((($a[0] << 8) + $a[1] << 8) + $a[2] << 8) + $a[3]) } @data; ``` - rukeysort { CALC\_KEY } @array works as `"ukeysort"`, but in reverse (or descending) order. - keysort\_inplace { CALC\_KEY } @array - nkeysort\_inplace { CALC\_KEY } @array - ikeysort\_inplace { CALC\_KEY } @array - ukeysort\_inplace { CALC\_KEY } @array - rkeysort\_inplace { CALC\_KEY } @array - rnkeysort\_inplace { CALC\_KEY } @array - rikeysort\_inplace { CALC\_KEY } @array - rukeysort\_inplace { CALC\_KEY } @array work as the corresponding `"keysort"` functions but sorting the array inplace. - rsort @array - nsort @array - rnsort @array - isort @array - risort @array - usort @array - rusort @array - rsort\_inplace @array - nsort\_inplace @array - rnsort\_inplace @array - isort\_inplace @array - risort\_inplace @array - usort\_inplace @array - rusort\_inplace @array are simplified versions of its `"keysort"` cousins. They use the own values as the sorting keys. For instance those constructions are equivalent: ``` @sorted = nsort @foo; @sorted = nkeysort { $_ } @foo; @sorted = sort { $a <=> $b } @foo; ``` - multikeysorter(@types) - multikeysorter\_inplace(@types) - multikeysorter(\\&genkeys, @types) - multikeysorter\_inplace(\\&genkeys, @types) are the low level interface to the multi-key sorting functionality (normally, you should use Sort::Key::Maker and Sort::Key::Register or Sort::Key::Multi instead). They get a list of keys descriptions and return a reference to a multi-key sorting subroutine. Types accepted by default are: ``` string, str, locale, loc, integer, int, unsigned_integer, uint, number, num ``` and support for additional types can be added via the register\_type subroutine available from Sort::Key::Types or the more friendly interface available from 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 multi-key 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)); ``` ## SEE ALSO perl sort function, integer, locale. Companion modules Sort::Key::Multi, Sort::Key::Register, Sort::Key::Maker and Sort::Key::Natural. Sort::Key::IPv4, Sort::Key::DateTime and Sort::Key::OID modules add support for additional datatypes to Sort::Key. Sort::Key::External allows to sort huge lists that do not fit in the available memory. Other interesting Perl sorting modules are Sort::Maker, Sort::Naturally and Sort::External. ## SUPPORT To report bugs, send me and email or use the CPAN bug tracking system at \. ### Commercial support Commercial support, professional services and custom software development around this module are available through my current company. Drop me an email with a rough description of your requirements and we will get back to you ASAP. ### My wishlist If you like this module and you're feeling generous, take a look at my Amazon Wish List: \ ## COPYRIGHT AND LICENSE Copyright (C) 2005-2007, 2012, 2014 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.