Convert a numeric scalar to a string with the number value given in English words: for example the value 1024 is returned as 'one thousand and twenty-four'.
NUM2WORDS accepts a scalar of any standard numeric class: single, double, int, or uint. Integer types are parsed with their full precision, while floating types have internal precision limits to ensure least-unexpected output.
Options allows the user to select:
* the number type selection: ordinal / decimal / cheque / money / highest multiplier.
* the number of significant digits or order of precision.
* upper / lower / title / sentence case.
* trailing zeros or without.
* the use of a comma between magnitude groups.
* the use of a hyphen between tens and ones.
* the use of 'and' before the tens/ones (required in British and Commonwealth English).
* a 'positive' prefix for values >=+0.
* the numbering scale: short / long / Indian / Peletier / Rowlett / Knuth (-yllion).
* currency unit names (Pound, Pence, Dollar, Cents, Rupees, etc).
### Bonus Functions / Scripts ###
Three bonus files are also included:
* NUM2WORDS_DEMO compares the output of NUM2WORDS with real-world example numbers.
* NUM2WORDS_FAST is a minimalist version without any options, but twice as fast.
* NUM2WORDS_RAT converts a numeric to a string with an improper fraction in words.
### Convert Words to Numbers ###
### Examples ###
ans = 'zero'
ans = 'one thousand and twenty-four'
ans = 'negative one thousand and twenty-four'
num2words(1024, 'pos',true, 'case','title', 'hyphen',false)
ans = 'Positive One Thousand and Twenty Four'
num2words(1024, struct('type','ordinal', 'case','sentence'))
ans = 'One thousand and twenty-fourth'
num2words(1024, 'and',false, 'order',1) % round to the tens.
ans = 'one thousand twenty'
num2words(pi, 'order',-10) % round to tenth decimal digit
ans = 'three point one four one five nine two six five three six'
num2words(intmax('uint64'), 'sigfig',3, 'comma',false)
ans = 'eighteen quintillion four hundred quadrillion'
num2words(intmax('uint64'), 'sigfig',3, 'type','highest')
ans = 'eighteen point four quintillion'
num2words(intmax('uint64'), 'sigfig',3, 'scale','long')
ans = 'eighteen trillion, four hundred thousand billion'
num2words(intmax('uint64'), 'sigfig',3, 'case','title', 'scale','indian')
ans = 'One Lakh, Eighty-Four Thousand Crore Crore'
num2words(intmax('uint64'), 'order',17, 'case','upper', 'scale','knuth')
ans = 'EIGHTEEN HUNDRED FORTY BYLLION'
num2words(1234.56, 'type','cheque', 'unit','Euro')
ans = 'one thousand, two hundred and thirty-four euro and fifty-six cents'
num2words(1234.56, 'type','cheque', 'unit','Pound|', 'subunit','Penny|Pence')
ans = 'one thousand, two hundred and thirty-four pounds and fifty-six pence'
num2words(101, 'type','money', 'unit','Dalmatian|', 'case','title')
num2words(1001, 'type','money', 'unit','Night|', 'case','title')
[num2words(2e4, 'type','money', 'unit','League|', 'case','title'), ' Under the Sea']
Oh well, I guess my promise of a sixth star was an empty one, with a 5 star limit on the FEX. :)
Well done anyway. This does everything I can think of in the way of converting numbers to a textual form.
Based on the comment from John D'Errico, now supports money/cheque number types.
John D'Errico: Thank you for your feedback.
A money 'type' would be interesting, but limiting it to dollars/cents would definitely start a culture-war on FEX, and the subunit handling is challenging: some currencies use a ratio other than 1/100 to define the subunit, a few currencies don't even have subunits, and the Yen has two subunits. So it would require an option for the user to supply their currency name/s, some complicated subunit handling, and a way to decide whether to use 'only' or not (value:no, cheque:yes). As the 'money' option is basically just repeated applications of the function, I figured an example would suffice.
Lots of options to control the style of your output. Good help. Well done.
I was surprised not to see a direct money option though. So a 'type' of 'dollars' might have been useful and interesting. I'd have had to figure out how to give it an extra star then.
* Check for cell array optional inputs.
* Include HTML _DOC file in zip.
* Change HTML documentation filename.
* Add HTML directory
* Rename "myriad" scale to "knuth".
* Improve documentation.
* Update license.
* Add 'india' number scale (lakh and crore).
* Simplify cell array creation.
* Fix bug in myriad parsing (if >1 highest level multiplier).
* Add a new <scale> option <myriad> (Knuth's -yllion).
* More robust handling of some edge cases: zero, NaN, Inf.
- Minor edit in blurb.
- Minor edit to FEX blurb.
* Add money/cheque number type.
- I accidentally uploaded an older version. This version matches the online description :)
* comma control option.
- Downloadable as toolbox
- Fix bug for ordinals 'first' and 'second'.
- Improve decimal fraction handling.
Inspired by: text2speech - tts, num2english, text-to-speech, Variable Precision Integer Arithmetic, Number to Scientific Prefix, Text2Speech for Matlab using unofficial google service, Date Vector/Number to ISO 8601 Date String, Customizable Natural-Order Sort, ISO 8601 Date String to Serial Date Number, Numeric to Ordinal-String, Natural-Order Row Sort, Natural-Order Filename Sort, Convert number to words, Number to Myriad, Words to Number
Inspired: ISO 8601 Date String to Serial Date Number, Date Vector/Number to ISO 8601 Date String, Numeric to Ordinal-String, Natural-Order Row Sort, Natural-Order Filename Sort, Customizable Natural-Order Sort, Scientific Prefix to Number, Number to Scientific Prefix, Interactive Regular Expression Tool, Round to Electronic Component Values, Number to Myriad, Words to Number
Download apps, toolboxes, and other File Exchange content using Add-On Explorer in MATLAB.