Converting Numeric Dollar Values to Text

Introduction:

The article describes an easy approach to converting a numeric dollar value into its text equivalent; the primary purpose for such a mechanism would be to express the amount displayed on a check as a string within the 'Amount' section typical to most checks.  It may have some other use as well but that was the goal I had in mind when I wrote a simple code module to perform the conversion.  The code provided in the example will convert numbers between 1 cent and $9,999,999.99 but it could be continued beyond this point with little additional effort.

To serve the purpose of a test harness, the sample application converts the numeric values into text and displays both in the form of a personal check.  This application is not a full blown check writing application, it is just a demo project without any sort of back end record keeping system whatsoever.

Figure 1:  Demo Application Displaying converted numeric values as text

Getting Started:

Unzip the attached file; in it you will find solution containing a single windows forms project.  The project was written in Visual Basic 2005 and it contains only two significant files, a code module entitled, "DecimalToText" and a form class entitled, "frmCheck".  The module is used to perform the string conversion functions while the form class is used as a test harness that serves only to evaluate the code module.

Figure 2.  Check Writer Solution in the Solution Explorer

There are certainly many other options available for constructing code to perform such a translation, however, in a effort to keep things simple, I opted to convert the numeric value into a character array and to use a series of select case statements to determine the length of the array and to set portions of the text according to the length and content of the amount entered as a numeric value.  In this instance, I found that the select case statement approach used did offer more complete control over writing out the text given the current numeric value's content in terms of applying the correct text at the correct time to render out the correct amount string at the end of the processing task.  Still and all, the approach shown is not a terribly efficient way of handling the translation but it does appear to work well enough across the involved range of potential numeric values.

The Code:  DecimalToText Module

As was mentioned, this class was declared as a module to make its functions accessible throughout the application without the requiring the creation of an instance of the class.  This class contains only one public function, "ConvertDecimalToText"; the method accepts a decimal value as its only argument.  All other functions or subroutines in the class are declared private and are only called by this public function.

The class itself does not include any import statements nor does it inherit from any other class or implement any interfaces.  The ConvertDecimalToText function accepts the decimal value to translate into text and in order to determine the size number of places in the decimal value, the value is converted to a string and then into a character array.  The character array is stripped of the fractional portion of the number and its decimal place, the length of the remaining array is evaluated within a select statement in order to determine the type of number to process (ones, tens, hundreds, thousands, etc.).  Once the size of the number has been determined, the value is processed into text by values acquired from the character array passed into a collection of other functions used to retrieve the appropriate text for that value.  In some instances, to properly write out the text, either one or two values from the character array are joined together and processed (so that the function can return, for example, ninety-nine instead of ninety and nine).

The code used in this function is as follows:

As you can see from looking at the code, the select case statement is just used to process  the text describing each separate section of the translated number.  The more places the character array has, the more parts there are to process.  I stopped processing the numbers at nine million; if you need to write checks larger than $9,999,999.99 then just continue the processing with case 8, case 9, and so forth.

Each of the remaining functions in this module are used to process parts of the decimal value to be converted; since each portion of the number will return different text representations, there are separate functions for each portion of the number, e.g., dollars, tens of dollars, hundreds of dollars, thousands of dollars, tens of thousands of dollars, etc.

I won't place all of the subordinate functions into this document but, as an example, I will print up the function that calculates the portion that returns the single dollar value for the sting.  It is as follows:

In examining this piece of code you will note that the function accepts a character value as an argument; this character value is stripped from the decimal value once it has been converted to a character array and then the value (a number between 0 and 9) is processed in this select statement.  In use, if the user keys in, for example, 1.05, the conversion function will pass "1" to this function which will in turn return "One"; this value will then be added to the value returned from function used to obtain the fraction values and then that assembled string is passed back to the form and displayed as "One and 05/100's Dollars" to the user.

The rest of the functions in this module operate in a very similar manner; review the code contained in this module to see how each portion of the amount string is built.

The Code:  Check Form (frmCheck.vb) Class

This portion of the project is used as a test harness to evaluate different decimal values.  I tested processing numbers between 0 and 9,999,999.99 using this same method.  The code is simple enough, the user may key a value up to the maximum amount (9,999,999.99) into a text box and click on an update button at the bottom of the form.  When the update button is clicked, the user entered text is processed and passed to the conversion function.  The string returned from the conversion function is then displayed in the 'Amount' area of the fake check.

The code in the form class is as follows:

There is a little more code in this class; it is merely used to limit the user to entering numeric values into the text box and to display a date on the fake check.  I won't reprint that bit here but you can examine it in the sample project.

Summary.

There are many different ways in which the decimal values could be converted to text; this is only one possibility and it is something of a brute force approach to tackling the problem.  However, this approach is easy to extend or to modify if you were to wish to modify the output.  For example, I have noted that some machine drawn checks are formatted in this manner:

One thousand Eleven Hundred Nineteen Dollars and Fifty Eight Cents

Where as this example would print this same value in this format:

One Thousand Eleven Hundred Nineteen and 58/100's Dollars

I consider the later to be the more typical approach used and for that reason I wrote the conversion utility function to output in a manner consistent with this format.  Again, this is not a terribly efficient process and you may wish to generate string arrays containing each of the text values and devise a method for looping through the decimal value contents and assigning bits of text to each of its constituent parts, however, at the end of the day you still will end up writing out the text in some form or format somewhere.