README
1README for Sort::Naturally
2 Time-stamp: "2001-05-25 21:17:33 MDT"
3
4 Sort::Naturally
5
6[extracted from the Pod...]
7
8NAME
9 Sort::Naturally -- sort lexically, but sort numeral parts
10 numerically
11
12SYNOPSIS
13 @them = nsort(qw(
14 foo12a foo12z foo13a foo 14 9x foo12 fooa foolio Foolio Foo12a
15 ));
16 print join(' ', @them), "\n";
17
18 Prints:
19
20 9x 14 foo fooa foolio Foolio foo12 foo12a Foo12a foo12z foo13a
21
22 (Or "foo12a" + "Foo12a" and "foolio" + "Foolio" and might be
23 switched, depending on your locale.)
24
25DESCRIPTION
26 This module exports two functions, nsort and ncmp; they are
27 used in implementing my idea of a "natural sorting"
28 algorithm. Under natural sorting, numeric substrings are
29 compared numerically, and other word-characters are compared
30 lexically.
31
32 This is the way I define natural sorting:
33
34 o Non-numeric word-character substrings are sorted
35 lexically, case-insensitively: "Foo" comes between
36 "fish" and "fowl".
37
38 o Numeric substrings are sorted numerically: "100" comes
39 after "20", not before.
40
41 o \W substrings (neither words-characters nor digits) are
42 ignored.
43
44 o Our use of \w, \d, \D, and \W is locale-sensitive:
45 Sort::Naturally uses a use locale statement.
46
47 o When comparing two strings, where a numeric substring
48 in one place is not up against a numeric substring in
49 another, the non-numeric always comes first. This is
50 fudged by reading pretending that the lack of a number
51 substring has the value -1, like so:
52
53 foo => "foo", -1
54 foobar => "foo", -1, "bar"
55 foo13 => "foo", 13,
56 foo13xyz => "foo", 13, "xyz"
57
58 That's so that "foo" will come before "foo13", which
59 will come before "foobar".
60
61 o The start of a string is exceptional: leading non-\W
62 (non-word, non-digit) components are are ignored, and
63 numbers come before letters.
64
65 o I define "numeric substring" just as sequences matching
66 m/\d+/ -- scientific notation, commas, decimals, etc.,
67 are not seen. If your data has thousands separators in
68 numbers ("20,000 Leagues Under The Sea" or "20.000
69 lieues sous les mers"), consider stripping them before
70 feeding them to nsort or ncmp.
71
72[end Pod extract]
73
74
75INSTALLATION
76
77You install Sort::Naturally, as you would install any perl module
78library, by running these commands:
79
80 perl Makefile.PL
81 make
82 make test
83 make install
84
85If you want to install a private copy of Sort::Naturally in your home
86directory, then you should try to produce the initial Makefile with
87something like this command:
88
89 perl Makefile.PL LIB=~/perl
90
91See perldoc perlmodinstall for more information on installing modules.
92
93
94DOCUMENTATION
95
96POD-format documentation is included in Naturally.pm. POD is readable
97with the 'perldoc' utility. See ChangeLog for recent changes.
98
99
100SUPPORT
101
102Questions, bug reports, useful code bits, and suggestions for
103Sort::Naturally should just be sent to me at sburke@cpan.org
104
105
106AVAILABILITY
107
108The latest version of Sort::Naturally is available from the
109Comprehensive Perl Archive Network (CPAN). Visit
110<http://www.perl.com/CPAN/> to find a CPAN site near you.
111
112
113COPYRIGHT
114
115Copyright 2001, Sean M. Burke <sburke@cpan.org>, all rights
116reserved.
117
118The programs and documentation in this dist are distributed in
119the hope that they will be useful, but without any warranty; without
120even the implied warranty of merchantability or fitness for a
121particular purpose.
122
123This library is free software; you can redistribute it and/or modify
124it under the same terms as Perl itself.
125