X-Git-Url: http://wagnertech.de/gitweb/gitweb.cgi/mfinanz.git/blobdiff_plain/0fa5eadc89319dc8680654e47354baafe394c3e3..75b851fe9801db7aba240e3092f71553d78488d7:/doc/modules/README.Sort-Naturally

diff --git a/doc/modules/README.Sort-Naturally b/doc/modules/README.Sort-Naturally
new file mode 100644
index 000000000..4fa4f1e72
--- /dev/null
+++ b/doc/modules/README.Sort-Naturally
@@ -0,0 +1,124 @@
+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.