NAME Lingua::EN::Numbers
Various numberstring conversion utility routines.
Convert numbers to their cardinal or ordinal representation.
Several other numeric string "prettifying" routines.
SYNOPSIS
use Lingua::EN::Numbers;
# Integers
say cardinal(42); # fortytwo
say cardinal('144'); # one hundred fortyfour
say cardinal(76541); # seventysix thousand, five hundred fortyone
# Rationals
say cardinal(7/2); # three and one half
say cardinal(7/2, :improper); # seven halves
say cardinal(7/2, :im ); # seven halves
say cardinal(15/4) # three and three quarters
say cardinal(3.75) # three and three quarters
say cardinal(15/4, :improper) # fifteen quarters
say cardinal('3/16'); # three sixteenths
# Years
say cardinalyear(1800) # eighteen hundred
say cardinalyear(1905) # nineteen ohfive
say cardinalyear(2000) # two thousand
say cardinalyear(2015) # twenty fifteen
# cardinal vs. cardinalyear
say cardinal(1776); # one thousand, seven hundred seventysix
say cardinalyear(1776) # seventeen seventysix
# Sometimes larger denominators make it difficult to discern where the
# numerator ends and the denominator begins. Change the separator to
# make it easier to tell.
say cardinal(97873/10000000);
# ninety seven thousand, eight hundred seventythree ten millionths
say cardinal(97873/10000000, :separator(' / '));
# ninety seven thousand, eight hundred seventythree / ten millionths
# If you want to use a certain denominator in the display and not reduce
# fractions, specify a common denominator.
say cardinal(15/1000); # three two hundredths
say cardinal(15/1000, :denominator(1000)); # fifteen thousandths
# or
say cardinal(15/1000, denominator => 1000); # fifteen thousandths
# or
say cardinal(15/1000, :den(1000) ); # fifteen thousandths
# Ordinals
say ordinal(1); # first
say ordinal(2); # second
say ordinal(123); # one hundred twentythird
# Ordinal digit
say ordinaldigit(22); # 22nd
say ordinaldigit(1776); # 1776th
say ordinaldigit(331 :u); # 331ˢᵗ
# Use prettyrat() to print rational strings as fractions rather than
# as decimal numbers. Whole number fractions will be reduced to Ints.
say prettyrat(1.375); # 11/8
say prettyrat(8/2); # 4
# nocommas flag
# save state
my $state = nocommas?;
# disable commas
nocommas;
say cardinal(97873/10000000);
# ninety seven thousand eight hundred seventythree ten millionths
# restore state
nocommas($state);
# Commas routine
say comma( 5.0e9.Int ); # 5,000,000,000
say comma( 123456 ); # 123,456
say comma( 7832.00 ); # 7,832
say comma( '7832.00' ); # 7,832.00
Or, import the short form routine names:
use Lingua::EN::Numbers :short;
say card(42); # fortytwo
say cardy(2020) # twenty twenty
say ordn(42); # fortysecond
say ordd(42); # 42nd
say card(.875) # seven eights
say prat(.875); # 7/8
DESCRIPTION
Exports the Subs:

cardinal( )  short: card()

cardinalyear( )  short: cardy()

ordinal( )  short: ordn()

ordinaldigit( )  short: ordd()

prettyrat( )  short: prat()
and Flag:
Short form routine names are only available if you specifically import them:
use Lingua::EN::Numbers :short;
cardinal( )  short: card()
Returns cardinal representations of integers following the American English, short scale convention.
See: https://en.wikipedia.org/wiki/Long_and_short_scales
cardinal( $number, :separator($str), :denominator($val), :improper );

$number
 value; required, any Real number (Rat, Int, or Num)

:separator or :sep
 value; optional, separator between numerator and denominator, defaults to space. Ignored if a non Rat is passed in.

:denominator or :den
 value; optional, integer denominator to use for representation, do not reduce to lowest terms. Ignored if a non Rat is passed in.

:improper or :im
 flag; optional, do not regularize improper fractions. Ignored if a non Rat is passed in.
