Sort::Key(3)

💖 NAME

This is the manual page for Sort::Key(3) from the User Contributed Perl Documentation — and it's literally the fastest way to sort anything in Perl. No cap. The actual NAME line says: Sort::Key - the fastest way to sort anything in Perl, and honestly? Iconic.

✨ SYNOPSIS

Bestie, here's the whole vibe in code form:

         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

So Sort::Key gives you a whole set of functions to sort lists of values by some calculated key value. It's faster — usually much faster — and uses less memory than other alternatives implemented around the perl sort function (ST, GRT, etc.). Lowkey a flex.

It also provides multi-key sorting functionality via the companion modules Sort::Key::Multi, Sort::Key::Maker and Sort::Key::Register. The whole squad is here.

🧚 FUNCTIONS

This module provides a large number of sorting subroutines, but they're all variations off the keysort one:

  @sorted = keysort { CALC_KEY($_) } @data

That's conceptually equivalent to:

  @sorted = sort { CALC_KEY($a) cmp CALC_KEY($b) } @data

And CALC_KEY($_) can be any expression to extract the key value from $_ — not only a subroutine call. Versatile queen.

For instance, some variations are nkeysort, which performs a numeric comparison; rkeysort, which orders the data in descending order; ikeysort and ukeysort, which are optimized versions of nkeysort that can be used when the keys are integers or unsigned integers respectively; etc. There are so many cousins, and they all eat.

Also, inplace versions of the sorters are provided. For instance:

  keysort_inplace { CALC_KEY($_) } @data

That's equivalent to:

  @data = keysort { CALC_KEY($_) } @data

But it's a bit faster and uses less memory. The parenthetical is literally "(a bit)", bestie — we keep it real.

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). We said what we said — no overflow checking, so don't act surprised.

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. Inplace girlies understand.

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 — 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) — 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

Support for additional types can be added via the register_type subroutine available from Sort::Key::Types, or via the more friendly interface available from Sort::Key::Register.

Types can be preceded by a minus sign to indicate descending order. Not me loving a tiny minus sign doing so much 💅.

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

The perl sort function, integer, locale.

Companion modules: Sort::Key::Multi, Sort::Key::Register, Sort::Key::Maker and Sort::Key::Natural.

The Sort::Key::IPv4, Sort::Key::DateTime and Sort::Key::OID modules add support for additional datatypes to Sort::Key.

Sort::Key::External allows you 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 http://rt.cpan.org.

💼 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: http://amzn.com/w/1WU1P6IR5QZ42

👑 COPYRIGHT AND LICENSE

Copyright (C) 2005-2007, 2012, 2014 by Salvador Fandiño, <sfandino@yahoo.com>.

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.

---

Okay bye bestie 🫶💖 this page is perl v5.42.0, dated 2015-04-14, and filed as Sort::Key(3) — periodt. 💅✨