MATLAB Examples

NUM2WORDS Examples

The function NUM2WORDS converts a numeric scalar into a string with the number value given in English words, e.g. 1024 -> 'one thousand and twenty-four'. Optional arguments control the handling of the numeric input, as well as many string formatting and dialect options. The options are explained in this document, together with examples.

The number format is based on http://www.blackwasp.co.uk/NumberToWords.aspx

Contents

Basic Usage

For integer values NUM2WORDS can be called without any options:

num2words(0)
num2words(+1024)
num2words(-1024)
ans =
zero
ans =
one thousand and twenty-four
ans =
negative one thousand and twenty-four

Decimal Digits

NUM2WORDS rounds the number value to the digit specified by the order or sigfig options: sigfig rounds the input value to the requested number of significant figures, while order rounds to the specified order. The default order is zero, which means that all fractional digits are rounded to give an integer. Decimal digits can therefore be returned by selecting an appropriate value for either the order or sigfig options:

num2words(1.234) % default 'order' is zero
num2words(1.234, 'order',-2)
num2words(1.234, 'sigfig',3)
ans =
one
ans =
one point two three
ans =
one point two three

Trailing Zeros

If the trailing decimal digits are zeros, then by default they are not returned in the string. Setting the trz option to true will keep the trailing zeros up to the requested order or sigfig:

num2words(1, 'sigfig',3, 'trz',false) % default
num2words(1, 'sigfig',3, 'trz',true)
ans =
one
ans =
one point zero zero

Floating-Point Precision

NUM2WORDS has internal limits on the significant figures for all floating-point numbers: 15 for double, and 6 for single. These limits ensure that the least-unexpected output is returned. As NUM2WORDS is based around SPRINTF, an SPRINTF example shows why this is required:

sprintf('%#.15g',1e23) % fifteen significant figures
sprintf('%#.16g',1e23) % sixteen significant figures
ans =
1.00000000000000e+023
ans =
9.999999999999999e+022

Integer Precision

In contrast, all integer class numbers are parsed at their full precision (even UINT64, and positive and negative INT64 values):

num2words(intmax('uint64'))
num2words(intmin('int64'), 'pos',true)
num2words(intmax('int64'), 'pos',true)
ans =
eighteen quintillion, four hundred and forty-six quadrillion, seven hundred and forty-four trillion, seventy-three billion, seven hundred and nine million, five hundred and fifty-one thousand, six hundred and fifteen
ans =
negative nine quintillion, two hundred and twenty-three quadrillion, three hundred and seventy-two trillion, thirty-six billion, eight hundred and fifty-four million, seven hundred and seventy-five thousand, eight hundred and eight
ans =
positive nine quintillion, two hundred and twenty-three quadrillion, three hundred and seventy-two trillion, thirty-six billion, eight hundred and fifty-four million, seven hundred and seventy-five thousand, eight hundred and seven

Type: Decimal

The default type: it can be used for all integer and decimal fraction values. All of the above examples use this number type.

Type: Ordinal

The last number word is changed to have an ordinal ending:

num2words(1, 'type','ordinal')
num2words(12, 'type','ordinal')
num2words(123, 'type','ordinal')
ans =
first
ans =
twelfth
ans =
one hundred and twenty-third

Type: Highest

This uses the highest multiplier/scale (i.e. only one multiplier word) together with a significand that includes decimal digits when required. In most cases it will be useful to also specify the number of significant figures:

num2words(1234567.89, 'type','highest')
num2words(1234567.89, 'type','highest', 'sigfig',2)
ans =
one point two three four five six eight million
ans =
one point two million

Type: Money

Treats the number as being a value of currency, and returns a string that contains the currency unit and subunit names. The currency subunit is 1/100 of the unit, which suits almost all currencies in the world today. The currency unit and subunit names can be supplied as string arguments: the string format also selects whether the name has a regular, irregular or invariant plural form (see the NUM2WORDS help for details).

Note that the default order is changed to -2, to match the subunit.

num2words(23.5, 'type','money')
num2words(23.5, 'type','money', 'unit','Pound|', 'subunit','Penny|Pence')
num2words(101,  'type','money', 'unit','Dalmatian|', 'case','title')
num2words(1001, 'type','money', 'unit','Night|', 'case','title')
ans =
twenty-three dollars and fifty cents
ans =
twenty-three pounds and fifty pence
ans =
One Hundred and One Dalmatians
ans =
One Thousand and One Nights

Type: Cheque

Similar to money, but follows the style used in many countries: if no trailing subunits then the units are followed by the word 'only', and leading units are always indicated, even if they are zero (preventing fraud):

num2words(5.0,'type','cheque')
num2words(0.5,'type','cheque')
ans =
five dollars only
ans =
zero dollars and fifty cents

String: Capitalisation

The default returns a lower-case string. It is also possible to select upper-case, title-case (all words except 'and' have an initial capital letter) and sentence-case (only the first word has an initial capital):

num2words(-1023,'case','lower') % default
num2words(-1023,'case','upper')
num2words(-1023,'case','title')
num2words(-1023,'case','sentence')
ans =
negative one thousand and twenty-three
ans =
NEGATIVE ONE THOUSAND AND TWENTY-THREE
ans =
Negative One Thousand and Twenty-Three
ans =
Negative one thousand and twenty-three

String: Grammar

There are some string formatting options that allow for different English dialects and style guidelines. The option defaults can be changed inside the mfile, if you wish to make another English dialect the default.

num2words(10000234,'and',true,'comma',true, 'hyphen',true) % default
num2words(10000234,'and',false,'comma',false, 'hyphen',false)
ans =
ten million, two hundred and thirty-four
ans =
ten million two hundred thirty four

String: 'Positive' Prefix

NUM2WORDS always prepends 'negative' for negative number values (including negative zero). The 'positive' prefix is optional:

num2words(1, 'pos',false) % default
num2words(1, 'pos',true)
ans =
one
ans =
positive one

Number Scales

NUM2WORDS supports a number of common and not-so-common number scales:

  • short and long scales are explained on many websites. Most contemporary English dialects use the short scale (and this is the NUM2WORDS default).
  • indian number system is commonly used in South Asia (the Indian subcontinent). Defaults back to short for values greater than 1e21.
  • peletier scale is used in many non-english speaking european countries.
  • rowlett scale was designed to avoid the ambiguity of the short and long scales.
  • knuth scale (aka -yllion) uses a logarithmic naming system to use very few names to cover a very wide range of values.
num2words(1e9, 'scale','short') % default
num2words(1e9, 'scale','long')
num2words(1e9, 'scale','peletier')
num2words(1e9, 'scale','rowlett')
num2words(1e9, 'scale','indian')
num2words(1e9, 'scale','knuth')
ans =
one billion
ans =
one thousand million
ans =
one milliard
ans =
one gillion
ans =
one hundred crore
ans =
ten myllion

Reverse Conversion: WORDS2NUM

The function WORDS2NUM converts a string (with a number given in English words) into a numeric value.