Composite formatting

The .NET composite formatting feature takes a list of objects and a composite format string as input. A composite format string consists of fixed text intermixed with indexed placeholders, called format items. These format items correspond to the objects in the list. The formatting operation yields a result string that consists of the original fixed text intermixed with the string representation of the objects in the list.

The following methods support the composite formatting feature:

• String.Format, which returns a formatted result string.
• StringBuilder.AppendFormat, which appends a formatted result string to a StringBuilder object.
• Some overloads of the Console.WriteLine method, which display a formatted result string to the console.
• Some overloads of the TextWriter.WriteLine method, which write the formatted result string to a stream or file. The classes derived from TextWriter, such as StreamWriter and HtmlTextWriter, also share this functionality.
• Debug.WriteLine(String, Object[]), which outputs a formatted message to trace listeners.
• The Trace.TraceError(String, Object[]), Trace.TraceInformation(String, Object[]), and Trace.TraceWarning(String, Object[]) methods, which output formatted messages to trace listeners.
• The TraceSource.TraceInformation(String, Object[]) method, which writes an informational method to trace listeners.

A composite format string and object list are used as arguments of methods that support the composite formatting feature. A composite format string consists of zero or more runs of fixed text intermixed with one or more format items. The fixed text is any string that you choose, and each format item corresponds to an object or boxed structure in the list. The string representation of each object replaces the corresponding format item.

Consider the following Format code fragment:

string.Format("Name = {0}, hours = {1:hh}", "Fred", DateTime.Now);

String.Format("Name = {0}, hours = {1:hh}", "Fred", DateTime.Now)

The fixed text is Name =  and , hours = . The format items are {0}, whose index of 0 corresponds to the object name, and {1:hh}, whose index of 1 corresponds to the object DateTime.Now.

Each format item takes the following form and consists of the following components:

{index[,alignment][:formatString]}

The matching braces ({ and }) are required.

The mandatory index component, which is also called a parameter specifier, is a number starting from 0 that identifies a corresponding item in the list of objects. That is, the format item whose parameter specifier is 0 formats the first object in the list. The format item whose parameter specifier is 1 formats the second object in the list, and so on. The following example includes four parameter specifiers, numbered zero through three, to represent prime numbers less than 10:

string primes = string.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                              2, 3, 5, 7);
Console.WriteLine(primes);

// The example displays the following output:
//      Four prime numbers: 2, 3, 5, 7

Dim primes As String = String.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                                      2, 3, 5, 7)
Console.WriteLine(primes)

'The example displays the following output
'     Four prime numbers 2, 3, 5, 7

Multiple format items can refer to the same element in the list of objects by specifying the same parameter specifier. For example, you can format the same numeric value in hexadecimal, scientific, and number format by specifying a composite format string such as "0x{0:X} {0:E} {0:N}", as the following example shows:

string multiple = string.Format("0x{0:X} {0:E} {0:N}",
                                Int64.MaxValue);
Console.WriteLine(multiple);

// The example displays the following output:
//      0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

Dim multiple As String = String.Format("0x{0:X} {0:E} {0:N}",
                                       Int64.MaxValue)
Console.WriteLine(multiple)

'The example displays the following output
'     0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

Each format item can refer to any object in the list. For example, if there are three objects, you can format the second, first, and third object by specifying a composite format string such as {1} {0} {2}. An object that isn't referenced by a format item is ignored. A FormatException is thrown at run time if a parameter specifier designates an item outside the bounds of the list of objects.

The optional alignment component is a signed integer indicating the preferred formatted field width. If the value of alignment is less than the length of the formatted string, alignment is ignored, and the length of the formatted string is used as the field width. The formatted data in the field is right-aligned if alignment is positive and left-aligned if alignment is negative. If padding is necessary, white space is used. The comma is required if alignment is specified.

The following example defines two arrays, one containing the names of employees and the other containing the hours they worked over two weeks. The composite format string left-aligns the names in a 20-character field and right-aligns their hours in a 5-character field. The "N1" standard format string formats the hours with one fractional digit.

string[] names = { "Adam", "Bridgette", "Carla", "Daniel",
                   "Ebenezer", "Francine", "George" };
decimal[] hours = { 40, 6.667m, 40.39m, 82,
                    40.333m, 80, 16.75m };

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours");

for (int counter = 0; counter < names.Length; counter++)
    Console.WriteLine("{0,-20} {1,5:N1}", names[counter], hours[counter]);

// The example displays the following output:
//      Name                 Hours
//      
//      Adam                  40.0
//      Bridgette              6.7
//      Carla                 40.4
//      Daniel                82.0
//      Ebenezer              40.3
//      Francine              80.0
//      George                16.8

Dim names As String() = {"Adam", "Bridgette", "Carla", "Daniel",
                         "Ebenezer", "Francine", "George"}

Dim hours As Decimal() = {40, 6.667D, 40.39D, 82,
                          40.333D, 80, 16.75D}

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours")

