BlackWaspTM

This web site uses cookies. By using the site you accept the cookie policy.This message is for compliance with the UK ICO law.

Algorithms and Data Structures
.NET 1.1+

Convert A Number into Words

When developing commercial applications, particularly when those applications perform activities such as cheque printing, it can be necessary to display numeric values using the equivalent text. This article describes an algorithm to achieve this.

Algorithm Goals

There are many occasions when it is necessary to output a numeric value using text rather than numeric digits. A common example is the production of cheques. These usually require both the numeric and the spoken-word equivalent text to be printed. Unfortunately, the .NET framework does not provide a simple method by which this conversion can be made so a custom algorithm must be developed.

This article describes an algorithm that converts a numeric value into the equivalent text. It goes on to provide the C# code for this task. For simplicity, the article concentrates on the generation of English words for 32-bit integer values. However, you can extend the method easily to add other languages, decimal number conversion and currency information.

Large Number Names

The English names of the smaller numbers are generally accepted. However, once a number to be converted reaches a value of one thousand million or greater, the names of numbers vary according to usage. The algorithm described in this article uses the modern short scale numbering. In this scale, one thousand million is equivalent to one billion. This is different to the less-used traditional British long scale numbering where a billion is one million million.

The following table lists the short scale number names included in the algorithm and their numeric values. The range of numbers has been selected to provide for the full range of values that may be held in a 32-bit integer. If you wish to extend the functionality of the algorithm to larger numbers, a Wikipedia article exists that lists the names of large numbers.

ValueName
1one
10ten
100hundred
1,000thousand
1,000,000million
1,000,000,000billion

Number Rules

The set of rules for converting an integer number to text initially appear to be reasonably complex. However, once analysed, they can be separated into a small number of distinct rule groups that are simpler to implement individually. To provide a single algorithm for all integer values there are six such rule groups:

  • Zero Rule. If the value is zero then the number in words is 'zero' and no other rules apply.
  • Three Digit Rule. The integer value is split into groups of three digits starting from the right-hand side. Each set of three digits is then processed individually as a number of hundreds, tens and units. Once converted to text, the three-digit groups are recombined with the addition of the relevant scale number (thousand, million, billion).
  • Hundreds Rules. If the hundreds portion of a three-digit group is not zero, the number of hundreds is added as a word. If the three-digit group is exactly divisible by one hundred, the text 'hundred' is appended. If not, the text "hundred and" is appended. eg. 'two hundred' or 'one hundred and twelve'
  • Tens Rules. If the tens section of a three-digit group is two or higher, the appropriate '-ty' word (twenty, thirty, etc.) is added to the text and followed by the name of the third digit (unless the third digit is a zero, which is ignored). If the tens and the units are both zero, no text is added. For any other value, the name of the one or two-digit number is added as a special case.
  • Recombination Rules. When recombining the translated three-digit groups, each group except the last is followed by a large number name and a comma, unless the group is blank and therefore not included at all. One exception is when the final group does not include any hundreds and there is more than one non-blank group. In this case, the final comma is replaced with 'and'. eg. 'one billion, one million and twelve'.
  • Negative Rule. Negative numbers are always preceded by the text 'negative'.

The Algorithm and the Code

Preparation

Depending upon how you wish to use this algorithm, you may want to create it in a new class, incorporate it in an existing class or simply hide it behind a form event. To keep the code simple and short, this article assumes you have a class of some kind prepared and are adding a new method to that class. The code simply declares a new public method that accepts the integer to be converted as its only parameter.

To prepare, create or identify the class that you will add the method to, then add the following declaration code:

// Converts an integer value into English words
public string NumberToWords(int number)
{
}

NB: If you are creating or adding to a utilities class, you may wish to adjust the declaration to make the method static. If you do, all of the other declarations detailed below must also be marked as static.

Declaring the Names for Numbers

There are three key groups of names for numbers that must be declared. Firstly there are the small numbers between zero and nineteen that are used by the tens rule. The second group of numbers is used to represent the tens values from twenty to ninety. Finally we have the scale numbers. These are the large numbers that are used during recombination.

The number names must be stored within the program code in a manner that permits easy identification. In this example code, we will declare three arrays. An array of twenty items holds the small numbers, an array of ten items is used for the tens values (with two initial unused entries) and an array of four values contains the scale number names with the first entry containing an empty string.

As the code will eventually include private methods in addition to the public method already declared, the arrays are created as private class-level variables. This allows the arrays to be accessible by the entire class without being passed between functions. The numbers are defined in Title Case as this is aesthetically pleasing and can be easily converted to upper or lower case after the process is complete.

Add the following declarations to the class to declare and initialise the arrays:

// Single-digit and small number names
private string[] _smallNumbers = new string[]
    { "Zero", "One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine",
      "Ten", "Eleven", "Twelve", "Thirteen", "Fourteen", "Fifteen", "Sixteen", "Seventeen",
      "Eighteen", "Nineteen"};
     
// Tens number names from twenty upwards
private string[] _tens = new string[]
    { "", "", "Twenty", "Thirty", "Forty", "Fifty", "Sixty", "Seventy", "Eighty", "Ninety"};
     
// Scale number names for use during recombination
private string[] _scaleNumbers = new string[] {"", "Thousand", "Million", "Billion"};
2 February 2007