Pass cardinal()
a number or something that can be converted to one; returns its cardinal representation.
Recognizes integer numbers from: 9999999999999999999999999999999999999999999999999999999999999999999999999999 99999999999999999999999999999999999999999999999999999999999999999999999999999 99999999999999999999999999999999999999999999999999999999999999999999999999999 9999999999999999999999999999999999999999999999999999999999999999999999999999 to 99999999999999999999999999999999999999999999999999999999999999999999999999999 99999999999999999999999999999999999999999999999999999999999999999999999999999 99999999999999999999999999999999999999999999999999999999999999999999999999999 999999999999999999999999999999999999999999999999999999999999999999999999999
Thats 306 9s, negative, through positive:
nine hundred ninetynine centillion, nine hundred ninetynine novemnonagintillion, nine hundred ninetynine octononagintillion, nine hundred ninetynine septennonagintillion, nine hundred ninetynine sexnonagintillion, nine hundred ninetynine quinnonagintillion, nine hundred ninetynine quattuornonagintillion, nine hundred ninetynine trenonagintillion, nine hundred ninetynine duononagintillion, nine hundred ninetynine unnonagintillion, nine hundred ninetynine nonagintillion, nine hundred ninetynine novemoctogintillion, nine hundred ninetynine octooctogintillion, nine hundred ninetynine septenoctogintillion, nine hundred ninetynine sexoctogintillion, nine hundred ninetynine quinoctogintillion, nine hundred ninetynine quattuoroctogintillion, nine hundred ninetynine treoctogintillion, nine hundred ninetynine duooctogintillion, nine hundred ninetynine unoctogintillion, nine hundred ninetynine octogintillion, nine hundred ninetynine novemseptuagintillion, nine hundred ninetynine octoseptuagintillion, nine hundred ninetynine septenseptuagintillion, nine hundred ninetynine sexseptuagintillion, nine hundred ninetynine quinseptuagintillion, nine hundred ninetynine quattuorseptuagintillion, nine hundred ninetynine treseptuagintillion, nine hundred ninetynine duoseptuagintillion, nine hundred ninetynine unseptuagintillion, nine hundred ninetynine septuagintillion, nine hundred ninetynine novemsexagintillion, nine hundred ninetynine octosexagintillion, nine hundred ninetynine septensexagintillion, nine hundred ninetynine sexsexagintillion, nine hundred ninetynine quinsexagintillion, nine hundred ninetynine quattuorsexagintillion, nine hundred ninetynine tresexagintillion, nine hundred ninetynine duosexagintillion, nine hundred ninetynine unsexagintillion, nine hundred ninetynine sexagintillion, nine hundred ninetynine novemquinquagintillion, nine hundred ninetynine octoquinquagintillion, nine hundred ninetynine septenquinquagintillion, nine hundred ninetynine sexquinquagintillion, nine hundred ninetynine quinquinquagintillion, nine hundred ninetynine quattuorquinquagintillion, nine hundred ninetynine trequinquagintillion, nine hundred ninetynine duoquinquagintillion, nine hundred ninetynine unquinquagintillion, nine hundred ninetynine quinquagintillion, nine hundred ninetynine novemquadragintillion, nine hundred ninetynine octoquadragintillion, nine hundred ninetynine septenquadragintillion, nine hundred ninetynine sexquadragintillion, nine hundred ninetynine quinquadragintillion, nine hundred ninetynine quattuorquadragintillion, nine hundred ninetynine trequadragintillion, nine hundred ninetynine duoquadragintillion, nine hundred ninetynine unquadragintillion, nine hundred ninetynine quadragintillion, nine hundred ninetynine novemtrigintillion, nine hundred ninetynine octotrigintillion, nine hundred ninetynine septentrigintillion, nine hundred ninetynine sextrigintillion, nine hundred ninetynine quintrigintillion, nine hundred ninetynine quattuortrigintillion, nine hundred ninetynine tretrigintillion, nine hundred ninetynine duotrigintillion, nine hundred ninetynine untrigintillion, nine hundred ninetynine trigintillion, nine hundred ninetynine novemvigintillion, nine hundred ninetynine octovigintillion, nine hundred ninetynine septenvigintillion, nine hundred ninetynine sexvigintillion, nine hundred ninetynine quinvigintillion, nine hundred ninetynine quattuorvigintillion, nine hundred ninetynine trevigintillion, nine hundred ninetynine duovigintillion, nine hundred ninetynine unvigintillion, nine hundred ninetynine vigintillion, nine hundred ninetynine novemdecillion, nine hundred ninetynine octodecillion, nine hundred ninetynine septendecillion, nine hundred ninetynine sexdecillion, nine hundred ninetynine quindecillion, nine hundred ninetynine quattuordecillion, nine hundred ninetynine tredecillion, nine hundred ninetynine duodecillion, nine hundred ninetynine undecillion, nine hundred ninetynine decillion, nine hundred ninetynine nonillion, nine hundred ninetynine octillion, nine hundred ninetynine septillion, nine hundred ninetynine sextillion, nine hundred ninetynine quintillion, nine hundred ninetynine quadrillion, nine hundred ninetynine trillion, nine hundred ninetynine billion, nine hundred ninetynine million, nine hundred ninetynine thousand, nine hundred ninetynine
Handles Rats limited to the integer limits for the numerator and denominator.
When converting rational numbers, the word "and" is inserted between any whole number portion and the fractional portions of the number. If you have an "and" in the output, the input number had a fractional portion.
By default, cardinal()
reduces fractions to their lowest terms. If you want to specify the denominator used to display, pass in an integer to the :denominator option.
It is probably best to specify a denominator that is a common divisor for the denominator. cardinal()
will work with any integer denominator, and will scale the numerator to match, but will round off the numerator to the nearest integer after scaling, so some error will creep in if denominator is NOT a common divisor with the denominator.
Recognizes Nums up to about 1.79e308. (2¹⁰²⁴  1)
When converting Nums, reads out the enumerated digits for the mantissa and returns the ordinal exponent.
E.G. cardinal(2.712e7)
will return:
two point seven one two times ten to the seventh
If you want it to be treated like an integer or rational, coerce it to the appropriate type.
cardinal(2.712e7.Int)
to get:
twentyseven million, one hundred twenty thousand
cardinal(1.25e3)
returns:
one point two five times ten to the negative third
cardinal(1.25e3.Rat)
returns:
one eight hundredth
cardinalyear( )  short: cardy()
Converts integers from 1 to 9999 to the common American English convention.
cardinalyear( $year, :oh($str) );

