Appendix Q

Other Format Specifiers

A program uses format specifiers to determine how objects are represented as strings. For example, by using different format specifiers, you can make an integer’s ToString method return a value as –12345, –12,345, (12,345), or 012,345–.

Visual Basic provides standard format specifiers in addition to custom specifiers. The standard specifiers make it easy to display values in often-used formats (such as currency or scientific notation). Custom specifiers provide more control over how results are composed.

STANDARD NUMERIC FORMAT SPECIFIERS

Standard numeric format specifiers enable you to easily display commonly used numeric formats. The following table lists the standard numeric specifiers.

CUSTOM NUMERIC FORMAT SPECIFIERS

Custom numeric format specifiers describe how a number should be formatted. The following table lists characters that you can use to build custom numeric formats.

NUMERIC FORMATTING SECTIONS

A numeric format specifier may contain one, two, or three sections separated by semicolons. If the specifier contains one section, the specifier is used for all numeric values.

If the specifier contains two sections, the first is used to format values that are positive or zero, and the second is used to format negative values.

If the specifier contains three sections, the first is used to format positive values, the second is used to format negative values, and the third is used to format values that are zero.

The following text shows output from the Immediate window for three values using the format specifier #,#.00;<#,#.00>;ZERO:

?(1234.5678).ToString("#,#.00; <#,#.00>;ZERO")
1,234.57
?(-1234.5678).ToString("#,#.00; <#,#.00>;ZERO")
<1,234.57>
?(0).ToString("#,#.00; <#,#.00>;ZERO")
ZERO

COMPOSITE FORMATTING

The String.Format, Console.WriteLine, and TextWriter.WriteLine methods provide a different method for formatting strings. These routines can take a composite formatting string parameter that contains literal characters plus placeholders for values. Other parameters to the methods give the values.

The value placeholders have the following format:

{index[,alignment][:format_specifier]}

The index value gives the index numbered from 0 of the parameter that should be inserted in this placeholder’s position.

The optional alignment value tells the minimum number of spaces the item should use and the result is padded with spaces, if necessary. If this value is negative, the result is left-justified. If the value is positive, the result is right-justified.

The format_specifier indicates how the item should be formatted.

For example, consider the following code:

Dim emp As String = "Crazy Bob":
Dim sales As Single = -12345.67
MessageBox.Show(String.Format("{0} {1:earned;lost} {1:c} this year", emp, sales))

The first placeholder refers to parameter number 0, which has the value “Crazy Bob.” The second placeholder refers to parameter number 1 and includes a two-part format specifier that displays “earned” if the value is positive or zero, and “lost” of the value is negative. The third placeholder refers to parameter number 1 again, this time formatted as currency.

The following code shows the result:

Crazy Bob lost ($12,345.67) this year

ENUMERATED TYPE FORMATTING

Visual Basic provides special formatting capabilities that can display the values of enumerated variables. For example, consider the following code:

Private Enum Dessert
    Cake = 1
    Pie = 2
    Cookie = 3
    IceCream = 4
End Enum
...
Dim dessert_choice As Dessert = Dessert.Cake
MessageBox.Show(dessert_choice.ToString)

This code displays the string “Cake.”

For variables of an enumerated type such as dessert_choice, the ToString method can take a specifier that determines how the value is formatted.

The specifier G or g formats the value as a string if possible. If the value is not a valid entry in the Enum’s definition, the result is the variable’s numeric value. For example, the previous code does not define a Dessert enumeration for the value 7 so, if you set dessert_choice to 7, then dessert_choice.ToString(“G”) returns the value 7.

If you define an enumerated type with the Flags attribute, variables of that type can be a combination of the Enum’s values, as shown in the following code:

<Flags()>
Private Enum Dessert
    Cake = 1
    Pie = 2
    Cookie = 4
    IceCream = 8
End Enum
...
Dim dessert_choice As Dessert = Dessert.IceCream Or Dessert.Cake
MessageBox.Show(dessert_choice.ToString("G"))

In this case, the G format specifier returns a string that contains all of the flag values separated by commas. In this example, the result is “Cake, IceCream.” Note that the values are returned in the order in which they are defined by the enumeration, not the order in which they are assigned to the variable.

If you do not use the Flags attribute when defining an enumerated type, the G format specifier always returns the variable’s numeric value if it is a combination of values rather than a single value from the list. In contrast the F specifier returns a list of comma-separated values if it makes sense. If you omit the Flags attribute from the previous code, dessert_choice.ToString(“G”) returns 9, but dessert_choice.ToString(“F”) returns “Cake, IceCream.”

The D or d specifier always formats the variable as a number.

The specifier X or x formats the value as a hexadecimal number.