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       Multikey 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 expresion 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 as
76           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 multikey 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           multikey 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 non
170           exportable register_type subroutine (see below) or the more
171           friendly 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 multikey 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
187       Sort::Key::register_type($name, \&gensubkeys, @subkeystypes)
188           registers a new datatype named $name defining how to convert it to
189           a multikey.
190
191           &gensubkeys should convert the object of type $name passed on $_ to
192           a list of values composing the multikey.
193
194           @subkeystypes is the list of types for the generated multikeys.
195
196           For instance:
197
198             Sort::Key::register_type Person =>
199                            sub { $_->surname,
200                                  $_->name,
201                                  $_->middlename },
202                            qw(str str str);
203
204             Sort::Key::register_type Color =>
205                            sub { $_->R, $_->G, $_->B },
206                            qw(int int int);
207
208           Once a datatype has been registered it can be used in the same way
209           as types supported natively, even for defining new types, i.e.:
210
211             Sort::Key::register_type Family =>
212                            sub { $_->man, $_->woman },
213                            qw(Person Person);
214

COPYRIGHT AND LICENSE

225       Copyright (C) 2005, 2006 by Salvador Fandin~o, <sfandino@yahoo.com>.
226
227       This library is free software; you can redistribute it and/or modify it
228       under the same terms as Perl itself, either Perl version 5.8.4 or, at
229       your option, any later version of Perl 5 you may have available.
230
231
232
233perl v5.12.0                      2007-04-07                      Sort::Key(3)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

COPYRIGHT AND LICENSE