A program uses format specifiers to determine how objects are represented as strings. C# provides two kinds of specifiers: standard format specifiers and custom format specifiers. Standard format specifiers are locale-aware, so the result depends on the computer’s regional settings. If a program uses standard format specifiers and you run the program in a new locale, it automatically produces the formats appropriate for that locale. For that reason, you should always use the standard specifiers whenever possible.

The following sections describe the standard and custom format specifiers.

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

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 of the parameter (numbered from 0) that should be inserted in this placeholder’s position.

The optional alignment value tells the minimum number of characters 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.

string name = "Crazy Bob";
decimal sales = -12345.67m;
MessageBox.Show(String.Format("{0} {1:earned;lost} {1:c} this year", name, sales));

The first placeholder refers to parameter number 0. The first parameter after the format specifier is the name variable, which has 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 if the value is negative. The third placeholder refers to parameter number 1 again, this time displaying its value formatted as currency.

The following shows the result.

Crazy Bob lost ($12,345.67) this year

Enumerated Type Formatting

Enumerated values are formatted as string representations rather than as the integer values that represent them. For example, consider the following code.

public enum Dessert
{
    Cake = 1,
    Pie = 2,
    Cookie = 3,
    IceCream = 4,
}
...
Dessert selection = Dessert.Cake;
MessageBox.Show(selection.ToString());

This code displays the string Cake.

For variables of an enumerated type such as selection, 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 enumeration’s definition, the result is the variable’s numeric value. For example, the previous code does not define a value for the integer 7 so, if you set selection to 7, selection.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 enumeration’s values, as shown in the following code.

[Flags()]
public enum Dessert
{
    Cake = 1,
    Pie = 2,
    Cookie = 3,
    IceCream = 4,
}
...
Dessert selection = Dessert.IceCream | Dessert.Pie;
Console.WriteLine(selection.ToString("G"));

In this case, the G format specifier returns a string that contains all the flag values separated by commas. In this example, the result is Pie, 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. For example, if you omit the Flags attribute from the previous code, selection.ToString("G") returns 6 (because Pie + IceCream = 2 + 4 = 6), but selection.ToString("F") returns Pie, 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.

The following table summarizes the enumeration format specifiers.