Recipe 5.20. Formatting Numbers into Strings

Problem

You want to format a number into a string suitable for displaying or printing, something that provides formatting control beyond the defaults.

Solution

Sample code folder: Chapter 05\ FormatNumbers

Apply the String object's Format() method, and use its custom formatting codes to get the output you desire.

Discussion

There are several ways and places in Visual Basic 2005 to apply formatting to numerical data. One of the best (and possibly the easiest to remember) is the Format() method, available as a shared method of the String object. A few simple examples will show you how to use this method:

 Dim intValue As Integer = 1234567 Dim floatValue As Double = Math.PI Dim result As New System.Text.StringBuilder result.AppendLine(String.Format("{0} … {1}", _    intValue, floatValue)) result.AppendLine(String.Format("{0:N} … {1:E}", _    intValue, floatValue)) result.AppendLine(intValue.ToString("N5") & " … " & _    floatValue.ToString("G5")) MsgBox(result.ToString())

This example formats an Integer and a Double in several different ways. Other numerical values, such as Long, Short, Single, Decimal, and so on, can be formatted in the same ways. Figure 5-22 shows the result of applying the above formatting.

Figure 5-22. A sampling of the many ways numbers can be formatted into strings

The Format() method's first argument is a formatting string that indicates how to use the remaining arguments. It can include zero or more zero-based position specifiers in curly braces. For instance, the text {1} says to insert the second data argument at that position. Consider this line of code:

 result = String.Format( _    "There are about {0} days in {1} years.", _    365.25 * 3, 3, 17)

The first indexed specifier, {0}, inserts the first data argument, the calculated result of 365.25 * 3. The second indexed formatting specifier, {1}, inserts the integer value 3 at that spot in the resulting string. The argument list also includes a third data element, 17, but because {2} does not appear in the format string, that argument is ignored.

You can use as many indexed formatting specifiers as you want in a single string, but you should always provide a matching indexed argument in the method call following the string, and the first argument is always zero-based. You can use the same argument more than once, you can use them in any order, and you can even skip some arguments. The important thing to remember is to match carefully the index number in the brackets with the argument's position, starting with zero.

When the index appears in the braces by itself, a default format is used. However, there are many formatting options available to customize the formatting. In the previous sample code, the {0:N} formatted the number to contain commas between every third digit, and {1:E} formatted the number using scientific notation. The Visual Studio online help documentation for the Format() method lists the many formatting options in detail.

You might have noticed that the last formatting line in the example is quite different from the previous ones. If you want to format a number into a string format without directly inserting it into a bigger string, you can use the many formatting options of the ToString() method, a method available to every .NET object (although specially overloaded for the numeric data types). In our example, the first number was formatted using "N5", which inserts commas and formats the digits to five places after the decimal point. The second number was formatted using "G5", causing "general" formatting of the number to five significant digits.

There are other formatting options for creating hexadecimal strings, formatting dates and times, formatting culture-specific data such as currency values, and so on. Several of these formatting options are used throughout this book. See the Visual Studio online documentation for specific predefined and custom format strings.

Problem

Solution

Discussion

Figure 5-22. A sampling of the many ways numbers can be formatted into strings

See Also