View source for Formatting Strings in C Sharp

In addition to the wide selection of string manipulation functions outlined in [[Working with Strings in C Sharp|Working with Strings in C#]], the string class also provides the ''String.Format()'' method.

The primary purpose of the C# ''String.Format()'' method is to provide a mechanism for inserting string, numerical or boolean values into a string.

== The Syntax of the String.Format() Method ==

The general syntax of the String.Format() method is as follows:

String.Format(''format string", ''arg1'', ''arg2'', .... );

The ''format string'' is the string into which the values will be placed. Within this string are ''place holders'' which indicate the location of each value within the string. Place holders take the form of braces surrounding a number indicating argument to be substituted for the place holder. Following on from the ''format string'' is a comma separated list of arguments. There must be an argument for each of the place holders.

== A Simple C# String Format Example ==

The following code fragment demonstrates a very simple use of the String.Format() method:

<pre>
		string newString;

		newString = String.Format("There are {0} cats in my {1} and no {2}", 2, "house", "dogs");

		System.Console.WriteLine (newString);
</pre>

When run, the above code will result in the following output:

<pre>
There are 2 cats in my house and no dogs
</pre>

Let's quickly review the String.Format() method call. The ''format string'' contains 3 place holder indicated by {0}, {1} and {2}. Following the format string are the arguments to be used in each place holder. For example, {0} is replaced by the first argument (the number 2), the {1} by the second argument (the string "house) and so on.

== Using Format Controls ==

So far we have only substituted arguments for place holders, but we have not made any changes to the format of the arguments before they are displayed. This essentially instructs the Format() method to use the default formatting for each argument type when displaying the string. Perhaps the most powerful aspect of the Format() method is the ability to use ''format controls'' within the place holders to control the format of the output. 

Format controls appear inside the braces ({}) of the place holders. The format of a place holder with a format control is as follows:

{''n'':''control''}

Where ''n'' is the place holder number and ''control'' is the special format control sequence to be applied to the argument.

== As Simple Format Control Example ==

The following example uses the ''X'' format control to display a number in Hexadecimal format:

<pre>

	newString = String.Format("The number {0} in Hexadecimal is {0:X}", 432);

	System.Console.WriteLine (newString);
</pre>

The above example displays argument 0 (the number 432) in two formats. The first is the default decimal format and the second uses the ''X'' format control to display the argument as a hexadecimal number.

The String.Format() method provides a wide range of format controls which are outlined in the following section.

== The C# String.Format() Format Controls ==

The following table lists format controls supported by the C# String.Format() method together with examples of each control:

<table border="1" cellspacing="0">
<tr style="background:#efefef;">
<th>Control<th>Type<th>Description<th>Example</th>
<tr>
<td>C</td><td>Currency</td><td>Displays number prefixed with the currency simple appropriate to the current locale</td><td>{0:C} of 432.00 outputs $432.00</td>
<tr>
<td>D</td><td>Decimal</td><td>Displays number in decimal form with optional padding</td><td>{0:D4} of 432 outputs 00432</td>
<tr>
<td>E</td><td>Exponential</td><td>Displays number in scientific form with optional value for fractional part</td><td>{0:E5} of 432.32 outputs 4.32320E+002</td>
<tr>
<td>E</td><td>Fixed</td><td>Displays the number including the specified number of decimal digits</td><td>{0:F3} of 432.324343 outputs 432.324</td>
<tr>
<td>N</td><td>Number</td><td>Converts a number to a human friendly format by inserting commas and rounding to the nearest 100<sup>th</sup></td><td>{0:N} of 123432.324343 outputs 123,432.32</td>
<tr>
<td>X</td><td>Hexadecimal</td><td>Converts a number to hexadecimal</td><td>{0:X} of 432 outputs 1B0</td>
<tr>
<td>0:0...</td><td>Zero Padding</td><td>Adds zeros to pad argument</td><td>{0:0000.00} of 43.1 outputs 0043.10</td>
<tr>
<td>0:0#...</td><td>Space Padding</td><td>Adds spaces to pad argument</td><td>{0:####.##} of 43.1 outputs   43.1 </td>
<tr>
<td>%</td><td>Percentage</td><td>Multiplies the argument by 100 and appends a percentage sign</td><td>{0:00.00%} of .432 outputs 43.20%</td>
</table>