WORDS2NUM Examples

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

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

In the WORDS2NUM documentation the word string refers to a 1xN character vector, and not to the MATLAB string class.

Contents

Basic Usage

For many integer and decimal values WORDS2NUM can be called without any options. WORDS2NUM will match integers, fractional digits following the word 'point', and magnitude words (e.g. 'million', 'billion', etc.):

words2num('zero')
words2num('infinity')
words2num('negative one thousand and twenty-four')
words2num('one point two three')
words2num('twelve hundred')
words2num('nine point eight million'), format longg
words2num('five billion, six million, seven thousand and eight'), format shortg
ans =
     0
ans =
   Inf
ans =
       -1024
ans =
                      1.23
ans =
        1200
ans =
     9800000
ans =
                5006007008

Numeric Class

The class of the numeric output can be selected using the class option: all relevant internal numeric operations are performed in that class.

words2num('one centillion', 'class','double') % default
words2num('one centillion', 'class','uint8')  % information may be lost!
words2num('eighteenpointfourfoursixsevenfourfourzeroseventhreesevenzeroninefivefiveonesixonefivequintillion','class','uint64') % full precision!
ans =
       1e+303
ans =
  255
ans =
 18446744073709551615

Outputs

Because the string detection is based on REGEXP it is possible to detect any number strings inside of longer strings. WORDS2NUM returns a vector of the converted numbers, and a cell array of the input string parts that were split by the detected number strings:

[num,spl] = words2num('HelloOneThousandAndTwentyFourWorld!')
[num,spl] = words2num('beforeonehundredmiddletwohundredafter')
num =
        1024
spl = 
    'Hello'    'World!'
num =
   100   200
spl = 
    'before'    'middle'    'after'

Character Case

The number strings can be matched depending on the character case:

words2num('One Thousand and TWENTY-four', 'case','ignore') % default
words2num('One Thousand and TWENTY-four', 'case','title')
words2num('One Thousand and TWENTY-four', 'case','upper')
words2num('One Thousand and TWENTY-four', 'case','lower')
ans =
        1024
ans =
        1000
ans =
    20
ans =
     4

Sign Prefix

By default a 'positive' or 'negative' prefix is automatically detected. It is possible to select to require the sign prefix, or to ignore it:

words2num('positive one, two, negative three','sign',[]) % default
words2num('positive one, two, negative three','sign',true) % require
words2num('positive one, two, negative three','sign',false) % ignore
ans =
     1     2    -3
ans =
     1    -3
ans =
     1     2     3

Number Formatting

Other features or string formatting may be selected to be required or excluded from the number strings. These features are optional by default, but may be required/excluded by specifying the corresponding option:

words2num('nine million, eight thousand', 'comma',true) % require
words2num('nine million, eight thousand', 'comma',false) % exclude
words2num('one thousand and twenty-four', 'hyphen',false) % exclude
words2num('one thousand and twenty-four', 'space',false) % exclude
words2num('one thousand and twenty-four', 'and',false) % exclude
ans =
     9008000
ans =
     9000000        8000
ans =
        1020           4
ans =
     1    24
ans =
        1000          24

Whitespace Characters

One or more whitespace characters may also be specified, these may include regular expression meta-characters, i.e. \s, \t, etc.:

words2num('one_thousand_and twenty four', 'white','_\s')
words2num('one.thousand.and twenty four', 'white',' .')
ans =
        1024
ans =
        1024

Prefix and Suffix

Using REGEXP allows the number string to only be matched when the requested prefix and/or suffix regular expressions are matched. For example it is possible to specify lookarounds that must be matched:

[num,spl] = words2num('two cats three hats')
[num,spl] = words2num('two cats three hats','prefix','^') % only match start of string
[num,spl] = words2num('two cats three hats','suffix','(?=\sh)') % lookaround: ' h'
num =
     2     3
spl = 
    ''    ' cats '    ' hats'
num =
     2
spl = 
    ''    ' cats three hats'
num =
     3
spl = 
    'two cats '    ' hats'

Number Scale

Several common and not-so-common number scales are supported:

words2num('one billion', 'scale','short')
words2num('one thousand million', 'scale','long')
words2num('one milliard', 'scale','peletier')
words2num('one gillion', 'scale','rowlett')
words2num('ten myllion', 'scale','knuth')
ans =
        1e+09
ans =
        1e+09
ans =
        1e+09
ans =
        1e+09
ans =
        1e+09

Compound Magnitude Words

This is still a little bit experimental, but there is an option to allow parsing of compound magnitude words:

words2num('one million', 'mag','simple') % default
words2num('one thousand thousand', 'mag','compound')
words2num('two point three trillion trillion trillion', 'mag','compound')
ans =
     1000000
ans =
     1000000
ans =
      2.3e+36

Reverse Conversion: NUM2WORDS

The function NUM2WORDS converts a numeric scalar into a string with the number value given in English words:

num2words(1024)
ans =
one thousand and twenty-four