For counter = 0 To names.Length - 1
    Console.WriteLine("{0,-20} {1,5:N1}", names(counter), hours(counter))
Next

'The example displays the following output
'     Name                 Hours
'     
'     Adam                  40.0
'     Bridgette              6.7
'     Carla                 40.4
'     Daniel                82.0
'     Ebenezer              40.3
'     Francine              80.0
'     George                16.8

The optional formatString component is a format string that's appropriate for the type of object being formatted. You can specify:

• A standard or custom numeric format string if the corresponding object is a numeric value.
• A standard or custom date and time format string if the corresponding object is a DateTime object.
• An enumeration format string if the corresponding object is an enumeration value.

If formatString isn't specified, the general ("G") format specifier for a numeric, date and time, or enumeration type is used. The colon is required if formatString is specified.

The following table lists types or categories of types in the .NET class library that support a predefined set of format strings, and provides links to the articles that list the supported format strings. String formatting is an extensible mechanism that makes it possible to define new format strings for all existing types and to define a set of format strings supported by an application-defined type.

For more information, see the IFormattable and ICustomFormatter interface articles.

Opening and closing braces are interpreted as starting and ending a format item. To display a literal opening brace or closing brace, you must use an escape sequence. Specify two opening braces ({{) in the fixed text to display one opening brace ({), or two closing braces (}}) to display one closing brace (}).

Escaped braces with a format item are parsed differently between .NET and .NET Framework.

Braces can be escaped around a format item. For example, consider the format item {{{0:D}}}, which is intended to display an opening brace, a numeric value formatted as a decimal number, and a closing brace. The format item is interpreted in the following manner:

1. The first two opening braces ({{) are escaped and yield one opening brace.
2. The next three characters ({0:) are interpreted as the start of a format item.
3. The next character (D) is interpreted as the Decimal standard numeric format specifier.
4. The next brace (}) is interpreted as the end of the format item.
5. The final two closing braces are escaped and yield one closing brace.
6. The final result that's displayed is the literal string, {6324}.

int value = 6324;
string output = string.Format("{{{0:D}}}", value);

Console.WriteLine(output);
// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}", value)

Console.WriteLine(output)

'The example displays the following output
'      {6324}

Braces in a format item are interpreted sequentially in the order they're encountered. Interpreting nested braces isn't supported.

The way escaped braces are interpreted can lead to unexpected results. For example, consider the format item {{{0:D}}}, which is intended to display an opening brace, a numeric value formatted as a decimal number, and a closing brace. However, the format item is interpreted in the following manner:

1. The first two opening braces ({{) are escaped and yield one opening brace.
2. The next three characters ({0:) are interpreted as the start of a format item.
3. The next character (D) would be interpreted as the Decimal standard numeric format specifier, but the next two escaped braces (}}) yield a single brace. Because the resulting string (D}) isn't a standard numeric format specifier, the resulting string is interpreted as a custom format string that means display the literal string D}.
4. The last brace (}) is interpreted as the end of the format item.
5. The final result that's displayed is the literal string, {D}. The numeric value that was to be formatted isn't displayed.

int value = 6324;
string output = string.Format("{{{0:D}}}",
                              value);
Console.WriteLine(output);

// The example displays the following output:
//       {D}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}",
                                     value)
Console.WriteLine(output)

'The example displays the following output:
'      {D}

One way to write your code to avoid misinterpreting escaped braces and format items is to format the braces and format items separately. That is, in the first format operation, display a literal opening brace. In the next operation, display the result of the format item, and in the final operation, display a literal closing brace. The following example illustrates this approach:

int value = 6324;
string output = string.Format("{0}{1:D}{2}",
                             "{", value, "}");
Console.WriteLine(output);

// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{0}{1:D}{2}",
                                     "{", value, "}")
Console.WriteLine(output)

'The example displays the following output:
'      {6324}

If the call to the composite formatting method includes an IFormatProvider argument whose value isn't null, the runtime calls its IFormatProvider.GetFormat method to request an ICustomFormatter implementation. If the method can return an ICustomFormatter implementation, it's cached during the call of the composite formatting method.

Each value in the parameter list that corresponds to a format item is converted to a string as follows:

1. If the value to be formatted is null, an empty string String.Empty is returned.

2. If an ICustomFormatter implementation is available, the runtime calls its Format method. The runtime passes the format item's formatString value (or null if it's not present) to the method. The runtime also passes the IFormatProvider implementation to the method. If the call to the ICustomFormatter.Format method returns null, execution proceeds to the next step. Otherwise, the result of the ICustomFormatter.Format call is returned.

