File Exchange

image thumbnail

Number to Words

version 3.5.1 (40.8 KB) by Stephen Cobeldick
Convert a number to a string giving the English name of the number value (GB/IN/US).

15 Downloads

Updated 09 Jul 2020

View Version History

View License

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

NUM2WORDS converts 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, intX, or uintX. 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 magnitude.
* the number of significant digits or order of magnitude.
* 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 greater than zero
* the numbering scale: short / long / Indian / Peletier / Rowlett / Knuth (-yllion).
* currency unit names (Pound, Pence, Dollar, Cents, Rupees, etc).

### Bonus Functions / Scripts ###

* NUM2WORDS_TEST contains thousands of test cases.
* NUM2WORDS_DEMO compares the output of NUM2WORDS against real-world examples.
* NUM2WORDS_RAT converts a numeric to a string with an improper fraction in words.
* NUM2WORDSQ is a minimalist version without any options, but twice as fast.

### Reverse Conversion ###

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')
>> sprintf('%s Under the Sea',num2words(2e4, 'type','money', 'unit','League|', 'case','title'))

Cite As

Stephen Cobeldick (2021). Number to Words (https://www.mathworks.com/matlabcentral/fileexchange/47221-number-to-words), MATLAB Central File Exchange. Retrieved .

Comments and Ratings (11)

Victor Villar

Vikas Sharma

Lakost

MOHIT

YiHua Zhou

Sadman Sakib Sayor

John D'Errico

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

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.

MATLAB Release Compatibility
Created with R2010b
Compatible with R2009a and later releases
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!