Overview

The general idea behind this package is to take a number, convert that number to an abstract representation of its spoken form and finally render that representation to a Text value.

Numerals are represented by a small expression language defined in the Text.Numeral.Exp module.

Conversion from numbers to numerals is the responsibility of rules. The Rule type itself and a number of useful rules are defined in the Text.Numeral.Rules module.

Finally, the Text.Numeral.Render module is responsible for converting the numeral expression language to a Text value. This happens via the render function. Render is parametrised with a Repr value and with an Inflection. The Repr contains all the knowledge on how to convert the abstract expression to a concrete Text value. The Inflection is used for languages where number words change based on a number of grammatical categories such as case, gender or number.

The use of this package is best understood with some examples. First some English number names, both British and US variants:

>>> import qualified Text.Numeral.Language.EN as EN
>>> EN.uk_cardinal defaultInflection 123 :: Maybe Text
Just "one hundred and twenty-three"
>>> EN.us_cardinal defaultInflection (10^50 + 42) :: Maybe Text
Just "one hundred quindecillion forty-two"

French, which contains some traces of a base 20 system:

>>> import qualified Text.Numeral.Language.FR as FR
>>> FR.cardinal defaultInflection (-99) :: Maybe Text
Just "moins quatre-vingt-dix-neuf"

Conversions can fail. Alamblak, a language spoken by a few people in Papua New Guinea, has no representation for negative numbers:

>>> import qualified Text.Numeral.Language.AMP as AMP
>>> AMP.cardinal defaultInflection (-3) :: Maybe Text
Nothing

Some languages have multiple scripts and methods for writing number names. Take Chinese for example, which can be written using Han characters or transcribed to the Latin script using Pinyin.

Traditional Chinese characters:

>>> import qualified Text.Numeral.Language.ZH as ZH
>>> ZH.trad_cardinal defaultInflection 123456 :: Maybe Text
Just "十二萬三千四百五十六"

Simplified characters for use in financial contexts:

>>> ZH.finance_simpl_cardinal defaultInflection 123456 :: Maybe Text
Just "拾贰万参仟肆伯伍拾陆"

Transcribed using Pinyin:

>>> ZH.pinyin_cardinal defaultInflection 123456 :: Maybe Text
Just "shíèrwàn sānqiān sìbǎi wǔshí liù"

Using the struct functions you can see the grammatical structure of number names. Because the results of these functions are polymorphic you need to specify a specific type.

>>> import qualified Text.Numeral.Language.NL as NL
>>> NL.struct 123 :: Integer
123
>>> import Text.Numeral
>>> NL.struct 123 :: Exp
Add (Lit 100) (Add (Lit 3) (Mul (Lit 2) (Lit 10)))

Compare with:

>>> NL.cardinal defaultInflection 123 :: Maybe Text
Just "honderddrieëntwintig"

100 (honderd) + (3 (drie) + (ën) 2 (twin) * 10 (tig))