Formatting Numbers

So far, you’ve seen how to use the basic data types of the CLR. All data types expose a ToString method, which returns the variable’s value (a number or date) as a string, so that it can be used with other strings in your code. The ToString method formats numbers and dates in many ways and it’s probably one of the most commonly needed methods. You can call the ToString method without any arguments, as we have done so far, to convert any value to a string. The ToString method, however, accepts an optional argument, which determines how the value will be formatted as a string. For example, you can format a number as currency by prefixing it with the appropriate sign (for example, the dollar symbol) and displaying it to two decimal digits, and you can display dates in many formats. Some reports require that negative amounts are enclosed in parentheses. The ToString method allows you to display numbers and dates in any way you wish.

Notice that ToString is a method, not a property. It returns a value that you can assign to a string variable or pass as arguments to a function such as MsgBox(), but the original value is not affected. The ToString method can also format a value if called with an optional argument:

ToString(formatString)Code language: VB.NET (vbnet)

The formatString argument is a format specifier (a string that specifies the exact format to be applied to the variable). This argument can be a specific character that corresponds to a predetermined format (a standard format string, as it’s called) or a string of characters that have special meaning in formatting numeric values (a picture format string). Use standard format strings for the most common formatting options, and use picture strings to specify unusual formatting requirements. To format the value 9959.95 as a dollar amount, you can use the following standard currency:

Dim Amnt As Single = 9959.95
Dim strAmnt As String
strAmnt = Amnt.ToString("C")Code language: VB.NET (vbnet)

Or use the following picture numeric format string:

strAmnt = Amnt.ToString("$#,###.00")Code language: VB.NET (vbnet)

Both statements will format the value as $9,959.95. The “C” argument in the first example means currency and formats the numeric value as currency. If you’re using a non-U.S. version of Windows, the currency symbol will change accordingly. Use the Regional And Language Options tool in the Control Panel to temporarily change the current culture to a European one, and the amount will be formatted with the Euro sign.

The picture format string is made up of literals and characters that have special meaning in formatting. The dollar sign has no special meaning and will appear as is. The # symbol is a digit placeholder; all # symbols will be replaced by numeric digits, starting from the right. If the number has fewer digits than specified in the string, the extra symbols to the left will be ignored.

The comma tells the Format function to insert a comma between thousands. The period is the decimal point, which is followed by two more digit placeholders. Unlike the # sign, the 0 is a special placeholder: If there are not enough digits in the number for all the zeros you’ve specified, a 0 will appear in the place of the missing digits. If the original value had been 9959.9, for example, the last statement would have formatted it as $9,959.90. If you used the # placeholder instead, the string returned by the Format method would have a single decimal digit.

Standard Numeric Format Strings

The ToString method of the numeric data types recognizes the standard numeric format strings shown in Table 2.6.

Table 2.6: Standard Numeric Format Strings

The format character can be followed by an integer. If present, the integer value specifies the number of decimal places that are displayed. The default accuracy is two decimal digits.

The C format string causes the ToString method to return a string representing the number as a currency value. An integer following the C determines the number of decimal digits that are displayed. If no number is provided, two digits are shown after the decimal separator.Assuming that the variable value has been declared as Decimal and its value is 5596, then the expression value.ToString(“C”) will return the string $5,596.00. If the value of the variable were 5596.4499, then the expression value.ToString(“C3”) would return the string $5,596.450.

Notice that not all format strings apply to all data types. For example, only integer values can be converted to hexadecimal format, and the D format string works with integer values only.

There are format strings and digits for dates too, and they’re discussed in Chapter 13, where I will present the Date data type and related topics in detail.

Picture Numeric Format Strings

If the format characters listed in Table 2.6 are not adequate for the control you need over the appearance of numeric values, you can provide your own picture format strings. Picture format strings contain special characters that allow you to format your values exactly as you like. Table 2.7 lists the picture formatting characters.

Table 2.7: Picture Numeric Format Strings

The following statements will print the highlighted values:

Dim Amount As Decimal = 42492.45
Debug.WriteLine(Amount.ToString("$#,###.00"))
$42,492.45
Amount = 0.2678
Debug.WriteLine(Amount.ToString("0.000"))
0.268
Amount = -24.95
Debug.WriteLine(Amount.ToString("$#,###.00;($#,###.00)"))
($24.95)Code language: VB.NET (vbnet)