doc/modules/README.Sort-Naturally

   1 README for Sort::Naturally
   2                                         Time-stamp: "2001-05-25 21:17:33 MDT"
   3
   4                             Sort::Naturally
   5
   6 [extracted from the Pod...]
   7
   8 NAME
   9      Sort::Naturally -- sort lexically, but sort numeral parts
  10      numerically
  11
  12 SYNOPSIS
  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
  25 DESCRIPTION
  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
  75 INSTALLATION
  76
  77 You install Sort::Naturally, as you would install any perl module
  78 library, by running these commands:
  79
  80    perl Makefile.PL
  81    make
  82    make test
  83    make install
  84
  85 If you want to install a private copy of Sort::Naturally in your home
  86 directory, then you should try to produce the initial Makefile with
  87 something like this command:
  88
  89   perl Makefile.PL LIB=~/perl
  90
  91 See perldoc perlmodinstall for more information on installing modules.
  92
  93
  94 DOCUMENTATION
  95
  96 POD-format documentation is included in Naturally.pm.  POD is readable
  97 with the 'perldoc' utility.  See ChangeLog for recent changes.
  98
  99
 100 SUPPORT
 101
 102 Questions, bug reports, useful code bits, and suggestions for
 103 Sort::Naturally should just be sent to me at sburke@cpan.org
 104
 105
 106 AVAILABILITY
 107
 108 The latest version of Sort::Naturally is available from the
 109 Comprehensive Perl Archive Network (CPAN).  Visit
 110 <http://www.perl.com/CPAN/> to find a CPAN site near you.
 111
 112
 113 COPYRIGHT
 114
 115 Copyright 2001, Sean M. Burke <sburke@cpan.org>, all rights
 116 reserved.
 117
 118 The programs and documentation in this dist are distributed in
 119 the hope that they will be useful, but without any warranty; without
 120 even the implied warranty of merchantability or fitness for a
 121 particular purpose.
 122
 123 This library is free software; you can redistribute it and/or modify
 124 it under the same terms as Perl itself.