Getting Started   ASP.NET Base Types   Formatting Types

---

In addition to the type of formatting used with base types, format specifiers can be used to format text written to the console with Console.Writeline, format text written to a text file with TextWriter.Writeline, or format multiple data types into a string with String.Format.

Non-base types accept string format specifiers in the following form, where the characters inside the curly brackets specify the formatting to apply to the variable:

"{0:G}"

The 0 character is the parameter specifier and denotes the argument on which to apply formatting. In this case, the argument used for formatting is the first argument that follows the format string. For information on formatting multiple types, or formatting the same type multiple times, see Formatting Multiple Objects, later in this topic.

The parameter specifier is separated from the format specifier ( represented by G ) by a colon ( : ) within the curly bracket set. If the type to be formatted implements the IFormattable interface, then the ToString method required by this interface is called passing the format specifier. If no format specifier is supplied, null ( Nothing in Visual Basic ) is passed, causing the general format to be used. If the type to be formatted does not implement the IFormattable interface, the ToString method inherited from the Object class is called. If the value to be formatted has a null value ( Nothing in Visual Basic ), an empty string ( "" ) is returned. After the preceding logic has been performed, alignment is applied. For information on applying alignment, see the Alignment section below.

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

[ VB ]
Dim FormatString1 As String = String.Format ( "{0:dddd MMMM}", DateTime.Now ) 
Dim FormatString2 As String = DateTime.Now.ToString ( "dddd MMMM" ) 
[ C# ]
string FormatString1 = String.Format ( "{0:dddd MMMM}", DateTime.Now );
string FormatString2 = 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 stream associated with the Console object. The following code example uses the Console.WriteLine method to format the value of myInt to a currency value.

[ VB ]
Dim myInt As Integer = 100
Console.WriteLine ( "{0:C}", myInt ) 
[ C# ]
int myInt = 100;
Console.WriteLine ( "{0:C}", myInt );

This code displays $100.00 to the console on computers that have U.S. English as the current culture.

For composite formatting, the parameter specifier refers to the nth parameter provided after the format string, where n is a zero-based integer. You can use the parameter specifier to create a new string object from multiple objects if you number the objects, placing each number in curly brackets similar to the following: {0}, {1}, {2}, and so on. The {0} parameter specifier refers to the first object passed after the format string, the {1} parameter refers to the second, and so on. You can display the same argument multiple times if you pass the same parameter specifier multiple times. For example, if you pass the following format string, the first argument will be displayed twice: "{0} {0} {1}". The following code example formats a string and a DateTime object.

[ VB ]
Dim myName As String = "Fred"
String.Format ( "Name = {0}, hours = {1:hh}, minutes = {1:mm}",
      myName, DateTime.Now ) 
[ C# ]
string myName = "Fred";
String.Format ( "Name = {0}, hours = {1:hh}, minutes = {1:mm}",
      myName, DateTime.Now );

The output from the above string is "Name = Fred, hours = 07, minutes = 23", where the current time reflects these numbers.

To specify the alignment for a formatted string in the composite formatting scheme, you can place a comma after the parameter specifier and before the colon used to separate the parameter specifier and the format specifier. A number indicating the field width should follow the comma. A negative number indicates that this parameter should be right-aligned within that field, and a positive number indicates it should be left-aligned. For right-aligned fields, the alignment is calculated so that the last field in the new alignment is the last character in the string being aligned. For left-aligned fields, the alignment is calculated so that the first field in the new alignment is the first character of the string being aligned. Alignment is always achieved using white spaces. The text is never shortened to meet the specified width; instead, the width is expanded to allow the full text to be displayed. Therefore, in order for alignment to be meaningful, the number you pass should be greater than the length of the original string you are aligning.

The following code examples demonstrate the use of alignment in formatting. The arguments that are formatted are placed between ’|’ characters to highlight the resulting alignment.

[ VB ]
Dim myFName As String = "Fred"
Dim myLName As String = "Opals"
Dim myInt As Integer = 100
Dim FormatFName As String = String.Format ( "First Name = |{0,10}|", myFName ) 
Dim FormatLName As String = String.Format ( "Last Name = |{0,10}|", myLName ) 
Dim FormatPrice As String = String.Format ( "Price = |{0,10:C }|", myInt ) 
Console.WriteLine ( FormatFName ) 
Console.WriteLine ( FormatLName ) 
Console.WriteLine ( FormatPrice ) 

FormatFName = String.Format ( "First Name = |{0,-10}|", myFName ) 
FormatLName = String.Format ( "Last Name = |{0,-10}|", myLName ) 
FormatPrice = String.Format ( "Price = |{0,-10:C }|", myInt ) 
Console.WriteLine ( FormatFName ) 
Console.WriteLine ( FormatLName ) 
Console.WriteLine ( FormatPrice ) 
[ C# ]
string myFName = "Fred";
string myLName = "Opals";
int myInt = 100;
string FormatFName = String.Format ( "First Name = {0,10}", myFName );
string FormatLName = String.Format ( "Last Name = {0,10}", myLName );
string FormatPrice = String.Format ( "Price = {0,10:C}", myInt ); 
Console.WriteLine ( FormatFName );
Console.WriteLine ( FormatLName );
Console.WriteLine ( FormatPrice );

FormatFName = String.Format ( "First Name = |{0,-10}|", myFName );
FormatLName = String.Format ( "Last Name = |{0,-10}|", myLName );
FormatPrice = String.Format ( "Price = |{0,-10:C}|", myInt );
Console.WriteLine ( FormatFName );
Console.WriteLine ( FormatLName );
Console.WriteLine ( FormatPrice );

The preceding code displays the following to the console in the U.S. English culture. Different cultures display different currency symbols and separators.

First Name = |          Fred|
Last Name = |         Opals|
Price = |           $100.00|
First Name = |Fred      |
Last Name = |Opals     |
Price = |$100.00   |