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 to find a CPAN site near you.