.NET 1.1+

C# String Generation with String.Format

The twentieth part of the C# Fundamentals tutorial adds to the previous examination of conversion between numeric and string data. This article describes the Format method of the String class that allows generation of strings containing text and numbers.

String.Format Method

The Format function is a static method of the String class. As mentioned earlier in this tutorial, a static method is one that can be called against the String class itself, rather than a method that requires a string object to be created first. The Format method allows the generation of strings that contain both textual information and inserted numeric data. This is ideal for outputting data for the user to read.

The Format method requires several parameters to operate correctly. The first parameter is always a template string. The template contains the text that is desired in the final string and one or more placeholders that are to be replaced with other values. The remainder of the parameters are the variables or literals that are to be formatted and inserted in place of the placeholders.

NB: The variables or literals can be of any data type including numeric data, strings and objects. For this article, we will consider only numeric data.

Templates and Placeholders

As described above, the template string must include placeholders to determine where other values are to be inserted. Each placeholder consists of a number between brace characters or curly brackets {}. The number in the braces is an index number that refers to one of the other parameters passed to the Format method. The index of the first non-template parameter is zero. A simple example can illustrate this.

string output;
int selection = 5;

// Generate the output string
output = string.Format("You selected item {0} from the list.", selection);

Console.WriteLine(output);     // Outputs "You selected item 5 from the list."

In the example above, the template string includes a single placeholder. The number between the braces is a zero, indicating that the first parameter after the template should be used as a replacement for the placeholder. In this case the value of the selection variable. However, the Format method is not limited to including only one parameter after the template. The following example shows two placeholders.

string output;
int selection = 5;
int count = 10;

// Generate the output string
output = string.Format("You selected item {0} from {1}.", selection, count);

Console.WriteLine(output);     // Outputs "You selected item 5 from 10."

Numeric Formatting

When inserting numbers into strings using the String.Format method, the numbers can be formatted. The formatting is achieved by adding format specifiers within the placeholders. The available format specifiers are the same as those for the ToString method of numeric data types. A table of all of the format specifiers is included in part 19 of the C# Fundamentals tutorial.

To include a format specifier, a colon (:) is inserted after the placeholder index number. The format specifier is then added before the closing brace. The following example shows the same parameter being used by two placeholders. One uses formatting, the other does not.

string output;
int value = 100;

// Convert a number to hexadecimal
output = string.Format("The decimal value {0} = {0:X} in hex.", value);

Console.WriteLine(output);     // Outputs "The decimal value 100 = 64 in hex."

Including Braces in Templates

In some circumstance you may require brace characters in the template string to be included in the output string. This is achieved by adding two brace characters. When a double brace is encountered by the Format method it is replaced by a single brace.

string output;
int value = 100;

// Convert a number to hexadecimal
output = string.Format("{{The decimal value {0} = {0:X} in hex.}}", value);

Console.WriteLine(output);     // Outputs "{The decimal value 100 = 64 in hex.}"

Console.WriteLine Method

Early in the C# Fundamentals tutorial the Console.WriteLine method was used to output some simple text in a console application. Console.WriteLine actually uses the same functionality as String.Format when generating the string that is to be outputted. This means that the above example can be greatly simplified as follows:

int value = 100;

// Convert a number to hexadecimal
Console.WriteLine("{{The decimal value {0} = {0:X} in hex.}}", value);