README for Sort::Naturally
                                        Time-stamp: "2001-05-25 21:17:33 MDT"

			    Sort::Naturally

[extracted from the Pod...]

NAME
     Sort::Naturally -- sort lexically, but sort numeral parts
     numerically

SYNOPSIS
       @them = nsort(qw(
        foo12a foo12z foo13a foo 14 9x foo12 fooa foolio Foolio Foo12a
       ));
       print join(' ', @them), "\n";

     Prints:

       9x 14 foo fooa foolio Foolio foo12 foo12a Foo12a foo12z foo13a

     (Or "foo12a" + "Foo12a" and "foolio" + "Foolio" and might be
     switched, depending on your locale.)

DESCRIPTION
     This module exports two functions, nsort and ncmp; they are
     used in implementing my idea of a "natural sorting"
     algorithm.  Under natural sorting, numeric substrings are
     compared numerically, and other word-characters are compared
     lexically.

     This is the way I define natural sorting:

     o    Non-numeric word-character substrings are sorted
          lexically, case-insensitively: "Foo" comes between
          "fish" and "fowl".

     o    Numeric substrings are sorted numerically:  "100" comes
          after "20", not before.

     o    \W substrings (neither words-characters nor digits) are
          ignored.

     o    Our use of \w, \d, \D, and \W is locale-sensitive:
          Sort::Naturally uses a use locale statement.

     o    When comparing two strings, where a numeric substring
          in one place is not up against a numeric substring in
          another, the non-numeric always comes first.  This is
          fudged by reading pretending that the lack of a number
          substring has the value -1, like so:

            foo       =>  "foo",  -1
            foobar    =>  "foo",  -1,  "bar"
            foo13     =>  "foo",  13,
            foo13xyz  =>  "foo",  13,  "xyz"

          That's so that "foo" will come before "foo13", which
          will come before "foobar".

     o    The start of a string is exceptional: leading non-\W
          (non-word, non-digit) components are are ignored, and
          numbers come before letters.

     o    I define "numeric substring" just as sequences matching
          m/\d+/ -- scientific notation, commas, decimals, etc.,
          are not seen.  If your data has thousands separators in
          numbers ("20,000 Leagues Under The Sea" or "20.000
          lieues sous les mers"), consider stripping them before
          feeding them to nsort or ncmp.

[end Pod extract]


INSTALLATION

You install Sort::Naturally, as you would install any perl module
library, by running these commands:

   perl Makefile.PL
   make
   make test
   make install

If you want to install a private copy of Sort::Naturally in your home
directory, then you should try to produce the initial Makefile with
something like this command:

  perl Makefile.PL LIB=~/perl

See perldoc perlmodinstall for more information on installing modules.


DOCUMENTATION

POD-format documentation is included in Naturally.pm.  POD is readable
with the 'perldoc' utility.  See ChangeLog for recent changes.


SUPPORT

Questions, bug reports, useful code bits, and suggestions for
Sort::Naturally should just be sent to me at sburke@cpan.org


AVAILABILITY

The latest version of Sort::Naturally is available from the
Comprehensive Perl Archive Network (CPAN).  Visit
<http://www.perl.com/CPAN/> to find a CPAN site near you.


COPYRIGHT

Copyright 2001, Sean M. Burke <sburke@cpan.org>, all rights
reserved.

The programs and documentation in this dist are distributed in
the hope that they will be useful, but without any warranty; without
even the implied warranty of merchantability or fitness for a
particular purpose.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.