C# string.Format Method

String.Format creates strings from a pattern and values. It is a static method in the C# language. It receives a format string that specifies where the following arguments should inserted. The format string uses substitution markers. Formatting strings are useful. They are required throughout the .NET Framework.

This C# string.Format tutorial shows how to use patterns to format strings.

Notes: Many methods in the .NET Framework use the format syntax. These include string.Format, Console.WriteLine, ToString and AppendFormat.

Example

This example shows the use of the string.Format method to combine three strings with formatting options. The format string itself is the first argument to the string.Format method and it is specified as a string literal.

The position markers in the format string are specified to the left of the colons, and this means the "0", "1:", and "2:" indicate where the first, second, and third arguments are inserted. The part after the ":" and in between the { } brackets indicates the exact format specification for that variable.

Program that uses string.Format [C#]

using System;

class Program
{
    static void Main()
    {
	//
	// Declare three variables that we will use in the format method.
	// ... The values they have are not important.
	//
	string value1 = "Dot Net Perls";
	int value2 = 10000;
	DateTime value3 = new DateTime(2007, 11, 1);
	//
	// Use string.Format method with four arguments.
	// ... The first argument is the formatting string.
	// ... It specifies how the next three arguments are formatted.
	//
	string result = string.Format("{0}: {1:0.0} - {2:yyyy}",
	    value1,
	    value2,
	    value3);
	//
	// Write the result.
	//
	Console.WriteLine(result);
    }
}

Output

Dot Net Perls: 10000.0 - 2007

Walkthrough. There are three variables declared and initialized in the start of the Main method. These variables are used in the next call to string.Format.

The first argument to the string.Format method is a format string. The resulting string contains extra formatting between the arguments. The "0.0" part of the format string specifies how the integer is displayed, while the "yyyy" part specifies that only the four-digit year of the date should be displayed.

Number formats

To continue, you can specify that a value type such as a double can be formatted inside the string.Format method based on the format string. The format string is the first argument to the string.Format method. The format string in this example uses the 0:0.0% syntax, which means that the second argument should be formatted with the pattern 0.0%. The arguments are numbered starting at zero.

Program that uses string.Format with number [C#]

using System;

class Program
{
    static void Main()
    {
	//
	// Format a ratio as a percentage string.
	// ... You must specify the percentage symbol in the format string.
	// ... It will multiply the value by 100 for you.
	//
	double ratio = 0.73;
	string result = string.Format("string = {0:0.0%}",
	    ratio);
	Console.WriteLine(result);
    }
}

Output

string = 73.0%

Format string details. The format string here demonstrates several aspects to the string.Format method use. The 0.0% part of the format string specifies the exact number of digits that are required. Note that the 0.0% can have as many digits before the decimal place as necessary, but only one after the decimal place. The percentage symbol will result in the number being multiplied by 100 logically.

Padding

Next, padding can be used with strings. This can be expressed declaratively in formatting strings and the string.Format method. The term 'padding' indicates that you are inserting a variable number of characters at the left or right of the string to ensure that the total length of the string is a fixed length. Instead of the PadLeft and PadRight methods, you can use the string.Format method with special substitutions.

Program that uses string.Format for padding [C#]

using System;

class Program
{
    static void Main()
    {
	//
	// The constant formatting string.
	// ... It specifies the padding.
	// ... A negative number means to left-align.
	// ... A positive number means to right-align.
	//
	const string format = "{0,-10} {1,10}";
	//
	// Construct the strings.
	//
	string line1 = string.Format(format,
	    100,
	    5);
	string line2 = string.Format(format,
	    "Carrot",
	    "Giraffe");
	//
	// Write the formatted strings.
	//
	Console.WriteLine(line1);
	Console.WriteLine(line2);
    }
}

Output

100                 5
Carrot        Giraffe

Description. For declaring padding inside a format string, use the comma character followed by the padding size. You can use a negative padding size to add padding to the right, which will left-align the text. You can use a positive padding size to add padding to the left, which will right-align the string.

ToString or string.Format?

Sometimes, you need to just format a single number, like an integer or long. In this case, you don't need to use string.Format. You can just use the ToString virtual method. This reduces some overhead associated with processing the substitution marker syntax.

Program uses string.Format and ToString [C#]

using System;

class Program
{
    static void Main()
    {
	int value = 123;
	string a = string.Format("{0:0000}", value); // Too complex
	string b = value.ToString("0000"); // Simpler
	Console.WriteLine(a);
	Console.WriteLine(b);
    }
}

Output

0123
0123

Dates

The DateTime struct is a value type that is an abstract data type for any possible date and time. The string.Format method can be used with DateTime arguments and these will be inserted into the substitution markers. Because DateTime formatting is so important, this site introduces a thorough exploration of the string.Format and DateTime formatting strings.

File names

Many programs need to create files dynamically. The files often need to have file names that are based on the current date and time or another characteristic such as a counter. For example, a logging file can have a file name that is based on the exact date and time it was written.

The string.Format method provides a way to express this functionality in a clear way. You can use the string.Format method with substitutions to create the file names based on state variables.

StringBuilder (AppendFormat)

The StringBuilder type presents a method called AppendFormat. The AppendFormat method receives a formatting string and also the arguments to the formatting string, which are placed in the substitution markers. For performance work, the AppendFormat method is not ideal. It can however lead to clearer code.

Console.WriteLine formatting

Console programs can use formatting strings directly inside the Console.Write and Console.WriteLine methods. When using Visual Studio, you can type Console.WriteLine and then scroll through the IntelliSense popup to find the overloads that receive the format string. You can then call Console.WriteLine with the same arguments as the string.Format method receives, and it will internally call the string.Format method.

Implementation

In the base class library, the string.Format method uses a param argument, which is a variable parameter list. This results in an array allocation on each invocation of the method. You can discover more about the params keyword here.

Substitution processing. Internally, the string.Format method uses the StringBuilder type, which contains a mutable character buffer. It estimates a capacity based on a heuristic in the StringBuilder constructor. Next, the AppendFormat method is called to process the substitutions themselves. The ToString method is finally called. Fortunately the ToString method does not normally require a copy to be made.

Summary

The string.Format method provides a way for you to insert argument strings and separators together, and also to specify display options for each argument individually. We saw how you can combine several strings and format dates, numbers, and percentages. We noted that many methods in the .NET Framework use this syntax. And we delved into the implementation of the method itself.