README for Lingua::EN::Numbers::Ordinate
                                        Time-stamp: "2000-08-24 16:59:23 MDT"

		    Lingua::EN::Numbers::Ordinate

[Partially excerpted from the POD.]


     Lingua::EN::Numbers::Ordinate -- go from cardinal number (3)
     to ordinal ("3rd")

SYNOPSIS
       use Lingua::EN::Numbers::Ordinate;
       print ordinate(4), "\n";
        # prints 4th
       print ordinate(-342), "\n";
        # prints -342nd

       # Example of actual use:
       ...
       for(my $i = 0; $i < @records; $i++) {
         unless(is_valid($record[$i]) {
           warn "The ", ordinate($i), " record is invalid!\n";
           next;
         }
         ...
       }

DESCRIPTION
     There are two kinds of numbers in English -- cardinals (1,
     2, 3...), and ordinals (1st, 2nd, 3rd...).  This library
     provides functions for giving the ordinal form of a number,
     given its cardinal value.

FUNCTIONS
     ordinate(SCALAR)
          Returns a string consisting of that scalar's string
          form, plus the appropriate ordinal suffix.  Example:
          ordinate(23) returns "23rd".

          As a special case, ordinate(undef) and ordinate("")
          return "0th", not "th".

          This function is exported by default.

     th(SCALAR)
          Merely an alias for ordinate, but not exported by
          default.

     ordsuf(SCALAR)
          Returns just the appropriate ordinal suffix for the
          given scalar numeric value.  This is what ordinate uses
          to actually do its work.  For example, ordsuf(3) is
          "rd".

          Not exported by default.

     The above functions are all prototyped to take a scalar
     value, so ordinate(@stuff) is the same as ordinate(scalar
     @stuff).

CAVEATS
     * Note that this library knows only about numbers, not
     number-words.  ordinate('seven') might just as well be
     ordinate('superglue') or ordinate("\x1E\x9A") -- you'll get
     the fallthru case of the input string plus "th".

     * As is unavoidable, ordinate(0256) returns "174th" (because
     ordinate sees the value 174). Similarly, ordinate(1E12)
     returns "1000000000000th".  Returning "trillionth" would be
     nice, but that's an awfully atypical case.

     * Note that this library's algorithm (as well as the basic
     concept and implementation of ordinal numbers) is totally
     language specific.

     To pick a trivial example, consider that in French, 1
     ordinates as "1ier", whereas 41 ordinates as "41ieme".

STILL NOT SATISFIED?
     Bored of this...?

       use Lingua::EN::Numbers::Ordinate qw(ordinate th);
       ...
       print th($n), " entry processed...\n";
       ...

     Try this bit of lunacy:

       {
         my $th_object;
         sub _th () { $th_object }

         package Lingua::EN::Numbers::Ordinate::Overloader;
         my $x; # Gotta have something to bless.
         $th_object = bless \$x; # Define the object now, which _th returns
         use Carp ();
         use Lingua::EN::Numbers::Ordinate ();
         sub overordinate {
           Carp::croak "_th should be used only as postfix!" unless $_[2];
           Lingua::EN::Numbers::Ordinate::ordinate($_[1]);
         }
         use overload '&' => \&overordinate;
       }

     Then you get to do:

       print 3 & _th, "\n";
         # prints "3rd"

       print 1 + 2 & _th, "\n";
         # prints "3rd" too!
         # Because of the precedence of & !

       print _th & 3, "\n";
         # dies with: "th should be used only as postfix!"

     Kooky, isn't it?  For more delightful deleria like this, see
     Damian Conway's Object Oriented Perl from Manning Press.

     Kinda makes you like th(3), doesn't it?

COPYRIGHT
     Copyright (c) 2000 Sean M. Burke.  All rights reserved.

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

AUTHOR
     Sean M. Burke sburke@cpan.org


[End of POD excerpt]

PREREQUISITES

This suite requires Perl 5; I've only used it under Perl 5.004, so for
anything lower, you're on your own.

Lingua::EN::Numbers::Ordinate doesn't use any nonstandard modules.


INSTALLATION

You install Lingua::EN::Numbers::Ordinate, 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 Lingua::EN::Numbers::Ordinate
in your home directory, then you should try to produce the initial
Makefile with something like this command:

  perl Makefile.PL LIB=~/perl


DOCUMENTATION

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


MACPERL INSTALLATION NOTES

You needn't bother with the makefiles.  Just make a Lingua directory
in your MacPerl site_lib or lib directory, an EN directory under that,
and a Numbers directory under that, and move Ordinate.pm into there.


SUPPORT

Questions, bug reports, useful code bits, and suggestions for
Lingua::EN::Numbers::Ordinate should just be sent to me at sburke@cpan.org


AVAILABILITY

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