Sort::Key(3pm)

1Sort::Key(3)          User Contributed Perl Documentation         Sort::Key(3)
2
3
4

NAME

6       Sort::Key - the fastest way to sort anything in Perl
7

SYNOPSIS

9         use Sort::Key qw(keysort nkeysort ikeysort);
10
11         @by_name = keysort { "$_->{surname} $_->{name}" } @people;
12
13         # sorting by a numeric key:
14         @by_age = nkeysort { $_->{age} } @people;
15
16         # sorting by a numeric integer key:
17         @by_sons = ikeysort { $_->{sons} } @people;
18

DESCRIPTION

20       Sort::Key provides a set of functions to sort lists of values by some
21       calculated key value.
22
23       It is faster (usually much faster) and uses less memory than other
24       alternatives implemented around perl sort function (ST, GRT, etc.).
25
26       Multi-key sorting functionality is also provided via the companion
27       modules Sort::Key::Multi, Sort::Key::Maker and Sort::Key::Register.
28
29   FUNCTIONS
30       This module provides a large number of sorting subroutines but they are
31       all variations off the "keysort" one:
32
33         @sorted = keysort { CALC_KEY($_) } @data
34
35       that is conceptually equivalent to
36
37         @sorted = sort { CALC_KEY($a) cmp CALC_KEY($b) } @data
38
39       and where "CALC_KEY($_)" can be any expression to extract the key value
40       from $_ (not only a subroutine call).
41
42       For instance, some variations are "nkeysort" that performs a numeric
43       comparison, "rkeysort" that orders the data in descending order,
44       "ikeysort" and "ukeysort" that are optimized versions of "nkeysort"
45       that can be used when the keys are integers or unsigned integers
46       respectively, etc.
47
48       Also, inplace versions of the sorters are provided. For instance
49
50         keysort_inplace { CALC_KEY($_) } @data
51
52       that is equivalent to
53
54         @data = keysort { CALC_KEY($_) } @data
55
56       but being (a bit) faster and using less memory.
57
58       The full list of subroutines that can be imported from this module
59       follows:
60
61       keysort { CALC_KEY } @array
62           returns the elements on @array sorted by the key calculated
63           applying "{ CALC_KEY }" to them.
64
65           Inside "{ CALC_KEY }", the object is available as $_.
66
67           For example:
68
69             @a=({name=>john, surname=>smith}, {name=>paul, surname=>belvedere});
70             @by_name=keysort {$_->{name}} @a;
71
72           This function honours the "use locale" pragma.
73
74       nkeysort { CALC_KEY } @array
75           similar to "keysort" but compares the keys numerically instead of
76           as strings.
77
78           This function honours the "use integer" pragma, i.e.:
79
80             use integer;
81             my @s=(2.4, 2.0, 1.6, 1.2, 0.8);
82             my @ns = nkeysort { $_ } @s;
83             print "@ns\n"
84
85           prints
86
87             0.8 1.6 1.2 2.4 2
88
89       rnkeysort { CALC_KEY } @array
90           works as "nkeysort", comparing keys in reverse (or descending)
91           numerical order.
92
93       ikeysort { CALC_KEY } @array
94           works as "keysort" but compares the keys as integers (32 bits or
95           more, no checking is performed for overflows).
96
97       rikeysort { CALC_KEY } @array
98           works as "ikeysort", but in reverse (or descending) order.
99
100       ukeysort { CALC_KEY } @array
101           works as "keysort" but compares the keys as unsigned integers (32
102           bits or more).
103
104           For instance, it can be used to efficiently sort IP4 addresses:
105
106             my @data = qw(1.2.3.4 4.3.2.1 11.1.111.1 222.12.1.34
107                           0.0.0.0 255.255.255.0) 127.0.0.1);
108
109             my @sorted = ukeysort {
110                              my @a = split /\./;
111                              (((($a[0] << 8) + $a[1] << 8) + $a[2] << 8) + $a[3])
112                          } @data;
113
114       rukeysort { CALC_KEY } @array
115           works as "ukeysort", but in reverse (or descending) order.
116
117       keysort_inplace { CALC_KEY } @array
118       nkeysort_inplace { CALC_KEY } @array
119       ikeysort_inplace { CALC_KEY } @array
120       ukeysort_inplace { CALC_KEY } @array
121       rkeysort_inplace { CALC_KEY } @array
122       rnkeysort_inplace { CALC_KEY } @array
123       rikeysort_inplace { CALC_KEY } @array
124       rukeysort_inplace { CALC_KEY } @array
125           work as the corresponding "keysort" functions but sorting the array
126           inplace.
127
128       rsort @array
129       nsort @array
130       rnsort @array
131       isort @array
132       risort @array
133       usort @array
134       rusort @array
135       rsort_inplace @array
136       nsort_inplace @array
137       rnsort_inplace @array
138       isort_inplace @array
139       risort_inplace @array
140       usort_inplace @array
141       rusort_inplace @array
142           are simplified versions of its "keysort" cousins. They use the own
143           values as the sorting keys.
144
145           For instance those constructions are equivalent:
146
147             @sorted = nsort @foo;
148
149             @sorted = nkeysort { $_ } @foo;
150
151             @sorted = sort { $a <=> $b } @foo;
152
153       multikeysorter(@types)
154       multikeysorter_inplace(@types)
155       multikeysorter(\&genkeys, @types)
156       multikeysorter_inplace(\&genkeys, @types)
157           are the low level interface to the multi-key sorting functionality
158           (normally, you should use Sort::Key::Maker and Sort::Key::Register
159           or Sort::Key::Multi instead).
160
161           They get a list of keys descriptions and return a reference to a
162           multi-key sorting subroutine.
163
164           Types accepted by default are:
165
166             string, str, locale, loc, integer, int,
167             unsigned_integer, uint, number, num
168
169           and support for additional types can be added via the register_type
170           subroutine available from Sort::Key::Types or the more friendly
171           interface available from Sort::Key::Register.
172
173           Types can be preceded by a minus sign to indicate descending order.
174
175           If the first argument is a reference to a subroutine it is used as
176           the multi-key extraction function. If not, the generated sorters
177           expect one as their first argument.
178
179           Example:
180
181             my $sorter1 = multikeysorter(sub {length $_, $_}, qw(int str));
182             my @sorted1 = &$sorter1(qw(foo fo o of oof));
183
184             my $sorter2 = multikeysorter(qw(int str));
185             my @sorted2 = &$sorter2(sub {length $_, $_}, qw(foo fo o of oof));
186

SUPPORT

203       To report bugs, send me and email or use the CPAN bug tracking system
204       at <http://rt.cpan.org>.
205
206   Commercial support
207       Commercial support, professional services and custom software
208       development around this module are available through my current
209       company. Drop me an email with a rough description of your requirements
210       and we will get back to you ASAP.
211
212   My wishlist
213       If you like this module and you're feeling generous, take a look at my
214       Amazon Wish List: <http://amzn.com/w/1WU1P6IR5QZ42>
215

COPYRIGHT AND LICENSE

217       Copyright (C) 2005-2007, 2012, 2014 by Salvador Fandiño,
218       <sfandino@yahoo.com>.
219
220       This library is free software; you can redistribute it and/or modify it
221       under the same terms as Perl itself, either Perl version 5.8.4 or, at
222       your option, any later version of Perl 5 you may have available.
223
224
225
226perl v5.34.0                      2022-01-21                      Sort::Key(3)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

SUPPORT

COPYRIGHT AND LICENSE