File Exchange

image thumbnail

Number to Words

version 3.4 (22.2 KB) by

Convert a number to a string giving the English name of the number value (GB/IN/US).

36 Downloads

Updated

View License

Editor's Note: This file was selected as MATLAB Central Pick of the Week

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 ###

http://www.mathworks.com/matlabcentral/fileexchange/52925-words-to-number

### Examples ###

num2words(0)
ans = 'zero'

num2words(1024)
ans = 'one thousand and twenty-four'
num2words(-1024)
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']

Comments and Ratings (7)

MOHIT

MOHIT (view profile)

YiHua Zhou

John D'Errico

John D'Errico (view profile)

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.

Stephen Cobeldick

Based on the comment from John D'Errico, now supports money/cheque number types.

Stephen Cobeldick

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.

John D'Errico

John D'Errico (view profile)

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.

Updates

3.4

* Check for cell array optional inputs.

3.3

* Include HTML _DOC file in zip.

3.3

* Change HTML documentation filename.

3.3

* Add HTML directory

3.3

* Rename "myriad" scale to "knuth".
* Add published HTML documentation.

3.2

* Improve documentation.
* Consistent internal variable names.

3.1

* Update license.

3.0

* Add 'india' number scale (lakh and crore).
* Fix bugs in rounding of integer class numerics (for large sigfigs).

2.2

* Simplify cell array creation.

2.1

* Fix bug in myriad parsing (if >1 highest level multiplier).
* More robust fraction handling for all number scales.
* Smaller file-size.

2.0

* Add a new <scale> option <myriad> (Knuth's -yllion).
* Rename option <ae> as <and>.

1.9

* More robust handling of some edge cases: zero, NaN, Inf.
* Fraction function accepts name-value or structure input arguments.

1.8

- Minor edit in blurb.

1.7

- Minor edit to FEX blurb.

1.6

* Add money/cheque number type.
* Allow options to be supplied as name-value pairs.

1.5

- I accidentally uploaded an older version. This version matches the online description :)

1.4

* comma control option.
* scale control option (short, long, Rowlett, Peletier).
* all names upto realmax.
* limit significant figures for floats.
* remove option <cardinal>.
* change option value 'ame' -> 'ae'.
* option fields case insensitive.

1.3

- Downloadable as toolbox

1.2

- Fix bug for ordinals 'first' and 'second'.
- Expand options table with more examples.

1.1

- Improve decimal fraction handling.
- Improve input checking.

MATLAB Release
MATLAB 7.11 (R2010b)

Download apps, toolboxes, and other File Exchange content using Add-On Explorer in MATLAB.

» Watch video

Win prizes and improve your MATLAB skills

Play today