3. If the value implements the IFormattable interface, the interface's ToString(String, IFormatProvider) method is called. If one is present in the format item, the formatString value is passed to the method. Otherwise, null is passed. The IFormatProvider argument is determined as follows:

   • For a numeric value, if a composite formatting method with a non-null IFormatProvider argument is called, the runtime requests a NumberFormatInfo object from its IFormatProvider.GetFormat method. If it's unable to supply one, if the value of the argument is null, or if the composite formatting method doesn't have an IFormatProvider parameter, the NumberFormatInfo object for the current culture is used.

   • For a date and time value, if a composite formatting method with a non-null IFormatProvider argument is called, the runtime requests a DateTimeFormatInfo object from its IFormatProvider.GetFormat method. In the following situations, the DateTimeFormatInfo object for the current culture is used instead:

     • The IFormatProvider.GetFormat method is unable to supply a DateTimeFormatInfo object.
     • The value of the argument is null.
     • The composite formatting method doesn't have an IFormatProvider parameter.

   • For objects of other types, if a composite formatting method is called with an IFormatProvider argument, its value is passed directly to the IFormattable.ToString implementation. Otherwise, null is passed to the IFormattable.ToString implementation.

4. The type's parameterless ToString method, which either overrides Object.ToString() or inherits the behavior of its base class, is called. In this case, the format string specified by the formatString component in the format item, if it's present, is ignored.

Alignment is applied after the preceding steps have been performed.

The following example shows one string created using composite formatting and another created using an object's ToString method. Both types of formatting produce equivalent results.

string formatString1 = string.Format("{0:dddd MMMM}", DateTime.Now);
string formatString2 = DateTime.Now.ToString("dddd MMMM");

Dim formatString1 As String = String.Format("{0:dddd MMMM}", DateTime.Now)
Dim formatString2 As String = DateTime.Now.ToString("dddd MMMM")

Assuming that the current day is a Thursday in May, the value of both strings in the preceding example is Thursday May in the U.S. English culture.

Console.WriteLine exposes the same functionality as String.Format. The only difference between the two methods is that String.Format returns its result as a string, while Console.WriteLine writes the result to the output stream associated with the Console object. The following example uses the Console.WriteLine method to format the value of myNumber to a currency value:

int myNumber = 100;
Console.WriteLine($"{myNumber:C}");

// The example displays the following output
// if en-US is the current culture:
//        $100.00

Dim myNumber As Integer = 100
Console.WriteLine("{0:C}", myNumber)

'The example displays the following output
'if en-US Is the current culture:
'       $100.00

The following example demonstrates formatting multiple objects, including formatting one object in two different ways:

string myName = "Fred";
Console.WriteLine(string.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
                                myName, DateTime.Now));

// Depending on the current time, the example displays output like the following:
//        Name = Fred, hours = 11, minutes = 30

Dim myName As String = "Fred"
Console.WriteLine(String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
                                myName, DateTime.Now))
'Depending on the current time, the example displays output Like the following:
'       Name = Fred, hours = 11, minutes = 30

The following example demonstrates the use of alignment in formatting. The arguments that are formatted are placed between vertical bar characters (|) to highlight the resulting alignment.

string firstName = "Fred";
string lastName = "Opals";
int myNumber = 100;

string formatFirstName = string.Format("First Name = |{0,10}|", firstName);
string formatLastName = string.Format("Last Name =  |{0,10}|", lastName);
string formatPrice = string.Format("Price =      |{0,10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);
Console.WriteLine();

formatFirstName = string.Format("First Name = |{0,-10}|", firstName);
formatLastName = string.Format("Last Name =  |{0,-10}|", lastName);
formatPrice = string.Format("Price =      |{0,-10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);

// The example displays the following output on a system whose current
// culture is en-US:
//     First Name = |      Fred|
//     Last Name =  |     Opals|
//     Price =      |   $100.00|
//
//     First Name = |Fred      |
//     Last Name =  |Opals     |
//     Price =      |$100.00   |

Dim firstName As String = "Fred"
Dim lastName As String = "Opals"
Dim myNumber As Integer = 100

Dim formatFirstName As String = String.Format("First Name = |{0,10}|", firstName)
Dim formatLastName As String = String.Format("Last Name =  |{0,10}|", lastName)
Dim formatPrice As String = String.Format("Price =      |{0,10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)
Console.WriteLine()

formatFirstName = String.Format("First Name = |{0,-10}|", firstName)
formatLastName = String.Format("Last Name =  |{0,-10}|", lastName)
formatPrice = String.Format("Price =      |{0,-10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)

'The example displays the following output on a system whose current
'culture Is en-US:
'    First Name = |      Fred|
'    Last Name =  |     Opals|
'    Price =      |   $100.00|
'
'    First Name = |Fred      |
'    Last Name =  |Opals     |
'    Price =      |$100.00   |

• WriteLine
• String.Format
• String interpolation (C#)
• String interpolation (Visual Basic)
• Formatting Types
• Standard Numeric Format Strings
• Custom Numeric Format Strings
• Standard Date and Time Format Strings
• Custom Date and Time Format Strings
• Standard TimeSpan Format Strings
• Custom TimeSpan Format Strings
• Enumeration Format Strings