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 () { $thobject }

         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

     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.