$year
 value; must be an integer between 1 and 9999 or something that can be coerced to an integer between 1 and 9999.

:oh
 value; optional, string to use for the "0" years after a millennium. Default 'oh'. Change to ' ought' or some other string if desired.
Follows the common American English convention for years:
2015 > twenty fifteen.
1984 > nineteen eightyfour.
Even millenniums are returned as thousands:
2000 > two thousand.
Even centuries are returned as hundreds:
1900 > nineteen hundred.
Years 1 .. 9 in each century are returned as ohs:
2001 > twenty ohone.
Configurable with the :oh parameter. Default is 'oh'. Change to 'ought' if you prefer twenty oughtone, or something else if that is your preference.
ordinal( )  short: ordn()
Takes an integer or something that can be coerced to an integer and returns a string similar to the cardinal() routine except it is positional rather than valuation.
E.G. 'first' rather than 'one', 'eleventh' rather than 'eleven'.
ordinal( $integer )

$integer
 value; an integer or something that can be coerced to a sensible integer value.
ordinaldigit( )  short: ordd()
Takes an integer or something that can be coerced to an integer and returns the given numeric value with the appropriate suffix appended to the number. 1 > 1st, 3 > 3rd, 24 > 24th etc.
ordinaldigit( $integer, :u )

$integer
 value; an integer or something that can be coerced to a sensible integer value.

:u
 boolean; enable Unicode superscript ordinal suffixes (ˢᵗ, ⁿᵈ, ʳᵈ, ᵗʰ). Default false.
comma( )
Insert commas into a numeric string following the English convention. Groups of 3ordersofmagnitude for whole numbers, fractional portions are unaffected.
comma( $number )

$number
 value; an integer, rational, intstring, ratstring or numeric string.
Will accept an Integer, IntString, Rational, RatString or a numeric string that looks like an Integer or Rational. Any nonsignificant leading zeros are dropped. Nonsignificant trailing zeros are dropped for numeric rationals. If you want to retain nonsignificant trailing zeros in Rats, pass the argument as a string.
prettyrat()  short: prat()
A "prettifying" routine to render rational numbers as a fraction. Rats that have a denominator of 1 will be rendered as integers.
prettyrat($number)

$number
 value; Any real number. Integers and Nums will be passed along unchanged; Rats will be converted to a fractional representation.
nocommas
A global flag for the cardinal()
and ordinal()
routines that disables / enables returning commas between 3orderofmagnitude groups.
nocommas( $bool )

$bool
 A truthy / falsey value to enable / disable inserting commas into spelled out numeric strings.
Takes a Boolean or any value that can be coerced to a Boolean as a flag to disable / enable inserting commas. Absence of a value is treated as True. E.G.
nocommas;
is the same as
nocommas(True);
to reenable inserting commas:
nocommas(False);
Disabled (False) by default. May be enabled and disabled as desired, even within a single block; the flag is global though, not lexical. If you disable commas deep within a block, it will affect all ordinal()
and cardinal()
calls afterwords, even in a different scope. If your script is part of a larger application, you may want to query the nocommas
state and restore it after any modification.
Query the nocommas flag state with:
my $state = nocommas?;
Returns the current flag state as a Boolean: True  commas disabled, False  commas enabled. Does not modify the current state.
Restore it with:
nocommas($state);
NOTE: the comma()
routine and nocommas
flag have nothing to do with each other, do not interact, and serve completely different purposes.
BUGS
Doesn't handle complex numbers. Does some cursory error trapping and coercion but the foot cannon is still loaded.
AUTHOR
Original Integer cardinal code by TimToady (Larry Wall).
See: http://rosettacode.org/wiki/Number_names#Raku
Other code by thundergnat (Steve Schulze).
LICENSE
Licensed under The Artistic 2.0; see LICENSE.