String.Format Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Converts the value of objects to strings based on the formats specified and inserts them into another string.
If you are new to the String.Format method, see the Get started with the String.Format method section for a quick overview.
See the Remarks section for general documentation for the String.Format method.
Overloads
| Format(IFormatProvider, String, Object, Object, Object) |
Replaces the format items in a string with the string representation of three specified objects. An parameter supplies culture-specific formatting information. |
| Format(String, Object, Object, Object) |
Replaces the format items in a string with the string representation of three specified objects. |
| Format(IFormatProvider, String, Object, Object) |
Replaces the format items in a string with the string representation of two specified objects. A parameter supplies culture-specific formatting information. |
| Format(String, Object, Object) |
Replaces the format items in a string with the string representation of two specified objects. |
| Format(IFormatProvider, CompositeFormat, ReadOnlySpan<Object>) |
Replaces the format item or items in a CompositeFormat with the string representation of the corresponding objects in the specified format. |
| Format(IFormatProvider, String, Object) |
Replaces the format item or items in a specified string with the string representation of the corresponding object. A parameter supplies culture-specific formatting information. |
| Format(IFormatProvider, String, Object[]) |
Replaces the format items in a string with the string representations of corresponding objects in a specified array. A parameter supplies culture-specific formatting information. |
| Format(String, Object[]) |
Replaces the format item in a specified string with the string representation of a corresponding object in a specified array. |
| Format(String, Object) |
Replaces one or more format items in a string with the string representation of a specified object. |
| Format(IFormatProvider, CompositeFormat, Object[]) |
Replaces the format item or items in a CompositeFormat with the string representation of the corresponding objects in the specified format. |
| Format<TArg0,TArg1,TArg2>(IFormatProvider, CompositeFormat, TArg0, TArg1, TArg2) |
Replaces the format item or items in a CompositeFormat with the string representation of the corresponding objects in the specified format. |
| Format<TArg0,TArg1>(IFormatProvider, CompositeFormat, TArg0, TArg1) |
Replaces the format item or items in a CompositeFormat with the string representation of the corresponding objects in the specified format. |
| Format<TArg0>(IFormatProvider, CompositeFormat, TArg0) |
Replaces the format item or items in a CompositeFormat with the string representation of the corresponding objects in the specified format. |
Examples
Numerous examples that call the Format method are interspersed through the Remarks section of this article.
You can also download a complete set of String.Format examples, which are included a .NET Core project for C#.
The following are some of the examples included in the article:
Create a format string
Inserting a string
The format item
Format items that have the same index
Control formatted output
Controlling formatting
Controlling spacing
Controlling alignment
Controlling the number of integral digits
Controlling the number of digits after the decimal separator
Including literal braces in a result string
Make format strings culture-sensitive
Customize the formatting operation
A custom formatting operation
An intercept provider and Roman numeral formatter
Remarks
Important
Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).
In this section:
Get started with the String.Format method
Which method do I call?
The Format method in brief
The Format item
How arguments are formatted
Format items that have the same index
Formatting and culture
Custom formatting operations
String.Format Q & A
Get started with the String.Format method
Use String.Format if you need to insert the value of an object, variable, or expression into another string. For example, you can insert the value of a Decimal value into a string to display it to the user as a single string:
Decimal pricePerOunce = (Decimal)17.36;
String^ s = String::Format("The current price is {0} per ounce.",
pricePerOunce);
// Result: The current price is 17.36 per ounce.
Decimal pricePerOunce = 17.36m;
String s = String.Format("The current price is {0} per ounce.",
pricePerOunce);
Console.WriteLine(s);
// Result: The current price is 17.36 per ounce.
let pricePerOunce = 17.36m
String.Format("The current price is {0} per ounce.", pricePerOunce)
|> printfn "%s"
// Result: The current price is 17.36 per ounce.
Dim pricePerOunce As Decimal = 17.36d
Dim s As String = String.Format("The current price is {0} per ounce.",
pricePerOunce)
' Result: The current price is 17.36 per ounce.
And you can control that value's formatting:
Decimal pricePerOunce = (Decimal)17.36;
String^ s = String::Format("The current price is {0:C2} per ounce.",
pricePerOunce);
// Result if current culture is en-US:
// The current price is $17.36 per ounce.
Decimal pricePerOunce = 17.36m;
String s = String.Format("The current price is {0:C2} per ounce.",
pricePerOunce);
Console.WriteLine(s);
// Result if current culture is en-US:
// The current price is $17.36 per ounce.
let pricePerOunce = 17.36m
String.Format("The current price is {0:C2} per ounce.", pricePerOunce)
|> printfn "%s"
// Result if current culture is en-US:
// The current price is $17.36 per ounce.
Dim pricePerOunce As Decimal = 17.36d
Dim s As String = String.Format("The current price is {0:C2} per ounce.",
pricePerOunce)
' Result if current culture is en-US:
' The current price is $17.36 per ounce.
Besides formatting, you can also control alignment and spacing.
Insert a string
String.Format starts with a format string, followed by one or more objects or expressions that will be converted to strings and inserted at a specified place in the format string. For example:
Decimal temp = (Decimal)20.4;
String^ s = String::Format("The temperature is {0}°C.", temp);
Console::WriteLine(s);
// Displays 'The temperature is 20.4°C.'
decimal temp = 20.4m;
string s = String.Format("The temperature is {0}°C.", temp);
Console.WriteLine(s);
// Displays 'The temperature is 20.4°C.'
let temp = 20.4m
String.Format("The temperature is {0}°C.", temp)
|> printfn "%s"
// Displays 'The temperature is 20.4°C.'
Dim temp As Decimal = 20.4d
Dim s As String = String.Format("The temperature is {0}°C.", temp)
Console.WriteLine(s)
' Displays 'The temperature is 20.4°C.'
The {0} in the format string is a format item. 0 is the index of the object whose string value will be inserted at that position. (Indexes start at 0.) If the object to be inserted is not a string, its ToString method is called to convert it to one before inserting it in the result string.
Here's another example that uses two format items and two objects in the object list:
String^ s = String::Format("At {0}, the temperature is {1}°C.",
DateTime::Now, 20.4);
// Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.'
string s = String.Format("At {0}, the temperature is {1}°C.",
DateTime.Now, 20.4);
Console.WriteLine(s);
// Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.'
String.Format("At {0}, the temperature is {1}°C.", DateTime.Now, 20.4)
|> printfn "%s"
// Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.'
Dim s As String = String.Format("At {0}, the temperature is {1}°C.",
Date.Now, 20.4)
' Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.'
You can have as many format items and as many objects in the object list as you want, as long as the index of every format item has a matching object in the object list. You also don't have to worry about which overload you call; the compiler will select the appropriate one for you.
Control formatting
You can follow the index in a format item with a format string to control how an object is formatted. For example, {0:d} applies the "d" format string to the first object in the object list. Here is an example with a single object and two format items:
String^ s = String::Format("It is now {0:d} at {0:t}",
DateTime::Now);
// Output similar to: 'It is now 4/10/2015 at 10:04 AM'
string s = String.Format("It is now {0:d} at {0:t}", DateTime.Now);
Console.WriteLine(s);
// Output similar to: 'It is now 4/10/2015 at 10:04 AM'
String.Format("It is now {0:d} at {0:t}", DateTime.Now)
|> printfn "%s"
// Output similar to: 'It is now 4/10/2015 at 10:04 AM'
Dim s As String = String.Format("It is now {0:d} at {0:t}",
Date.Now)
' Output similar to: 'It is now 4/10/2015 at 10:04 AM'
A number of types support format strings, including all numeric types (both standard and custom format strings), all dates and times (both standard and custom format strings) and time intervals (both standard and custom format strings), all enumeration types enumeration types, and GUIDs. You can also add support for format strings to your own types.
Control spacing
You can define the width of the string that is inserted into the result string by using syntax such as {0,12}, which inserts a 12-character string. In this case, the string representation of the first object is right-aligned in the 12-character field. (If the string representation of the first object is more than 12 characters in length, though, the preferred field width is ignored, and the entire string is inserted into the result string.)
The following example defines a 6-character field to hold the string "Year" and some year strings, as well as an 15-character field to hold the string "Population" and some population data. Note that the characters are right-aligned in the field.
array<int>^ years = { 2013, 2014, 2015 };
array<int>^ population = { 1025632, 1105967, 1148203 };
StringBuiler^ sb = gcnew StringBuilder();
sb->Append(String::Format("{0,6} {1,15}\n\n", "Year", "Population"));
for(int index = 0; index < years->Length; index++)
sb->AppendFormat("{0,6} {1,15:N0}\n",
years[index], population[index]);
// Result:
// Year Population
//
// 2013 1,025,632
// 2014 1,105,967
// 2015 1,148,203
int[] years = { 2013, 2014, 2015 };
int[] population = { 1025632, 1105967, 1148203 };
var sb = new System.Text.StringBuilder();
sb.Append(String.Format("{0,6} {1,15}\n\n", "Year", "Population"));
for (int index = 0; index < years.Length; index++)
sb.Append(String.Format("{0,6} {1,15:N0}\n", years[index], population[index]));
Console.WriteLine(sb);
// Result:
// Year Population
//
// 2013 1,025,632
// 2014 1,105,967
// 2015 1,148,203
open System
open System.Text
let years = [| 2013; 2014; 2015 |]
let population = [| 1025632; 1105967; 1148203 |]
let sb = StringBuilder()
sb.Append(String.Format("{0,6} {1,15}\n\n", "Year", "Population")) |> ignore
for i = 0 to years.Length - 1 do
sb.Append(String.Format("{0,6} {1,15:N0}\n", years[i], population[i])) |> ignore
printfn $"{sb}"
// Result:
// Year Population
//
// 2013 1,025,632
// 2014 1,105,967
// 2015 1,148,203
Dim years() As Integer = { 2013, 2014, 2015 }
Dim population() As Integer = { 1025632, 1105967, 1148203 }
Dim sb As New StringBuilder()
sb.Append(String.Format("{0,6} {1,15}{2}{2}",
"Year", "Population", vbCrLf))
For index As Integer = 0 To years.Length - 1
sb.AppendFormat("{0,6} {1,15:N0}{2}",
years(index), population(index), vbCrLf)
Next
' Result:
' Year Population
'
' 2013 1,025,632
' 2014 1,105,967
' 2015 1,148,203
Control alignment
By default, strings are right-aligned within their field if you specify a field width. To left-align strings in a field, you preface the field width with a negative sign, such as {0,-12} to define a 12-character left-aligned field.
The following example is similar to the previous one, except that it left-aligns both labels and data.
array<int>^ years = { 2013, 2014, 2015 };
array<int>^ population = { 1025632, 1105967, 1148203 };
String^ s = String::Format("{0,-10} {1,-10}\n\n", "Year", "Population");
for(int index = 0; index < years->Length; index++)
s += String::Format("{0,-10} {1,-10:N0}\n",
years[index], population[index]);
// Result:
// Year Population
//
// 2013 1,025,632
// 2014 1,105,967
// 2015 1,148,203
int[] years = { 2013, 2014, 2015 };
int[] population = { 1025632, 1105967, 1148203 };
String s = String.Format("{0,-10} {1,-10}\n\n", "Year", "Population");
for(int index = 0; index < years.Length; index++)
s += String.Format("{0,-10} {1,-10:N0}\n",
years[index], population[index]);
Console.WriteLine($"\n{s}");
// Result:
// Year Population
//
// 2013 1,025,632
// 2014 1,105,967
// 2015 1,148,203
let years = [| 2013; 2014; 2015 |]
let population = [| 1025632; 1105967; 1148203 |]
let mutable s = String.Format("{0,-10} {1,-10}\n\n", "Year", "Population")
for i = 0 to years.Length - 1 do
s <- s + String.Format("{0,-10} {1,-10:N0}\n", years[i], population[i])
printfn $"\n{s}"
// Result:
// Year Population
//
// 2013 1,025,632
// 2014 1,105,967
// 2015 1,148,203
Dim years() As Integer = { 2013, 2014, 2015 }
Dim population() As Integer = { 1025632, 1105967, 1148203 }
Dim s As String = String.Format("{0,-10} {1,-10}{2}{2}",
"Year", "Population", vbCrLf)
For index As Integer = 0 To years.Length - 1
s += String.Format("{0,-10} {1,-10:N0}{2}",
years(index), population(index), vbCrLf)
Next
' Result:
' Year Population
'
' 2013 1,025,632
' 2014 1,105,967
' 2015 1,148,203
String.Format makes use of the composite formatting feature. For more information, see Composite Formatting.
Which method do I call?
| To | Call |
|---|---|
| Format one or more objects by using the conventions of the current culture. | Except for the overloads that include a provider parameter, the remaining Format overloads include a String parameter followed by one or more object parameters. Because of this, you don't have to determine which Format overload you intend to call. Your language compiler selects the appropriate overload from among the overloads that don't have a provider parameter, based on your argument list. For example, if your argument list has five arguments, the compiler calls the Format(String, Object[]) method. |
| Format one or more objects by using the conventions of a specific culture. | Each Format overload that begins with a provider parameter is followed by a String parameter and one or more object parameters. Because of this, you don't have to determine which specific Format overload you intend to call. Your language compiler selects the appropriate overload from among the overloads that have a provider parameter, based on your argument list. For example, if your argument list has five arguments, the compiler calls the Format(IFormatProvider, String, Object[]) method. |
| Perform a custom formatting operation either with an ICustomFormatter implementation or an IFormattable implementation. | Any of the four overloads with a provider parameter. The compiler selects the appropriate overload from among the overloads that have a provider parameter, based on your argument list. |
The Format method in brief
Each overload of the Format method uses the composite formatting feature to include zero-based indexed placeholders, called format items, in a composite format string. At run time, each format item is replaced with the string representation of the corresponding argument in a parameter list. If the value of the argument is null, the format item is replaced with String.Empty. For example, the following call to the Format(String, Object, Object, Object) method includes a format string with three format items, {0}, {1}, and {2}, and an argument list with three items.
using namespace System;
void main()
{
DateTime^ dat = gcnew DateTime(2012, 1, 17, 9, 30, 0);
String^ city = "Chicago";
int temp = -16;
String^ output = String::Format("At {0} in {1}, the temperature was {2} degrees.",
dat, city, temp);
Console::WriteLine(output);
}
// The example displays the following output:
// At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees.
DateTime dat = new DateTime(2012, 1, 17, 9, 30, 0);
string city = "Chicago";
int temp = -16;
string output = String.Format("At {0} in {1}, the temperature was {2} degrees.",
dat, city, temp);
Console.WriteLine(output);
// The example displays output like the following:
// At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees.
open System
let dat = DateTime(2012, 1, 17, 9, 30, 0)
let city = "Chicago"
let temp = -16
String.Format("At {0} in {1}, the temperature was {2} degrees.", dat, city, temp)
|> printfn "%s"
// The example displays output like the following:
// At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees.
Dim dat As Date = #1/17/2012 9:30AM#
Dim city As String = "Chicago"
Dim temp As Integer = -16
Dim output As String = String.Format("At {0} in {1}, the temperature was {2} degrees.",
dat, city, temp)
Console.WriteLine(output)
' The example displays the following output:
' At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees.
The format item
A format item has this syntax:
{index[,alignment][:formatString]}
Brackets denote optional elements. The opening and closing braces are required. (To include a literal opening or closing brace in the format string, see the Escaping Braces section in the Composite Formatting article.)
For example, a format item to format a currency value might appear like this:
String::Format("{0,-10:C}", (Decimal) 126347.89);
var value = String.Format("{0,-10:C}", 126347.89m);
Console.WriteLine(value);
open System
String.Format("{0,-10:C}", 126347.89m)
|> printfn "%s"
String.Format("{0,-10:C}", 126347.89d)
A format item has the following elements:
index
The zero-based index of the argument whose string representation is to be included at this position in the string. If this argument is null, an empty string will be included at this position in the string.
alignment
Optional. A signed integer that indicates the total length of the field into which the argument is inserted and whether it is right-aligned (a positive integer) or left-aligned (a negative integer). If you omit alignment, the string representation of the corresponding argument is inserted in a field with no leading or trailing spaces.
If the value of alignment is less than the length of the argument to be inserted, alignment is ignored and the length of the string representation of the argument is used as the field width.
formatString
Optional. A string that specifies the format of the corresponding argument's result string. If you omit formatString, the corresponding argument's parameterless ToString method is called to produce its string representation. If you specify formatString, the argument referenced by the format item must implement the IFormattable interface. Types that support format strings include:
All integral and floating-point types. (See Standard Numeric Format Strings and Custom Numeric Format Strings.)
DateTime and DateTimeOffset. (See Standard Date and Time Format Strings and Custom Date and Time Format Strings.)
All enumeration types. (See Enumeration Format Strings.)
TimeSpan values. (See Standard TimeSpan Format Strings and Custom TimeSpan Format Strings.)
GUIDs. (See the Guid.ToString(String) method.)
However, note that any custom type can implement IFormattable or extend an existing type's IFormattable implementation.
The following example uses the alignment and formatString arguments to produce formatted output.
using namespace System;
void main()
{
// Create array of 5-tuples with population data for three U.S. cities, 1940-1950.
array<Tuple<String^, DateTime, int, DateTime, int>^>^ cities = gcnew array<Tuple<String^, DateTime, int, DateTime, int>^>
{ gcnew Tuple<String^, DateTime, int, DateTime, int>("Los Angeles", DateTime(1940, 1, 1), 1504277,
DateTime(1950, 1, 1), 1970358),
gcnew Tuple<String^, DateTime, int, DateTime, int>("New York", DateTime(1940, 1, 1), 7454995,
DateTime(1950, 1, 1), 7891957),
gcnew Tuple<String^, DateTime, int, DateTime, int>("Chicago", DateTime(1940, 1, 1), 3396808,
DateTime(1950, 1, 1), 3620962),
gcnew Tuple<String^, DateTime, int, DateTime, int>("Detroit", DateTime(1940, 1, 1), 1623452,
DateTime(1950, 1, 1), 1849568) };
// Display header
String^ header = String::Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}\n",
"City", "Year", "Population", "Change (%)");
Console::WriteLine(header);
String^ output;
for each (Tuple<String^, DateTime, int, DateTime, int>^ city in cities) {
output = String::Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}",
city->Item1, city->Item2, city->Item3, city->Item4, city->Item5,
(city->Item5 - city->Item3)/ (double)city->Item3);
Console::WriteLine(output);
}
}
// The example displays the following output:
// City Year Population Year Population Change (%)
//
// Los Angeles 1940 1,504,277 1950 1,970,358 31.0 %
// New York 1940 7,454,995 1950 7,891,957 5.9 %
// Chicago 1940 3,396,808 1950 3,620,962 6.6 %
// Detroit 1940 1,623,452 1950 1,849,568 13.9 %
// Create array of 5-tuples with population data for three U.S. cities, 1940-1950.
Tuple<string, DateTime, int, DateTime, int>[] cities =
{ Tuple.Create("Los Angeles", new DateTime(1940, 1, 1), 1504277,
new DateTime(1950, 1, 1), 1970358),
Tuple.Create("New York", new DateTime(1940, 1, 1), 7454995,
new DateTime(1950, 1, 1), 7891957),
Tuple.Create("Chicago", new DateTime(1940, 1, 1), 3396808,
new DateTime(1950, 1, 1), 3620962),
Tuple.Create("Detroit", new DateTime(1940, 1, 1), 1623452,
new DateTime(1950, 1, 1), 1849568) };
// Display header
var header = String.Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}\n",
"City", "Year", "Population", "Change (%)");
Console.WriteLine(header);
foreach (var city in cities) {
var output = String.Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}",
city.Item1, city.Item2, city.Item3, city.Item4, city.Item5,
(city.Item5 - city.Item3)/ (double)city.Item3);
Console.WriteLine(output);
}
// The example displays the following output:
// City Year Population Year Population Change (%)
//
// Los Angeles 1940 1,504,277 1950 1,970,358 31.0 %
// New York 1940 7,454,995 1950 7,891,957 5.9 %
// Chicago 1940 3,396,808 1950 3,620,962 6.6 %
// Detroit 1940 1,623,452 1950 1,849,568 13.9 %
// Create a list of 5-tuples with population data for three U.S. cities, 1940-1950.
let cities =
[ "Los Angeles", DateTime(1940, 1, 1), 1504277, DateTime(1950, 1, 1), 1970358
"New York", DateTime(1940, 1, 1), 7454995, DateTime(1950, 1, 1), 7891957
"Chicago", DateTime(1940, 1, 1), 3396808, DateTime(1950, 1, 1), 3620962
"Detroit", DateTime(1940, 1, 1), 1623452, DateTime(1950, 1, 1), 1849568 ]
// Display header
String.Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}\n", "City", "Year", "Population", "Change (%)")
|> printfn "%s"
for name, year1, pop1, year2, pop2 in cities do
String.Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}",
name, year1, pop1, year2, pop2,
double (pop2 - pop1) / double pop1)
|> printfn "%s"
// The example displays the following output:
// City Year Population Year Population Change (%)
//
// Los Angeles 1940 1,504,277 1950 1,970,358 31.0 %
// New York 1940 7,454,995 1950 7,891,957 5.9 %
// Chicago 1940 3,396,808 1950 3,620,962 6.6 %
// Detroit 1940 1,623,452 1950 1,849,568 13.9 %
Module Example
Public Sub Main()
' Create array of 5-tuples with population data for three U.S. cities, 1940-1950.
Dim cities() = _
{ Tuple.Create("Los Angeles", #1/1/1940#, 1504277, #1/1/1950#, 1970358),
Tuple.Create("New York", #1/1/1940#, 7454995, #1/1/1950#, 7891957),
Tuple.Create("Chicago", #1/1/1940#, 3396808, #1/1/1950#, 3620962),
Tuple.Create("Detroit", #1/1/1940#, 1623452, #1/1/1950#, 1849568) }
' Display header
Dim header As String = String.Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}",
"City", "Year", "Population", "Change (%)")
Console.WriteLine(header)
Console.WriteLine()
For Each city In cities
Dim output = String.Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}",
city.Item1, city.Item2, city.Item3, city.Item4, city.Item5,
(city.Item5 - city.Item3)/city.Item3)
Console.WriteLine(output)
Next
End Sub
End Module
' The example displays the following output:
' City Year Population Year Population Change (%)
'
' Los Angeles 1940 1,504,277 1950 1,970,358 31.0 %
' New York 1940 7,454,995 1950 7,891,957 5.9 %
' Chicago 1940 3,396,808 1950 3,620,962 6.6 %
' Detroit 1940 1,623,452 1950 1,849,568 13.9 %
How arguments are formatted
Format items are processed sequentially from the beginning of the string. Each format item has an index that corresponds to an object in the method's argument list. The Format method retrieves the argument and derives its string representation as follows:
If the argument is
null, the method inserts String.Empty into the result string. You don't have to be concerned with handling a NullReferenceException for null arguments.If you call the Format(IFormatProvider, String, Object[]) overload and the
providerobject's IFormatProvider.GetFormat implementation returns a non-null ICustomFormatter implementation, the argument is passed to its ICustomFormatter.Format(String, Object, IFormatProvider) method. If the format item includes a formatString argument, it is passed as the first argument to the method. If the ICustomFormatter implementation is available and produces a non-null string, that string is returned as the string representation of the argument; otherwise, the next step executes.If the argument implements the IFormattable interface, its IFormattable.ToString implementation is called.
The argument's parameterless
ToStringmethod, which either overrides or inherits from a base class implementation, is called.
For an example that intercepts calls to the ICustomFormatter.Format method and allows you to see what information the Format method passes to a formatting method for each format item in a composite format string, see Example: An intercept provider and Roman numeral formatter.
For more information, see the Processing Order section in the Composite Formatting article.
Format items that have the same index
The Format method throws a FormatException exception if the index of an index item is greater than or equal to the number of arguments in the argument list. However, format can include more format items than there are arguments, as long as multiple format items have the same index. In the call to the Format(String, Object) method in following example, the argument list has a single argument, but the format string includes two format items: one displays the decimal value of a number, and the other displays its hexadecimal value.
short[] values= { Int16.MinValue, -27, 0, 1042, Int16.MaxValue };
Console.WriteLine("{0,10} {1,10}\n", "Decimal", "Hex");
foreach (short value in values)
{
string formatString = String.Format("{0,10:G}: {0,10:X}", value);
Console.WriteLine(formatString);
}
// The example displays the following output:
// Decimal Hex
//
// -32768: 8000
// -27: FFE5
// 0: 0
// 1042: 412
// 32767: 7FFF
open System
let values= [| Int16.MinValue; -27s; 0s; 1042s; Int16.MaxValue |]
printfn "%10s %10s\n" "Decimal" "Hex"
for value in values do
String.Format("{0,10:G}: {0,10:X}", value)
|> printfn "%s"
// The example displays the following output:
// Decimal Hex
//
// -32768: 8000
// -27: FFE5
// 0: 0
// 1042: 412
// 32767: 7FFF
Module Example
Public Sub Main()
Dim values() As Short = { Int16.MinValue, -27, 0, 1042, Int16.MaxValue }
Console.WriteLine("{0,10} {1,10}", "Decimal", "Hex")
Console.WriteLine()
For Each value As Short In values
Dim formatString As String = String.Format("{0,10:G}: {0,10:X}", value)
Console.WriteLine(formatString)
Next
End Sub
End Module
' The example displays the following output:
' Decimal Hex
'
' -32768: 8000
' -27: FFE5
' 0: 0
' 1042: 412
' 32767: 7FFF
Format and culture
Generally, objects in the argument list are converted to their string representations by using the conventions of the current culture, which is returned by the CultureInfo.CurrentCulture property. You can control this behavior by calling one of the overloads of Format that includes a provider parameter. The provider parameter is an IFormatProvider implementation that supplies custom and culture-specific formatting information that is used to moderate the formatting process.
The IFormatProvider interface has a single member, GetFormat, which is responsible for returning the object that provides formatting information. .NET has three IFormatProvider implementations that provide culture-specific formatting:
CultureInfo. Its GetFormat method returns a culture-specific NumberFormatInfo object for formatting numeric values and a culture-specific DateTimeFormatInfo object for formatting date and time values.
DateTimeFormatInfo, which is used for culture-specific formatting of date and time values. Its GetFormat method returns itself.
NumberFormatInfo, which is used for culture-specific formatting of numeric values. Its GetFormat property returns itself.
Custom formatting operations
You can also call the any of the overloads of the Format method that have a provider parameter of type IFormatProvider to perform custom formatting operations. For example, you could format an integer as an identification number or as a telephone number. To perform custom formatting, your provider argument must implement both the IFormatProvider and ICustomFormatter interfaces. When the Format method is passed an ICustomFormatter implementation as the provider argument, the Format method calls its IFormatProvider.GetFormat implementation and requests an object of type ICustomFormatter. It then calls the returned ICustomFormatter object's Format method to format each format item in the composite string passed to it.
For more information about providing custom formatting solutions, see How to: Define and Use Custom Numeric Format Providers and ICustomFormatter. For an example that converts integers to formatted custom numbers, see Example: A custom formatting operation. For an example that converts unsigned bytes to Roman numerals, see Example: An intercept provider and Roman numeral formatter.
Example: A custom formatting operation
This example defines a format provider that formats an integer value as a customer account number in the form x-xxxxx-xx.
using namespace System;
ref class CustomerFormatter : IFormatProvider, ICustomFormatter
{
public:
virtual Object^ GetFormat(Type^ formatType)
{
if (formatType == ICustomFormatter::typeid)
return this;
else
return nullptr;
}
virtual String^ Format(String^ format,
Object^ arg,
IFormatProvider^ formatProvider)
{
if (! this->Equals(formatProvider))
{
return nullptr;
}
else
{
if (String::IsNullOrEmpty(format))
format = "G";
String^ customerString = arg->ToString();
if (customerString->Length < 8)
customerString = customerString->PadLeft(8, '0');
format = format->ToUpper();
if (format == L"G")
return customerString->Substring(0, 1) + "-" +
customerString->Substring(1, 5) + "-" +
customerString->Substring(6);
else if (format == L"S")
return customerString->Substring(0, 1) + "/" +
customerString->Substring(1, 5) + "/" +
customerString->Substring(6);
else if (format == L"P")
return customerString->Substring(0, 1) + "." +
customerString->Substring(1, 5) + "." +
customerString->Substring(6);
else
throw gcnew FormatException(
String::Format("The '{0}' format specifier is not supported.", format));
}
}
};
void main()
{
int acctNumber = 79203159;
Console::WriteLine(String::Format(gcnew CustomerFormatter, "{0}", acctNumber));
Console::WriteLine(String::Format(gcnew CustomerFormatter, "{0:G}", acctNumber));
Console::WriteLine(String::Format(gcnew CustomerFormatter, "{0:S}", acctNumber));
Console::WriteLine(String::Format(gcnew CustomerFormatter, "{0:P}", acctNumber));
try {
Console::WriteLine(String::Format(gcnew CustomerFormatter, "{0:X}", acctNumber));
}
catch (FormatException^ e) {
Console::WriteLine(e->Message);
}
}
// The example displays the following output:
// 7-92031-59
// 7-92031-59
// 7/92031/59
// 7.92031.59
// The 'X' format specifier is not supported.
using System;
public class TestFormatter
{
public static void Main()
{
int acctNumber = 79203159;
Console.WriteLine(String.Format(new CustomerFormatter(), "{0}", acctNumber));
Console.WriteLine(String.Format(new CustomerFormatter(), "{0:G}", acctNumber));
Console.WriteLine(String.Format(new CustomerFormatter(), "{0:S}", acctNumber));
Console.WriteLine(String.Format(new CustomerFormatter(), "{0:P}", acctNumber));
try {
Console.WriteLine(String.Format(new CustomerFormatter(), "{0:X}", acctNumber));
}
catch (FormatException e) {
Console.WriteLine(e.Message);
}
}
}
public class CustomerFormatter : IFormatProvider, ICustomFormatter
{
public object GetFormat(Type formatType)
{
if (formatType == typeof(ICustomFormatter))
return this;
else
return null;
}
public string Format(string format,
object arg,
IFormatProvider formatProvider)
{
if (! this.Equals(formatProvider))
{
return null;
}
else
{
if (String.IsNullOrEmpty(format))
format = "G";
string customerString = arg.ToString();
if (customerString.Length < 8)
customerString = customerString.PadLeft(8, '0');
format = format.ToUpper();
switch (format)
{
case "G":
return customerString.Substring(0, 1) + "-" +
customerString.Substring(1, 5) + "-" +
customerString.Substring(6);
case "S":
return customerString.Substring(0, 1) + "/" +
customerString.Substring(1, 5) + "/" +
customerString.Substring(6);
case "P":
return customerString.Substring(0, 1) + "." +
customerString.Substring(1, 5) + "." +
customerString.Substring(6);
default:
throw new FormatException(
String.Format("The '{0}' format specifier is not supported.", format));
}
}
}
}
// The example displays the following output:
// 7-92031-59
// 7-92031-59
// 7/92031/59
// 7.92031.59
// The 'X' format specifier is not supported.
open System
type CustomerFormatter() =
interface IFormatProvider with
member this.GetFormat(formatType) =
if formatType = typeof<ICustomFormatter> then
this
else
null
interface ICustomFormatter with
member this.Format(format, arg, formatProvider: IFormatProvider) =
if this.Equals formatProvider |> not then
null
else
let format =
if String.IsNullOrEmpty format then "G"
else format.ToUpper()
let customerString =
let s = string arg
if s.Length < 8 then
s.PadLeft(8, '0')
else s
match format with
| "G" ->
customerString.Substring(0, 1) + "-" +
customerString.Substring(1, 5) + "-" +
customerString.Substring 6
| "S" ->
customerString.Substring(0, 1) + "/" +
customerString.Substring(1, 5) + "/" +
customerString.Substring 6
| "P" ->
customerString.Substring(0, 1) + "." +
customerString.Substring(1, 5) + "." +
customerString.Substring 6
| _ ->
raise (FormatException $"The '{format}' format specifier is not supported.")
let acctNumber = 79203159
String.Format(CustomerFormatter(), "{0}", acctNumber)
|> printfn "%s"
String.Format(CustomerFormatter(), "{0:G}", acctNumber)
|> printfn "%s"
String.Format(CustomerFormatter(), "{0:S}", acctNumber)
|> printfn "%s"
String.Format(CustomerFormatter(), "{0:P}", acctNumber)
|> printfn "%s"
try
String.Format(CustomerFormatter(), "{0:X}", acctNumber)
|> printfn "%s"
with :? FormatException as e ->
printfn $"{e.Message}"
// The example displays the following output:
// 7-92031-59
// 7-92031-59
// 7/92031/59
// 7.92031.59
// The 'X' format specifier is not supported.
Module TestFormatter
Public Sub Main()
Dim acctNumber As Integer = 79203159
Console.WriteLine(String.Format(New CustomerFormatter, "{0}", acctNumber))
Console.WriteLine(String.Format(New CustomerFormatter, "{0:G}", acctNumber))
Console.WriteLine(String.Format(New CustomerFormatter, "{0:S}", acctNumber))
Console.WriteLine(String.Format(New CustomerFormatter, "{0:P}", acctNumber))
Try
Console.WriteLine(String.Format(New CustomerFormatter, "{0:X}", acctNumber))
Catch e As FormatException
Console.WriteLine(e.Message)
End Try
End Sub
End Module
Public Class CustomerFormatter : Implements IFormatProvider, ICustomFormatter
Public Function GetFormat(type As Type) As Object _
Implements IFormatProvider.GetFormat
If type Is GetType(ICustomFormatter) Then
Return Me
Else
Return Nothing
End If
End Function
Public Function Format(fmt As String, _
arg As Object, _
formatProvider As IFormatProvider) As String _
Implements ICustomFormatter.Format
If Not Me.Equals(formatProvider) Then
Return Nothing
Else
If String.IsNullOrEmpty(fmt) Then fmt = "G"
Dim customerString As String = arg.ToString()
if customerString.Length < 8 Then _
customerString = customerString.PadLeft(8, "0"c)
Select Case fmt
Case "G"
Return customerString.Substring(0, 1) & "-" & _
customerString.Substring(1, 5) & "-" & _
customerString.Substring(6)
Case "S"
Return customerString.Substring(0, 1) & "/" & _
customerString.Substring(1, 5) & "/" & _
customerString.Substring(6)
Case "P"
Return customerString.Substring(0, 1) & "." & _
customerString.Substring(1, 5) & "." & _
customerString.Substring(6)
Case Else
Throw New FormatException( _
String.Format("The '{0}' format specifier is not supported.", fmt))
End Select
End If
End Function
End Class
' The example displays the following output:
' 7-92031-59
' 7-92031-59
' 7/92031/59
' 7.92031.59
' The 'X' format specifier is not supported.
Example: An intercept provider and Roman numeral formatter
This example defines a custom format provider that implements the ICustomFormatter and IFormatProvider interfaces to do two things:
It displays the parameters passed to its ICustomFormatter.Format implementation. This enables us to see what parameters the Format(IFormatProvider, String, Object[]) method is passing to the custom formatting implementation for each object that it tries to format. This can be useful when you're debugging your application.
If the object to be formatted is an unsigned byte value that is to be formatted by using the "R" standard format string, the custom formatter formats the numeric value as a Roman numeral.
using namespace System;
using namespace System::Globalization;
ref class InterceptProvider : IFormatProvider, ICustomFormatter
{
public:
virtual Object^ GetFormat(Type^ formatType)
{
if (formatType == ICustomFormatter::typeid)
return this;
else
return nullptr;
}
virtual String^ Format(String^ format, Object^ obj, IFormatProvider^ provider)
{
// Display information about method call.
String^ formatString = format != nullptr ? format : "<null>";
Console::WriteLine("Provider: {0}, Object: {1}, Format String: {2}",
provider, obj != nullptr ? obj : "<null>", formatString);
if (obj == nullptr) return String::Empty;
// If this is a byte and the "R" format string, format it with Roman numerals.
if (obj->GetType() == Byte::typeid && formatString->ToUpper()->Equals("R")) {
Byte value = (Byte) obj;
int remainder;
int result;
String^ returnString = String::Empty;
// Get the hundreds digit(s)
result = Math::DivRem(value, 100, remainder);
if (result > 0)
returnString = gcnew String('C', result);
value = (Byte) remainder;
// Get the 50s digit
result = Math::DivRem(value, 50, remainder);
if (result == 1)
returnString += "L";
value = (Byte) remainder;
// Get the tens digit.
result = Math::DivRem(value, 10, remainder);
if (result > 0)
returnString += gcnew String('X', result);
value = (Byte) remainder;
// Get the fives digit.
result = Math::DivRem(value, 5, remainder);
if (result > 0)
returnString += "V";
value = (Byte) remainder;
// Add the ones digit.
if (remainder > 0)
returnString += gcnew String('I', remainder);
// Check whether we have too many X characters.
int pos = returnString->IndexOf("XXXX");
if (pos >= 0) {
int xPos = returnString->IndexOf("L");
if ((xPos >= 0) & (xPos == pos - 1))
returnString = returnString->Replace("LXXXX", "XC");
else
returnString = returnString->Replace("XXXX", "XL");
}
// Check whether we have too many I characters
pos = returnString->IndexOf("IIII");
if (pos >= 0)
if (returnString->IndexOf("V") >= 0)
returnString = returnString->Replace("VIIII", "IX");
else
returnString = returnString->Replace("IIII", "IV");
return returnString;
}
// Use default for all other formatting.
if (obj->GetType() == IFormattable::typeid)
return ((IFormattable^) obj)->ToString(format, CultureInfo::CurrentCulture);
else
return obj->ToString();
}
};
void main()
{
int n = 10;
double value = 16.935;
DateTime day = DateTime::Now;
InterceptProvider^ provider = gcnew InterceptProvider();
Console::WriteLine(String::Format(provider, "{0:N0}: {1:C2} on {2:d}\n", n, value, day));
Console::WriteLine(String::Format(provider, "{0}: {1:F}\n", "Today: ",
(DayOfWeek) DateTime::Now.DayOfWeek));
Console::WriteLine(String::Format(provider, "{0:X}, {1}, {2}\n",
(Byte) 2, (Byte) 12, (Byte) 199));
Console::WriteLine(String::Format(provider, "{0:R}, {1:R}, {2:R}\n",
(Byte) 2, (Byte) 12, (Byte) 199));
}
// The example displays the following output:
// Provider: InterceptProvider, Object: 10, Format String: N0
// Provider: InterceptProvider, Object: 16.935, Format String: C2
// Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d
// 10: $16.94 on 1/31/2013
//
// Provider: InterceptProvider, Object: Today: , Format String: <null>
// Provider: InterceptProvider, Object: Thursday, Format String: F
// Today: : Thursday
//
// Provider: InterceptProvider, Object: 2, Format String: X
// Provider: InterceptProvider, Object: 12, Format String: <null>
// Provider: InterceptProvider, Object: 199, Format String: <null>
// 2, 12, 199
//
// Provider: InterceptProvider, Object: 2, Format String: R
// Provider: InterceptProvider, Object: 12, Format String: R
// Provider: InterceptProvider, Object: 199, Format String: R
// II, XII, CXCIX
using System;
using System.Globalization;
public class InterceptProvider : IFormatProvider, ICustomFormatter
{
public object GetFormat(Type formatType)
{
if (formatType == typeof(ICustomFormatter))
return this;
else
return null;
}
public string Format(String format, Object obj, IFormatProvider provider)
{
// Display information about method call.
string formatString = format ?? "<null>";
Console.WriteLine("Provider: {0}, Object: {1}, Format String: {2}",
provider.GetType().Name, obj ?? "<null>", formatString);
if (obj == null) return String.Empty;
// If this is a byte and the "R" format string, format it with Roman numerals.
if (obj is Byte && formatString.ToUpper().Equals("R")) {
Byte value = (Byte) obj;
int remainder;
int result;
String returnString = String.Empty;
// Get the hundreds digit(s)
result = Math.DivRem(value, 100, out remainder);
if (result > 0)
returnString = new String('C', result);
value = (Byte) remainder;
// Get the 50s digit
result = Math.DivRem(value, 50, out remainder);
if (result == 1)
returnString += "L";
value = (Byte) remainder;
// Get the tens digit.
result = Math.DivRem(value, 10, out remainder);
if (result > 0)
returnString += new String('X', result);
value = (Byte) remainder;
// Get the fives digit.
result = Math.DivRem(value, 5, out remainder);
if (result > 0)
returnString += "V";
value = (Byte) remainder;
// Add the ones digit.
if (remainder > 0)
returnString += new String('I', remainder);
// Check whether we have too many X characters.
int pos = returnString.IndexOf("XXXX");
if (pos >= 0) {
int xPos = returnString.IndexOf("L");
if (xPos >= 0 & xPos == pos - 1)
returnString = returnString.Replace("LXXXX", "XC");
else
returnString = returnString.Replace("XXXX", "XL");
}
// Check whether we have too many I characters
pos = returnString.IndexOf("IIII");
if (pos >= 0)
if (returnString.IndexOf("V") >= 0)
returnString = returnString.Replace("VIIII", "IX");
else
returnString = returnString.Replace("IIII", "IV");
return returnString;
}
// Use default for all other formatting.
if (obj is IFormattable)
return ((IFormattable) obj).ToString(format, CultureInfo.CurrentCulture);
else
return obj.ToString();
}
}
public class Example
{
public static void Main()
{
int n = 10;
double value = 16.935;
DateTime day = DateTime.Now;
InterceptProvider provider = new InterceptProvider();
Console.WriteLine(String.Format(provider, "{0:N0}: {1:C2} on {2:d}\n", n, value, day));
Console.WriteLine(String.Format(provider, "{0}: {1:F}\n", "Today: ",
(DayOfWeek) DateTime.Now.DayOfWeek));
Console.WriteLine(String.Format(provider, "{0:X}, {1}, {2}\n",
(Byte) 2, (Byte) 12, (Byte) 199));
Console.WriteLine(String.Format(provider, "{0:R}, {1:R}, {2:R}\n",
(Byte) 2, (Byte) 12, (Byte) 199));
}
}
// The example displays the following output:
// Provider: InterceptProvider, Object: 10, Format String: N0
// Provider: InterceptProvider, Object: 16.935, Format String: C2
// Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d
// 10: $16.94 on 1/31/2013
//
// Provider: InterceptProvider, Object: Today: , Format String: <null>
// Provider: InterceptProvider, Object: Thursday, Format String: F
// Today: : Thursday
//
// Provider: InterceptProvider, Object: 2, Format String: X
// Provider: InterceptProvider, Object: 12, Format String: <null>
// Provider: InterceptProvider, Object: 199, Format String: <null>
// 2, 12, 199
//
// Provider: InterceptProvider, Object: 2, Format String: R
// Provider: InterceptProvider, Object: 12, Format String: R
// Provider: InterceptProvider, Object: 199, Format String: R
// II, XII, CXCIX
open System
open System.Globalization
type InterceptProvider() =
interface IFormatProvider with
member this.GetFormat(formatType) =
if formatType = typeof<ICustomFormatter> then
this
else
null
interface ICustomFormatter with
member _.Format(format, obj, provider: IFormatProvider) =
// Display information about method call.
let formatString =
if format = null then "<null>" else format
printfn $"Provider: {provider.GetType().Name}, Object: %A{obj}, Format String: %s{formatString}"
if obj = null then
String.Empty
else
// If this is a byte and the "R" format string, format it with Roman numerals.
match obj with
| :? byte as value when formatString.ToUpper().Equals "R" ->
let mutable returnString = String.Empty
// Get the hundreds digit(s)
let struct (result, remainder) = Math.DivRem(value, 100uy)
if result > 0uy then
returnString <- String('C', int result)
let value = byte remainder
// Get the 50s digit
let struct (result, remainder) = Math.DivRem(value, 50uy)
if result = 1uy then
returnString <- returnString + "L"
let value = byte remainder
// Get the tens digit.
let struct (result, remainder) = Math.DivRem(value, 10uy)
if result > 0uy then
returnString <- returnString + String('X', int result)
let value = byte remainder
// Get the fives digit.
let struct (result, remainder) = Math.DivRem(value, 5uy)
if result > 0uy then
returnString <- returnString + "V"
let value = byte remainder
// Add the ones digit.
if remainder > 0uy then
returnString <- returnString + String('I', int remainder)
// Check whether we have too many X characters.
let pos = returnString.IndexOf "XXXX"
if pos >= 0 then
let xPos = returnString.IndexOf "L"
returnString <-
if xPos >= 0 && xPos = pos - 1 then
returnString.Replace("LXXXX", "XC")
else
returnString.Replace("XXXX", "XL")
// Check whether we have too many I characters
let pos = returnString.IndexOf "IIII"
if pos >= 0 then
returnString <-
if returnString.IndexOf "V" >= 0 then
returnString.Replace("VIIII", "IX")
else
returnString.Replace("IIII", "IV")
returnString
// Use default for all other formatting.
| :? IFormattable as x ->
x.ToString(format, CultureInfo.CurrentCulture)
| _ ->
string obj
let n = 10
let value = 16.935
let day = DateTime.Now
let provider = InterceptProvider()
String.Format(provider, "{0:N0}: {1:C2} on {2:d}\n", n, value, day)
|> printfn "%s"
String.Format(provider, "{0}: {1:F}\n", "Today: ", DateTime.Now.DayOfWeek)
|> printfn "%s"
String.Format(provider, "{0:X}, {1}, {2}\n", 2uy, 12uy, 199uy)
|> printfn "%s"
String.Format(provider, "{0:R}, {1:R}, {2:R}\n", 2uy, 12uy, 199uy)
|> printfn "%s"
// The example displays the following output:
// Provider: InterceptProvider, Object: 10, Format String: N0
// Provider: InterceptProvider, Object: 16.935, Format String: C2
// Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d
// 10: $16.94 on 1/31/2013
//
// Provider: InterceptProvider, Object: Today: , Format String: <null>
// Provider: InterceptProvider, Object: Thursday, Format String: F
// Today: : Thursday
//
// Provider: InterceptProvider, Object: 2, Format String: X
// Provider: InterceptProvider, Object: 12, Format String: <null>
// Provider: InterceptProvider, Object: 199, Format String: <null>
// 2, 12, 199
//
// Provider: InterceptProvider, Object: 2, Format String: R
// Provider: InterceptProvider, Object: 12, Format String: R
// Provider: InterceptProvider, Object: 199, Format String: R
// II, XII, CXCIX
Imports System.Globalization
Public Class InterceptProvider : Implements IFormatProvider, ICustomFormatter
Public Function GetFormat(formatType As Type) As Object _
Implements IFormatProvider.GetFormat
If formatType Is GetType(ICustomFormatter) Then
Return Me
Else
Return Nothing
End If
End Function
Public Function Format(fmt As String, obj As Object, provider As IFormatProvider) As String _
Implements ICustomFormatter.Format
Dim formatString As String = If(fmt IsNot Nothing, fmt, "<null>")
Console.WriteLine("Provider: {0}, Object: {1}, Format String: {2}",
provider, If(obj IsNot Nothing, obj, "<null>"), formatString)
If obj Is Nothing Then Return String.Empty
' If this is a byte and the "R" format string, format it with Roman numerals.
If TypeOf(obj) Is Byte AndAlso formatString.ToUpper.Equals("R") Then
Dim value As Byte = CByte(obj)
Dim remainder As Integer
Dim result As Integer
Dim returnString As String = String.Empty
' Get the hundreds digit(s)
result = Math.DivRem(value, 100, remainder)
If result > 0 Then returnString = New String("C"c, result)
value = CByte(remainder)
' Get the 50s digit
result = Math.DivRem(value, 50, remainder)
If result = 1 Then returnString += "L"
value = CByte(remainder)
' Get the tens digit.
result = Math.DivRem(value, 10, remainder)
If result > 0 Then returnString += New String("X"c, result)
value = CByte(remainder)
' Get the fives digit.
result = Math.DivRem(value, 5, remainder)
If result > 0 Then returnString += "V"
value = CByte(remainder)
' Add the ones digit.
If remainder > 0 Then returnString += New String("I"c, remainder)
' Check whether we have too many X characters.
Dim pos As Integer = returnString.IndexOf("XXXX")
If pos >= 0 Then
Dim xPos As Integer = returnString.IndexOf("L")
If xPos >= 0 And xPos = pos - 1 Then
returnString = returnString.Replace("LXXXX", "XC")
Else
returnString = returnString.Replace("XXXX", "XL")
End If
End If
' Check whether we have too many I characters
pos = returnString.IndexOf("IIII")
If pos >= 0 Then
If returnString.IndexOf("V") >= 0 Then
returnString = returnString.Replace("VIIII", "IX")
Else
returnString = returnString.Replace("IIII", "IV")
End If
End If
Return returnString
End If
' Use default for all other formatting.
If obj Is GetType(IFormattable)
Return CType(obj, IFormattable).ToString(fmt, CultureInfo.CurrentCulture)
Else
Return obj.ToString()
End If
End Function
End Class
Module Example
Public Sub Main()
Dim n As Integer = 10
Dim value As Double = 16.935
Dim day As DateTime = Date.Now
Dim provider As New InterceptProvider()
Console.WriteLine(String.Format(provider, "{0:N0}: {1:C2} on {2:d}", n, value, day))
Console.WriteLine()
Console.WriteLine(String.Format(provider, "{0}: {1:F}", "Today",
CType(Date.Now.DayOfWeek, DayOfWeek)))
Console.WriteLine()
Console.WriteLine(String.Format(provider, "{0:X}, {1}, {2}\n",
CByte(2), CByte(12), CByte(199)))
Console.WriteLine()
Console.WriteLine(String.Format(provider, "{0:R}, {1:R}, {2:R}",
CByte(2), CByte(12), CByte(199)))
End Sub
End Module
' The example displays the following output:
' Provider: InterceptProvider, Object: 10, Format String: N0
' Provider: InterceptProvider, Object: 16.935, Format String: C2
' Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d
' 10: $16.94 on 1/31/2013
'
' Provider: InterceptProvider, Object: Today: , Format String: <null>
' Provider: InterceptProvider, Object: Thursday, Format String: F
' Today: : Thursday
'
' Provider: InterceptProvider, Object: 2, Format String: X
' Provider: InterceptProvider, Object: 12, Format String: <null>
' Provider: InterceptProvider, Object: 199, Format String: <null>
' 2, 12, 199
'
' Provider: InterceptProvider, Object: 2, Format String: R
' Provider: InterceptProvider, Object: 12, Format String: R
' Provider: InterceptProvider, Object: 199, Format String: R
' II, XII, CXCIX
String.Format Q & A
Why do you recommend string interpolation over calls to the String.Format method?
String interpolation is:
More flexible. It can be used in any string without requiring a call to a method that supports composite formatting. Otherwise, you have to call the Format method or another method that supports composite formatting, such as Console.WriteLine or StringBuilder.AppendFormat.
More readable. Because the expression to insert into a string appears in the interpolated expression rather than in a argument list, interpolated strings are far easier to code and to read. Because of their greater readability, interpolated strings can replace not only calls to composite format methods, but they can also be used in string concatenation operations to produce more concise, clearer code.
A comparison of the following two code examples illustrates the superiority of interpolated strings over string concatenation and calls to composite formatting methods. The use of multiple string concatenation operations in the following example produces verbose and hard-to-read code.
string[] names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" };
string output = names[0] + ", " + names[1] + ", " + names[2] + ", " +
names[3] + ", " + names[4] + ", " + names[5] + ", " +
names[6];
output += "\n";
var date = DateTime.Now;
output += String.Format("It is {0:t} on {0:d}. The day of the week is {1}.",
date, date.DayOfWeek);
Console.WriteLine(output);
// The example displays the following output:
// Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
// It is 10:29 AM on 1/8/2018. The day of the week is Monday.
open System
let names = [| "Balto"; "Vanya"; "Dakota"; "Samuel"; "Koani"; "Yiska"; "Yuma" |]
let output =
names[0] + ", " + names[1] + ", " + names[2] + ", " +
names[3] + ", " + names[4] + ", " + names[5] + ", " +
names[6] + "\n"
let date = DateTime.Now
output + String.Format("It is {0:t} on {0:d}. The day of the week is {1}.", date, date.DayOfWeek)
|> printfn "%s"
// The example displays the following output:
// Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
// It is 10:29 AM on 1/8/2018. The day of the week is Monday.
Module Example
Public Sub Main()
Dim names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" }
Dim output = names(0) + ", " + names(1) + ", " + names(2) + ", " +
names(3) + ", " + names(4) + ", " + names(5) + ", " +
names(6)
output += vbCrLf
Dim dat = DateTime.Now
output += String.Format("It is {0:t} on {0:d}. The day of the week is {1}.",
dat, dat.DayOfWeek)
Console.WriteLine(output)
End Sub
End Module
' The example displays the following output:
' Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
' It is 10:29 AM on 1/8/2018. The day of the week is Monday.
In contrast, the use of interpolated strings in the following example produce much clearer, more concise code than the string concatenation statement and the call to the Format method in the previous example.
string[] names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" };
string output = $"{names[0]}, {names[1]}, {names[2]}, {names[3]}, {names[4]}, " +
$"{names[5]}, {names[6]}";
var date = DateTime.Now;
output += $"\nIt is {date:t} on {date:d}. The day of the week is {date.DayOfWeek}.";
Console.WriteLine(output);
// The example displays the following output:
// Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
// It is 10:29 AM on 1/8/2018. The day of the week is Monday.
open System
let names = [| "Balto"; "Vanya"; "Dakota"; "Samuel"; "Koani"; "Yiska"; "Yuma" |]
let output = $"{names[0]}, {names[1]}, {names[2]}, {names[3]}, {names[4]}, {names[5]}, {names[6]}"
let date = DateTime.Now
output + $"\nIt is {date:t} on {date:d}. The day of the week is {date.DayOfWeek}."
|> printfn "%s"
// The example displays the following output:
// Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
// It is 10:29 AM on 1/8/2018. The day of the week is Monday.
Module Example
Public Sub Main()
Dim names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" }
Dim output = $"{names(0)}, {names(1)}, {names(2)}, {names(3)}, {names(4)}, " +
$"{names(5)}, {names(6)}"
Dim dat = DateTime.Now
output += $"{vbCrLf}It is {dat:t} on {dat:d}. The day of the week is {dat.DayOfWeek}."
Console.WriteLine(output)
End Sub
End Module
' The example displays the following output:
' Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
' It is 10:29 AM on 1/8/2018. The day of the week is Monday.
Where can I find a list of the predefined format strings that can be used with format items?
For all integral and floating-point types, see Standard Numeric Format Strings and Custom Numeric Format Strings.
For date and time values, see Standard Date and Time Format Strings and Custom Date and Time Format Strings.
For enumeration values, see Enumeration Format Strings.
For TimeSpan values, see Standard TimeSpan Format Strings and Custom TimeSpan Format Strings.
For Guid values, see the Remarks section of the Guid.ToString(String) reference page.
How do I control the alignment of the result strings that replace format items?
The general syntax of a format item is:
{index[,alignment][: formatString]}
where alignment is a signed integer that defines the field width. If this value is negative, text in the field is left-aligned. If it is positive, text is right-aligned.
How do I control the number of digits after the decimal separator?
All standard numeric format strings except "D" (which is used with integers only), "G", "R", and "X" allow a precision specifier that defines the number of decimal digits in the result string. The following example uses standard numeric format strings to control the number of decimal digits in the result string.
object[] values = { 1603, 1794.68235, 15436.14 };
string result;
foreach (var value in values) {
result = String.Format("{0,12:C2} {0,12:E3} {0,12:F4} {0,12:N3} {1,12:P2}\n",
Convert.ToDouble(value), Convert.ToDouble(value) / 10000);
Console.WriteLine(result);
}
// The example displays output like the following:
// $1,603.00 1.603E+003 1603.0000 1,603.000 16.03 %
//
// $1,794.68 1.795E+003 1794.6824 1,794.682 17.95 %
//
// $15,436.14 1.544E+004 15436.1400 15,436.140 154.36 %
open System
let values: obj list = [ 1603, 1794.68235, 15436.14 ]
for value in values do
String.Format("{0,12:C2} {0,12:E3} {0,12:F4} {0,12:N3} {1,12:P2}\n", Convert.ToDouble(value), Convert.ToDouble(value) / 10000.)
|> printfn "%s"
// The example displays output like the following:
// $1,603.00 1.603E+003 1603.0000 1,603.000 16.03 %
//
// $1,794.68 1.795E+003 1794.6824 1,794.682 17.95 %
//
// $15,436.14 1.544E+004 15436.1400 15,436.140 154.36 %
Module Example
Public Sub Main()
Dim values() As Object = { 1603, 1794.68235, 15436.14 }
Dim result As String
For Each value In values
result = String.Format("{0,12:C2} {0,12:E3} {0,12:F4} {0,12:N3} {1,12:P2}",
value, CDbl(value) / 10000)
Console.WriteLine(result)
Console.WriteLine()
Next
End Sub
End Module
' The example displays the following output:
' $1,603.00 1.603E+003 1603.0000 1,603.000 16.03 %
'
' $1,794.68 1.795E+003 1794.6824 1,794.682 17.95 %
'
' $15,436.14 1.544E+004 15436.1400 15,436.140 154.36 %
If you're using a custom numeric format string, use the "0" format specifier to control the number of decimal digits in the result string, as the following example shows.
decimal value = 16309.5436m;
string result = String.Format("{0,12:#.00000} {0,12:0,000.00} {0,12:000.00#}",
value);
Console.WriteLine(result);
// The example displays the following output:
// 16309.54360 16,309.54 16309.544
let value = 16309.5436m
String.Format("{0,12:#.00000} {0,12:0,000.00} {0,12:000.00#}", value)
|> printfn "%s"
// The example displays the following output:
// 16309.54360 16,309.54 16309.544
Module Example
Public Sub Main()
Dim value As Decimal = 16309.5436d
Dim result As String = String.Format("{0,12:#.00000} {0,12:0,000.00} {0,12:000.00#}",
value)
Console.WriteLine(result)
End Sub
End Module
' The example displays the following output:
' 16309.54360 16,309.54 16309.544
How do I control the number of integral digits?
By default, formatting operations only display non-zero integral digits. If you are formatting integers, you can use a precision specifier with the "D" and "X" standard format strings to control the number of digits.
int value = 1326;
string result = String.Format("{0,10:D6} {0,10:X8}", value);
Console.WriteLine(result);
// The example displays the following output:
// 001326 0000052E
open System
let value = 1326
String.Format("{0,10:D6} {0,10:X8}", value)
|> printfn "%s"
// The example displays the following output:
// 001326 0000052E
Module Example
Public Sub Main()
Dim value As Integer = 1326
Dim result As String = String.Format("{0,10:D6} {0,10:X8}", value)
Console.WriteLine(result)
End Sub
End Module
' The example displays the following output:
' 001326 0000052E
You can pad an integer or floating-point number with leading zeros to produce a result string with a specified number of integral digits by using the "0" custom numeric format specifier, as the following example shows.
int value = 16342;
string result = String.Format("{0,18:00000000} {0,18:00000000.000} {0,18:000,0000,000.0}",
value);
Console.WriteLine(result);
// The example displays the following output:
// 00016342 00016342.000 0,000,016,342.0
open System
let value = 16342
String.Format("{0,18:00000000} {0,18:00000000.000} {0,18:000,0000,000.0}", value)
|> printfn "%s"
// The example displays the following output:
// 00016342 00016342.000 0,000,016,342.0
Module Example
Public Sub Main()
Dim value As Integer = 16342
Dim result As String = String.Format("{0,18:00000000} {0,18:00000000.000} {0,18:000,0000,000.0}",
value)
Console.WriteLine(result)
End Sub
End Module
' The example displays the following output:
' 00016342 00016342.000 0,000,016,342.0
How many items can I include in the format list?
There is no practical limit. The second parameter of the Format(IFormatProvider, String, Object[]) method is tagged with the ParamArrayAttribute attribute, which allows you to include either a delimited list or an object array as your format list.
How do I include literal braces ("{" and "}") in the result string?
For example, how do you prevent the following method call from throwing a FormatException exception?
result = String.Format("The text has {0} '{' characters and {1} '}' characters.",
nOpen, nClose);
let result =
String.Format("The text has {0} '{' characters and {1} '}' characters.", nOpen, nClose)
result = String.Format("The text has {0} '{' characters and {1} '}' characters.",
nOpen, nClose)
A single opening or closing brace is always interpreted as the beginning or end of a format item. To be interpreted literally, it must be escaped. You escape a brace by adding another brace ("{{" and "}}" instead of "{" and "}"), as in the following method call:
string result;
int nOpen = 1;
int nClose = 2;
result = String.Format("The text has {0} '{{' characters and {1} '}}' characters.",
nOpen, nClose);
Console.WriteLine(result);
let result =
String.Format("The text has {0} '{{' characters and {1} '}}' characters.", nOpen, nClose)
result = String.Format("The text has {0} '{{' characters and {1} '}}' characters.",
nOpen, nClose)
However, even escaped braces are easily misinterpreted. We recommend that you include braces in the format list and use format items to insert them in the result string, as the following example shows.
string result;
int nOpen = 1;
int nClose = 2;
result = String.Format("The text has {0} '{1}' characters and {2} '{3}' characters.",
nOpen, "{", nClose, "}");
Console.WriteLine(result);
let result =
String.Format("The text has {0} '{1}' characters and {2} '{3}' characters.", nOpen, "{", nClose, "}")
result = String.Format("The text has {0} '{1}' characters and {2} '{3}' characters.",
nOpen, "{", nClose, "}")
Why does my call to the String.Format method throw a FormatException?
The most common cause of the exception is that the index of a format item doesn't correspond to an object in the format list. Usually this indicates that you've misnumbered the indexes of format items or you've forgotten to include an object in the format list. Attempting to include an unescaped left or right brace character also throws a FormatException. Occasionally, the exception is the result of a typo; for example, a typical mistake is to mistype "[" (the left bracket) instead of "{" (the left brace).
If the Format(System.IFormatProvider,System.String,System.Object[]) method supports parameter arrays, why does my code throw an exception when I use an array?
For example, the following code throws a FormatException exception:
Random rnd = new Random();
int[] numbers = new int[4];
int total = 0;
for (int ctr = 0; ctr <= 2; ctr++) {
int number = rnd.Next(1001);
numbers[ctr] = number;
total += number;
}
numbers[3] = total;
Console.WriteLine("{0} + {1} + {2} = {3}", numbers);
open System
let rnd = Random()
let mutable total = 0
let numbers = Array.zeroCreate<int> 4
for i = 0 to 2 do
let number = rnd.Next 1001
numbers[i] <- number
total <- total + number
numbers[3] <- total
Console.WriteLine("{0} + {1} + {2} = {3}", numbers)
Imports System.Collections.Generic
Module Example
Public Sub Main()
Dim rnd As New Random()
Dim numbers(3) As Integer
Dim total As Integer = 0
For ctr = 0 To 2
Dim number As Integer = rnd.Next(1001)
numbers(ctr) = number
total += number
Next
numbers(3) = total
Console.WriteLine("{0} + {1} + {2} = {3}", numbers)
End Sub
End Module
This is a problem of compiler overload resolution. Because the compiler cannot convert an array of integers to an object array, it treats the integer array as a single argument, so it calls the Format(String, Object) method. The exception is thrown because there are four format items but only a single item in the format list.
Because neither Visual Basic nor C# can convert an integer array to an object array, you have to perform the conversion yourself before calling the Format(String, Object[]) method. The following example provides one implementation.
Random rnd = new Random();
int[] numbers = new int[4];
int total = 0;
for (int ctr = 0; ctr <= 2; ctr++) {
int number = rnd.Next(1001);
numbers[ctr] = number;
total += number;
}
numbers[3] = total;
object[] values = new object[numbers.Length];
numbers.CopyTo(values, 0);
Console.WriteLine("{0} + {1} + {2} = {3}", values);
open System
let rnd = Random()
let numbers = Array.zeroCreate<int> 4
let mutable total = 0
for i = 0 to 2 do
let number = rnd.Next 1001
numbers[i] <- number
total <- total + number
numbers[3] <- total
let values = Array.zeroCreate<obj> numbers.Length
numbers.CopyTo(values, 0)
Console.WriteLine("{0} + {1} + {2} = {3}", values)
Imports System.Collections.Generic
Module Example
Public Sub Main()
Dim rnd As New Random()
Dim numbers(3) As Integer
Dim total As Integer = 0
For ctr = 0 To 2
Dim number As Integer = rnd.Next(1001)
numbers(ctr) = number
total += number
Next
numbers(3) = total
Dim values(numbers.Length - 1) As Object
numbers.CopyTo(values, 0)
Console.WriteLine("{0} + {1} + {2} = {3}", values)
End Sub
End Module
Format(IFormatProvider, String, Object, Object, Object)
Replaces the format items in a string with the string representation of three specified objects. An parameter supplies culture-specific formatting information.
public:
static System::String ^ Format(IFormatProvider ^ provider, System::String ^ format, System::Object ^ arg0, System::Object ^ arg1, System::Object ^ arg2);public static string Format (IFormatProvider provider, string format, object arg0, object arg1, object arg2);public static string Format (IFormatProvider? provider, string format, object? arg0, object? arg1, object? arg2);static member Format : IFormatProvider * string * obj * obj * obj -> stringPublic Shared Function Format (provider As IFormatProvider, format As String, arg0 As Object, arg1 As Object, arg2 As Object) As StringParameters
- provider
- IFormatProvider
An object that supplies culture-specific formatting information.
- format
- String
- arg0
- Object
The first object to format.
- arg1
- Object
The second object to format.
- arg2
- Object
The third object to format.
Returns
A copy of format in which the format items have been replaced by the string representations of arg0, arg1, and arg2.
Exceptions
format is null.
format is invalid.
-or-
The index of a format item is less than zero, or greater than two.
Remarks
Important
Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).
This method uses the composite formatting feature to convert three expressions to their string representations and to embed those representations in a string. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. The method converts each Object argument to its string representation by calling its ToString(IFormatProvider) method or, if the object's corresponding format item includes a format string, by calling its ToString(String,IFormatProvider) method. If these methods don't exist, it calls the object's parameterless ToString method.
However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Instead, you can call the method with an object that provides culture-sensitive or custom formatting and a composite format string that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. Your language compiler will then resolve your method call to a particular overload of the String.Format method.
For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.
Applies to
Format(String, Object, Object, Object)
Replaces the format items in a string with the string representation of three specified objects.
public:
static System::String ^ Format(System::String ^ format, System::Object ^ arg0, System::Object ^ arg1, System::Object ^ arg2);public static string Format (string format, object arg0, object arg1, object arg2);public static string Format (string format, object? arg0, object? arg1, object? arg2);static member Format : string * obj * obj * obj -> stringPublic Shared Function Format (format As String, arg0 As Object, arg1 As Object, arg2 As Object) As StringParameters
- format
- String
- arg0
- Object
The first object to format.
- arg1
- Object
The second object to format.
- arg2
- Object
The third object to format.
Returns
A copy of format in which the format items have been replaced by the string representations of arg0, arg1, and arg2.
Exceptions
format is null.
format is invalid.
-or-
The index of a format item is less than zero, or greater than two.
Remarks
Important
Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).
This method uses the composite formatting feature to convert the value of three expressions to their string representations and to embed those representations in a string.
However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Instead, you can call the method with a composite format string that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. Your language compiler will then resolve your method call to a particular overload of the String.Format method.
For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.
Example: Format three arguments
This example uses the Format(String, Object, Object, Object) method to create a string that illustrates the result of a Boolean And operation with two integer values. Note that the format string includes six format items, but the method has only three items in its parameter list, because each item is formatted in two different ways.
using namespace System;
void main()
{
String^ formatString = " {0,10} ({0,8:X8})\n" +
"And {1,10} ({1,8:X8})\n" +
" = {2,10} ({2,8:X8})";
int value1 = 16932;
int value2 = 15421;
String^ result = String::Format(formatString,
value1, value2, value1 & value2);
Console::WriteLine(result);
}
// The example displays the following output:
// 16932 (00004224)
// And 15421 (00003C3D)
// = 36 (00000024)
string formatString = " {0,10} ({0,8:X8})\n" +
"And {1,10} ({1,8:X8})\n" +
" = {2,10} ({2,8:X8})";
int value1 = 16932;
int value2 = 15421;
string result = String.Format(formatString,
value1, value2, value1 & value2);
Console.WriteLine(result);
// The example displays the following output:
// 16932 (00004224)
// And 15421 (00003C3D)
// = 36 (00000024)
open System
let formatString =
" {0,10} ({0,8:X8})\nAnd {1,10} ({1,8:X8})\n = {2,10} ({2,8:X8})"
let value1 = 16932
let value2 = 15421
String.Format(formatString, value1, value2, value1 &&& value2)
|> printfn "%s"
// The example displays the following output:
// 16932 (00004224)
// And 15421 (00003C3D)
// = 36 (00000024)
Public Module Example
Public Sub Main()
Dim formatString As String = " {0,10} ({0,8:X8})" + vbCrLf + _
"And {1,10} ({1,8:X8})" + vbCrLf + _
" = {2,10} ({2,8:X8})"
Dim value1 As Integer = 16932
Dim value2 As Integer = 15421
Dim result As String = String.Format(formatString, _
value1, value2, value1 And value2)
Console.WriteLine(result)
End Sub
End Module
' The example displays the following output:
' 16932 (00004224)
' And 15421 (00003C3D)
' = 36 (00000024)
See also
Applies to
Format(IFormatProvider, String, Object, Object)
Replaces the format items in a string with the string representation of two specified objects. A parameter supplies culture-specific formatting information.
public:
static System::String ^ Format(IFormatProvider ^ provider, System::String ^ format, System::Object ^ arg0, System::Object ^ arg1);public static string Format (IFormatProvider provider, string format, object arg0, object arg1);public static string Format (IFormatProvider? provider, string format, object? arg0, object? arg1);static member Format : IFormatProvider * string * obj * obj -> stringPublic Shared Function Format (provider As IFormatProvider, format As String, arg0 As Object, arg1 As Object) As StringParameters
- provider
- IFormatProvider
An object that supplies culture-specific formatting information.
- format
- String
- arg0
- Object
The first object to format.
- arg1
- Object
The second object to format.
Returns
A copy of format in which format items are replaced by the string representations of arg0 and arg1.
Exceptions
format is null.
Remarks
Important
Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).
This method uses the composite formatting feature to convert two expressions to their string representations and to embed those representations in a string. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. The method converts each Object argument to its string representation by calling its ToString(IFormatProvider) method or, if the object's corresponding format item includes a format string, by calling its ToString(String,IFormatProvider) method. If these methods don't exist, it calls the object's parameterless ToString method.
However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Instead, you can call the method with an object that provides culture-sensitive or custom formatting and a composite format string that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. Your language compiler will then resolve your method call to a particular overload of the String.Format method.
For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.
Applies to
Format(String, Object, Object)
Replaces the format items in a string with the string representation of two specified objects.
public:
static System::String ^ Format(System::String ^ format, System::Object ^ arg0, System::Object ^ arg1);public static string Format (string format, object arg0, object arg1);public static string Format (string format, object? arg0, object? arg1);static member Format : string * obj * obj -> stringPublic Shared Function Format (format As String, arg0 As Object, arg1 As Object) As StringParameters
- format
- String
- arg0
- Object
The first object to format.
- arg1
- Object
The second object to format.
Returns
A copy of format in which format items are replaced by the string representations of arg0 and arg1.
Exceptions
format is null.
Remarks
Important
Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).
This method uses the composite formatting feature to convert the value of two expressions to their string representations and to embed those representations in a string.
However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Instead, you can call the method with a composite format string that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. Your language compiler will then resolve your method call to a particular overload of the String.Format method.
For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.
Example: Format two arguments
This example uses the Format(String, Object, Object) method to display time and temperature data stored in a generic Dictionary<TKey,TValue> object. Note that the format string has three format items, although there are only two objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date.
using namespace System;
using namespace System::Collections::Generic;
void main()
{
Dictionary<DateTime, Double>^ temperatureInfo = gcnew Dictionary<DateTime, Double>();
temperatureInfo->Add(DateTime(2010, 6, 1, 14, 0, 0), 87.46);
temperatureInfo->Add(DateTime(2010, 12, 1, 10, 0, 0), 36.81);
Console::WriteLine("Temperature Information:\n");
String^ output;
for each (KeyValuePair<DateTime, Double>^ item in temperatureInfo)
{
output = String::Format("Temperature at {0,8:t} on {0,9:d}: {1,5:N1}�F",
item->Key, item->Value);
Console::WriteLine(output);
}
}
// The example displays the following output:
// Temperature Information:
//
// Temperature at 2:00 PM on 6/1/2010: 87.5�F
// Temperature at 10:00 AM on 12/1/2010: 36.8�F
Dictionary<DateTime, Double> temperatureInfo = new Dictionary<DateTime, Double>();
temperatureInfo.Add(new DateTime(2010, 6, 1, 14, 0, 0), 87.46);
temperatureInfo.Add(new DateTime(2010, 12, 1, 10, 0, 0), 36.81);
Console.WriteLine("Temperature Information:\n");
string output;
foreach (var item in temperatureInfo)
{
output = String.Format("Temperature at {0,8:t} on {0,9:d}: {1,5:N1}°F",
item.Key, item.Value);
Console.WriteLine(output);
}
// The example displays output like the following:
// Temperature Information:
//
// Temperature at 2:00 PM on 6/1/2010: 87.5°F
// Temperature at 10:00 AM on 12/1/2010: 36.8°F
open System
open System.Collections.Generic
let temperatureInfo = Dictionary<DateTime, float>()
temperatureInfo.Add(DateTime(2010, 6, 1, 14, 0, 0), 87.46)
temperatureInfo.Add(DateTime(2010, 12, 1, 10, 0, 0), 36.81)
printfn $"Temperature Information:\n"
for item in temperatureInfo do
String.Format("Temperature at {0,8:t} on {0,9:d}: {1,5:N1}°F", item.Key, item.Value)
|> printfn "%s"
// The example displays output like the following:
// Temperature Information:
//
// Temperature at 2:00 PM on 6/1/2010: 87.5°F
// Temperature at 10:00 AM on 12/1/2010: 36.8°F
Imports System.Collections.Generic
Module Example
Public Sub Main()
Dim temperatureInfo As New Dictionary(Of Date, Double)
temperatureInfo.Add(#6/1/2010 2:00PM#, 87.46)
temperatureInfo.Add(#12/1/2010 10:00AM#, 36.81)
Console.WriteLine("Temperature Information:")
Console.WriteLine()
Dim output As String
For Each item In temperatureInfo
output = String.Format("Temperature at {0,8:t} on {0,9:d}: {1,5:N1}°F", _
item.Key, item.Value)
Console.WriteLine(output)
Next
End Sub
End Module
' The example displays the following output:
' Temperature Information:
'
' Temperature at 2:00 PM on 6/1/2010: 87.5°F
' Temperature at 10:00 AM on 12/1/2010: 36.8°F
See also
- Formatting Types in .NET
- Composite Formatting
- Standard Date and Time Format Strings
- Custom Date and Time Format Strings
- Standard Numeric Format Strings
- Custom Numeric Format Strings
- Standard TimeSpan Format Strings
- Custom TimeSpan Format Strings
- Enumeration Format Strings
Applies to
Format(IFormatProvider, CompositeFormat, ReadOnlySpan<Object>)
Replaces the format item or items in a CompositeFormat with the string representation of the corresponding objects in the specified format.
public:
static System::String ^ Format(IFormatProvider ^ provider, System::Text::CompositeFormat ^ format, ReadOnlySpan<System::Object ^> args);public static string Format (IFormatProvider? provider, System.Text.CompositeFormat format, ReadOnlySpan<object?> args);static member Format : IFormatProvider * System.Text.CompositeFormat * ReadOnlySpan<obj> -> stringPublic Shared Function Format (provider As IFormatProvider, format As CompositeFormat, args As ReadOnlySpan(Of Object)) As StringParameters
- provider
- IFormatProvider
An object that supplies culture-specific formatting information.
- format
- CompositeFormat
- args
- ReadOnlySpan<Object>
A span of objects to format.
Returns
The formatted string.
Exceptions
format is null.
The index of a format item is greater than or equal to the number of supplied arguments.
Applies to
Format(IFormatProvider, String, Object)
Replaces the format item or items in a specified string with the string representation of the corresponding object. A parameter supplies culture-specific formatting information.
public:
static System::String ^ Format(IFormatProvider ^ provider, System::String ^ format, System::Object ^ arg0);public static string Format (IFormatProvider provider, string format, object arg0);public static string Format (IFormatProvider? provider, string format, object? arg0);static member Format : IFormatProvider * string * obj -> stringPublic Shared Function Format (provider As IFormatProvider, format As String, arg0 As Object) As StringParameters
- provider
- IFormatProvider
An object that supplies culture-specific formatting information.
- format
- String
- arg0
- Object
The object to format.
Returns
A copy of format in which the format item or items have been replaced by the string representation of arg0.
Exceptions
format is null.
Remarks
Important
Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).
This method uses the composite formatting feature to convert the value of an expression to its string representation and to embed that representation in a string. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. The method converts arg0 to its string representation by calling its ToString(IFormatProvider) method or, if the object's corresponding format item includes a format string, by calling its ToString(String,IFormatProvider) method. If these methods don't exist, it calls the object's parameterless ToString method.
However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Instead, you can call the method with an object that provides culture-sensitive or custom formatting and a composite format string that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. Your language compiler will then resolve your method call to a particular overload of the String.Format method.
For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.
Applies to
Format(IFormatProvider, String, Object[])
Replaces the format items in a string with the string representations of corresponding objects in a specified array. A parameter supplies culture-specific formatting information.
public:
static System::String ^ Format(IFormatProvider ^ provider, System::String ^ format, ... cli::array <System::Object ^> ^ args);public static string Format (IFormatProvider provider, string format, params object[] args);public static string Format (IFormatProvider? provider, string format, params object?[] args);static member Format : IFormatProvider * string * obj[] -> stringPublic Shared Function Format (provider As IFormatProvider, format As String, ParamArray args As Object()) As StringParameters
- provider
- IFormatProvider
An object that supplies culture-specific formatting information.
- format
- String
- args
- Object[]
An object array that contains zero or more objects to format.
Returns
A copy of format in which the format items have been replaced by the string representation of the corresponding objects in args.
Exceptions
format or args is null.
format is invalid.
-or-
The index of a format item is less than zero, or greater than or equal to the length of the args array.
Remarks
Important
Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).
This method uses the composite formatting feature to convert four or more expressions to their string representations and to embed those representations in a string. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. The method converts each Object argument to its string representation by calling its ToString(IFormatProvider) method or, if the object's corresponding format item includes a format string, by calling its ToString(String,IFormatProvider) method. If these methods don't exist, it calls the object's parameterless ToString method.
However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Instead, you can call the method with an object that provides culture-sensitive or custom formatting and a composite format string that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. Your language compiler will then resolve your method call to a particular overload of the String.Format method.
For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.
Example: Culture-sensitive formatting
This example uses the Format(IFormatProvider, String, Object[]) method to display the string representation of some date and time values and numeric values by using several different cultures.
string[] cultureNames = { "en-US", "fr-FR", "de-DE", "es-ES" };
DateTime dateToDisplay = new DateTime(2009, 9, 1, 18, 32, 0);
double value = 9164.32;
Console.WriteLine("Culture Date Value\n");
foreach (string cultureName in cultureNames)
{
System.Globalization.CultureInfo culture = new System.Globalization.CultureInfo(cultureName);
string output = String.Format(culture, "{0,-11} {1,-35:D} {2:N}",
culture.Name, dateToDisplay, value);
Console.WriteLine(output);
}
// The example displays the following output:
// Culture Date Value
//
// en-US Tuesday, September 01, 2009 9,164.32
// fr-FR mardi 1 septembre 2009 9 164,32
// de-DE Dienstag, 1. September 2009 9.164,32
// es-ES martes, 01 de septiembre de 2009 9.164,32
open System
open System.Globalization
let cultureNames = [| "en-US"; "fr-FR"; "de-DE"; "es-ES" |]
let dateToDisplay = DateTime(2009, 9, 1, 18, 32, 0)
let value = 9164.32
printfn "Culture Date Value\n"
for cultureName in cultureNames do
let culture = CultureInfo cultureName
String.Format(culture, "{0,-11} {1,-35:D} {2:N}", culture.Name, dateToDisplay, value)
|> printfn "%s"
// The example displays the following output:
// Culture Date Value
//
// en-US Tuesday, September 01, 2009 9,164.32
// fr-FR mardi 1 septembre 2009 9 164,32
// de-DE Dienstag, 1. September 2009 9.164,32
// es-ES martes, 01 de septiembre de 2009 9.164,32
Imports System.Globalization
Module Example
Public Sub Main()
Dim cultureNames() As String = { "en-US", "fr-FR", "de-DE", "es-ES" }
Dim dateToDisplay As Date = #9/1/2009 6:32PM#
Dim value As Double = 9164.32
Console.WriteLine("Culture Date Value")
Console.WriteLine()
For Each cultureName As String In cultureNames
Dim culture As New CultureInfo(cultureName)
Dim output As String = String.Format(culture, "{0,-11} {1,-35:D} {2:N}", _
culture.Name, dateToDisplay, value)
Console.WriteLine(output)
Next
End Sub
End Module
' The example displays the following output:
' Culture Date Value
'
' en-US Tuesday, September 01, 2009 9,164.32
' fr-FR mardi 1 septembre 2009 9 164,32
' de-DE Dienstag, 1. September 2009 9.164,32
' es-ES martes, 01 de septiembre de 2009 9.164,32
See also
- DateTimeFormatInfo
- ICustomFormatter
- IFormatProvider
- NumberFormatInfo
- Formatting Types in .NET
- Composite Formatting
- Standard Date and Time Format Strings
- Custom Date and Time Format Strings
- Standard Numeric Format Strings
- Custom Numeric Format Strings
- Standard TimeSpan Format Strings
- Custom TimeSpan Format Strings
- Enumeration Format Strings
Applies to
Format(String, Object[])
Replaces the format item in a specified string with the string representation of a corresponding object in a specified array.
public:
static System::String ^ Format(System::String ^ format, ... cli::array <System::Object ^> ^ args);public static string Format (string format, params object[] args);public static string Format (string format, params object?[] args);static member Format : string * obj[] -> stringPublic Shared Function Format (format As String, ParamArray args As Object()) As StringParameters
- format
- String
- args
- Object[]
An object array that contains zero or more objects to format.
Returns
A copy of format in which the format items have been replaced by the string representation of the corresponding objects in args.
Exceptions
format or args is null.
format is invalid.
-or-
The index of a format item is less than zero, or greater than or equal to the length of the args array.
Remarks
Important
Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).
This method uses the composite formatting feature to convert the value of four or more expressions to their string representations and to embed those representations in a string. Since the args parameter is marked with the System.ParamArrayAttribute attribute, you can pass the objects to the method as individual arguments or as an Object array.
However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Instead, you can call the method with a composite format string that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. Your language compiler will then resolve your method call to a particular overload of the String.Format method.
For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.
Example: Format more than three arguments
This example creates a string that contains data on the high and low temperature on a particular date. The composite format string has five format items in the C# example and six in the Visual Basic example. Two of the format items define the width of their corresponding value's string representation, and the first format item also includes a standard date and time format string.
using namespace System;
void main()
{
DateTime date1 = DateTime(2009, 7, 1);
TimeSpan hiTime = TimeSpan(14, 17, 32);
Decimal hiTemp = (Decimal) 62.1;
TimeSpan loTime = TimeSpan(3, 16, 10);
Decimal loTemp = (Decimal)54.8;
String^ result1 = String::Format("Temperature on {0:d}:\n{1,11}: {2} degrees (hi)\n{3,11}: {4} degrees (lo)",
date1, hiTime, hiTemp, loTime, loTemp);
Console::WriteLine(result1);
Console::WriteLine();
String^ result2 = String::Format("Temperature on {0:d}:\n{1,11}: {2} degrees (hi)\n{3,11}: {4} degrees (lo)",
gcnew array<Object^> { date1, hiTime, hiTemp, loTime, loTemp });
Console::WriteLine(result2);
}
// The example displays the following output:
// Temperature on 7/1/2009:
// 14:17:32: 62.1 degrees (hi)
// 03:16:10: 54.8 degrees (lo)
// Temperature on 7/1/2009:
// 14:17:32: 62.1 degrees (hi)
// 03:16:10: 54.8 degrees (lo)
DateTime date1 = new DateTime(2009, 7, 1);
TimeSpan hiTime = new TimeSpan(14, 17, 32);
decimal hiTemp = 62.1m;
TimeSpan loTime = new TimeSpan(3, 16, 10);
decimal loTemp = 54.8m;
string result1 = String.Format("Temperature on {0:d}:\n{1,11}: {2} degrees (hi)\n{3,11}: {4} degrees (lo)",
date1, hiTime, hiTemp, loTime, loTemp);
Console.WriteLine(result1);
Console.WriteLine();
string result2 = String.Format("Temperature on {0:d}:\n{1,11}: {2} degrees (hi)\n{3,11}: {4} degrees (lo)",
new object[] { date1, hiTime, hiTemp, loTime, loTemp });
Console.WriteLine(result2);
// The example displays output like the following:
// Temperature on 7/1/2009:
// 14:17:32: 62.1 degrees (hi)
// 03:16:10: 54.8 degrees (lo)
// Temperature on 7/1/2009:
// 14:17:32: 62.1 degrees (hi)
// 03:16:10: 54.8 degrees (lo)
let date1 = DateTime(2009, 7, 1)
let hiTime = TimeSpan(14, 17, 32)
let hiTemp = 62.1m
let loTime = TimeSpan(3, 16, 10)
let loTemp = 54.8m
String.Format("Temperature on {0:d}:\n{1,11}: {2} degrees (hi)\n{3,11}: {4} degrees (lo)", date1, hiTime, hiTemp, loTime, loTemp)
|> printfn "%s\n"
String.Format("Temperature on {0:d}:\n{1,11}: {2} degrees (hi)\n{3,11}: {4} degrees (lo)", [| date1 :> obj; hiTime; hiTemp; loTime; loTemp |])
|> printfn "%s"
// The example displays output like the following:
// Temperature on 7/1/2009:
// 14:17:32: 62.1 degrees (hi)
// 03:16:10: 54.8 degrees (lo)
// Temperature on 7/1/2009:
// 14:17:32: 62.1 degrees (hi)
// 03:16:10: 54.8 degrees (lo)
Module Example
Public Sub Main()
Dim date1 As Date = #7/1/2009#
Dim hiTime As New TimeSpan(14, 17, 32)
Dim hiTemp As Decimal = 62.1d
Dim loTime As New TimeSpan(3, 16, 10)
Dim loTemp As Decimal = 54.8d
Dim result1 As String = String.Format("Temperature on {0:d}:{5}{1,11}: {2} degrees (hi){5}{3,11}: {4} degrees (lo)", _
date1, hiTime, hiTemp, loTime, loTemp, vbCrLf)
Console.WriteLine(result1)
Console.WriteLine()
Dim result2 As String = String.Format("Temperature on {0:d}:{5}{1,11}: {2} degrees (hi){5}{3,11}: {4} degrees (lo)", _
New Object() { date1, hiTime, hiTemp, loTime, loTemp, vbCrLf })
Console.WriteLine(result2)
End Sub
End Module
' The example displays the following output:
' Temperature on 7/1/2009:
' 14:17:32: 62.1 degrees (hi)
' 03:16:10: 54.8 degrees (lo)
'
' Temperature on 7/1/2009:
' 14:17:32: 62.1 degrees (hi)
' 03:16:10: 54.8 degrees (lo)
You can also pass the objects to be formatted as an array rather than as an argument list.
using namespace System;
ref class CityInfo
{
public:
CityInfo(String^ name, int population, Decimal area, int year)
{
this->Name = name;
this->Population = population;
this->Area = area;
this->Year = year;
}
String^ Name;
int Population;
Decimal Area;
int Year;
};
ref class Example
{
public:
static void ShowPopulationData(CityInfo^ city)
{
array<Object^>^ args = gcnew array<Object^> { city->Name, city->Year, city->Population, city->Area };
String^ result = String::Format("{0} in {1}: Population {2:N0}, Area {3:N1} sq. feet",
args);
Console::WriteLine(result);
}
};
void main()
{
CityInfo^ nyc2010 = gcnew CityInfo("New York", 8175133, (Decimal) 302.64, 2010);
Example::ShowPopulationData(nyc2010);
CityInfo^ sea2010 = gcnew CityInfo("Seattle", 608660, (Decimal) 83.94, 2010);
Example::ShowPopulationData(sea2010);
}
// The example displays the following output:
// New York in 2010: Population 8,175,133, Area 302.6 sq. feet
// Seattle in 2010: Population 608,660, Area 83.9 sq. feet
using System;
public class CityInfo
{
public CityInfo(String name, int population, Decimal area, int year)
{
this.Name = name;
this.Population = population;
this.Area = area;
this.Year = year;
}
public readonly String Name;
public readonly int Population;
public readonly Decimal Area;
public readonly int Year;
}
public class Example
{
public static void Main()
{
CityInfo nyc2010 = new CityInfo("New York", 8175133, 302.64m, 2010);
ShowPopulationData(nyc2010);
CityInfo sea2010 = new CityInfo("Seattle", 608660, 83.94m, 2010);
ShowPopulationData(sea2010);
}
private static void ShowPopulationData(CityInfo city)
{
object[] args = { city.Name, city.Year, city.Population, city.Area };
String result = String.Format("{0} in {1}: Population {2:N0}, Area {3:N1} sq. feet",
args);
Console.WriteLine(result);
}
}
// The example displays the following output:
// New York in 2010: Population 8,175,133, Area 302.6 sq. feet
// Seattle in 2010: Population 608,660, Area 83.9 sq. feet
open System
type CityInfo =
{ Name: string
Population: int
Area: Decimal
Year: int }
let showPopulationData city =
let args: obj[] = [| city.Name; city.Year; city.Population; city.Area |]
String.Format("{0} in {1}: Population {2:N0}, Area {3:N1} sq. feet", args)
|> printfn "%s"
{ Name = "New York"; Population = 8175133; Area = 302.64m; Year = 2010 }
|> showPopulationData
{ Name = "Seattle"; Population = 608660; Area = 83.94m; Year = 2010 }
|> showPopulationData
// The example displays the following output:
// New York in 2010: Population 8,175,133, Area 302.6 sq. feet
// Seattle in 2010: Population 608,660, Area 83.9 sq. feet
Public Class CityInfo
Public Sub New(name As String, population As Integer, area As Decimal, year As Integer)
Me.Name = name
Me.Population = population
Me.Area = area
Me.Year = year
End Sub
Public ReadOnly Name As String
Public ReadOnly Population As Integer
Public ReadOnly Area As Decimal
Public ReadOnly Year As Integer
End Class
Module Example
Public Sub Main()
Dim nyc2010 As New CityInfo("New York", 8175133, 302.64d, 2010)
ShowPopulationData(nyc2010)
Dim sea2010 As New CityInfo("Seattle", 608660, 83.94d, 2010)
ShowPopulationData(sea2010)
End Sub
Private Sub ShowPopulationData(city As CityInfo)
Dim args() As Object = { city.Name, city.Year, city.Population, city.Area }
Dim result = String.Format("{0} in {1}: Population {2:N0}, Area {3:N1} sq. feet", args)
Console.WriteLine(result)
End Sub
End Module
' The example displays the following output:
' New York in 2010: Population 8,175,133, Area 302.6 sq. feet
' Seattle in 2010: Population 608,660, Area 83.9 sq. feet
See also
- Formatting Types in .NET
- Composite Formatting
- Standard Date and Time Format Strings
- Custom Date and Time Format Strings
- Standard Numeric Format Strings
- Custom Numeric Format Strings
- Standard TimeSpan Format Strings
- Custom TimeSpan Format Strings
- Enumeration Format Strings
Applies to
Format(String, Object)
Replaces one or more format items in a string with the string representation of a specified object.
public:
static System::String ^ Format(System::String ^ format, System::Object ^ arg0);public static string Format (string format, object arg0);public static string Format (string format, object? arg0);static member Format : string * obj -> stringPublic Shared Function Format (format As String, arg0 As Object) As StringParameters
- format
- String
- arg0
- Object
The object to format.
Returns
A copy of format in which any format items are replaced by the string representation of arg0.
Exceptions
format is null.
Remarks
Important
Instead of calling the String.Format method or using composite format strings, you can use interpolated strings if your language supports them. An interpolated string is a string that contains interpolated expressions. Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. For more information, see String interpolation (C# Reference) and Interpolated Strings (Visual Basic Reference).
This method uses the composite formatting feature to convert the value of an expression to its string representation and to embed that representation in a string.
However, when calling the String.Format method, it is not necessary to focus on the particular overload that you want to call. Instead, you can call the method with a composite format string that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. Your language compiler will then resolve your method call to a particular overload of the String.Format method.
For more detailed documentation on using the String.Format method, see Getting started with the String.Format method and Which method do I call?.
Example: Formatting a single argument
The following example uses the Format(String, Object) method to embed an individual's age in the middle of a string.
using namespace System;
void main()
{
DateTime birthdate = DateTime(1993, 7, 28);
array<DateTime>^ dates = gcnew array<DateTime> { DateTime(1993, 8, 16),
DateTime(1994, 7, 28),
DateTime(2000, 10, 16),
DateTime(2003, 7, 27),
DateTime(2007, 5, 27) };
for each (DateTime dateValue in dates)
{
TimeSpan interval = dateValue - birthdate;
// Get the approximate number of years, without accounting for leap years.
int years = ((int)interval.TotalDays) / 365;
// See if adding the number of years exceeds dateValue.
String^ output;
if (birthdate.AddYears(years) <= dateValue) {
output = String::Format("You are now {0} years old.", years);
Console::WriteLine(output);
}
else {
output = String::Format("You are now {0} years old.", years - 1);
Console::WriteLine(output);
}
}
}
// The example displays the following output:
// You are now 0 years old.
// You are now 1 years old.
// You are now 7 years old.
// You are now 9 years old.
// You are now 13 years old.
DateTime birthdate = new DateTime(1993, 7, 28);
DateTime[] dates = { new DateTime(1993, 8, 16),
new DateTime(1994, 7, 28),
new DateTime(2000, 10, 16),
new DateTime(2003, 7, 27),
new DateTime(2007, 5, 27) };
foreach (DateTime dateValue in dates)
{
TimeSpan interval = dateValue - birthdate;
// Get the approximate number of years, without accounting for leap years.
int years = ((int) interval.TotalDays) / 365;
// See if adding the number of years exceeds dateValue.
string output;
if (birthdate.AddYears(years) <= dateValue) {
output = String.Format("You are now {0} years old.", years);
Console.WriteLine(output);
}
else {
output = String.Format("You are now {0} years old.", years - 1);
Console.WriteLine(output);
}
}
// The example displays the following output:
// You are now 0 years old.
// You are now 1 years old.
// You are now 7 years old.
// You are now 9 years old.
// You are now 13 years old.
let birthdate = DateTime(1993, 7, 28)
let dates =
[ DateTime(1993, 8, 16)
DateTime(1994, 7, 28)
DateTime(2000, 10, 16)
DateTime(2003, 7, 27)
DateTime(2007, 5, 27) ]
for dateValue in dates do
let interval = dateValue - birthdate
// Get the approximate number of years, without accounting for leap years.
let years = (int interval.TotalDays) / 365
// See if adding the number of years exceeds dateValue.
if birthdate.AddYears years <= dateValue then
String.Format("You are now {0} years old.", years)
else
String.Format("You are now {0} years old.", years - 1)
|> printfn "%s"
// The example displays the following output:
// You are now 0 years old.
// You are now 1 years old.
// You are now 7 years old.
// You are now 9 years old.
// You are now 13 years old.
Module Example
Public Sub Main()
Dim birthdate As Date = #7/28/1993#
Dim dates() As Date = { #9/16/1993#, #7/28/1994#, #10/16/2000#, _
#7/27/2003#, #5/27/2007# }
For Each dateValue As Date In dates
Dim interval As TimeSpan = dateValue - birthdate
' Get the approximate number of years, without accounting for leap years.
Dim years As Integer = CInt(interval.TotalDays) \ 365
' See if adding the number of years exceeds dateValue.
Dim output As String
If birthdate.AddYears(years) <= dateValue Then
output = String.Format("You are now {0} years old.", years)
Console.WriteLine(output)
Else
output = String.Format("You are now {0} years old.", years - 1)
Console.WriteLine(output)
End If
Next
End Sub
End Module
' The example displays the following output:
' You are now 0 years old.
' You are now 1 years old.
' You are now 7 years old.
' You are now 9 years old.
' You are now 13 years old.
See also
- Formatting Types in .NET
- Composite Formatting
- Standard Date and Time Format Strings
- Custom Date and Time Format Strings
- Standard Numeric Format Strings
- Custom Numeric Format Strings
- Standard TimeSpan Format Strings
- Custom TimeSpan Format Strings
- Enumeration Format Strings
Applies to
Format(IFormatProvider, CompositeFormat, Object[])
Replaces the format item or items in a CompositeFormat with the string representation of the corresponding objects in the specified format.
public:
static System::String ^ Format(IFormatProvider ^ provider, System::Text::CompositeFormat ^ format, ... cli::array <System::Object ^> ^ args);public static string Format (IFormatProvider? provider, System.Text.CompositeFormat format, params object?[] args);static member Format : IFormatProvider * System.Text.CompositeFormat * obj[] -> stringPublic Shared Function Format (provider As IFormatProvider, format As CompositeFormat, ParamArray args As Object()) As StringParameters
- provider
- IFormatProvider
An object that supplies culture-specific formatting information.
- format
- CompositeFormat
- args
- Object[]
An array of objects to format.
Returns
The formatted string.
Exceptions
format or args is null.
The index of a format item is greater than or equal to the number of supplied arguments.
Applies to
Format<TArg0,TArg1,TArg2>(IFormatProvider, CompositeFormat, TArg0, TArg1, TArg2)
Replaces the format item or items in a CompositeFormat with the string representation of the corresponding objects in the specified format.
public:
generic <typename TArg0, typename TArg1, typename TArg2>
static System::String ^ Format(IFormatProvider ^ provider, System::Text::CompositeFormat ^ format, TArg0 arg0, TArg1 arg1, TArg2 arg2);public static string Format<TArg0,TArg1,TArg2> (IFormatProvider? provider, System.Text.CompositeFormat format, TArg0 arg0, TArg1 arg1, TArg2 arg2);static member Format : IFormatProvider * System.Text.CompositeFormat * 'TArg0 * 'TArg1 * 'TArg2 -> stringPublic Shared Function Format(Of TArg0, TArg1, TArg2) (provider As IFormatProvider, format As CompositeFormat, arg0 As TArg0, arg1 As TArg1, arg2 As TArg2) As StringType Parameters
- TArg0
The type of the first object to format.
- TArg1
The type of the second object to format.
- TArg2
The type of the third object to format.
Parameters
- provider
- IFormatProvider
An object that supplies culture-specific formatting information.
- format
- CompositeFormat
- arg0
- TArg0
The first object to format.
- arg1
- TArg1
The second object to format.
- arg2
- TArg2
The third object to format.
Returns
The formatted string.
Exceptions
format is null.
The index of a format item is greater than or equal to the number of supplied arguments.
Applies to
Format<TArg0,TArg1>(IFormatProvider, CompositeFormat, TArg0, TArg1)
Replaces the format item or items in a CompositeFormat with the string representation of the corresponding objects in the specified format.
public:
generic <typename TArg0, typename TArg1>
static System::String ^ Format(IFormatProvider ^ provider, System::Text::CompositeFormat ^ format, TArg0 arg0, TArg1 arg1);public static string Format<TArg0,TArg1> (IFormatProvider? provider, System.Text.CompositeFormat format, TArg0 arg0, TArg1 arg1);static member Format : IFormatProvider * System.Text.CompositeFormat * 'TArg0 * 'TArg1 -> stringPublic Shared Function Format(Of TArg0, TArg1) (provider As IFormatProvider, format As CompositeFormat, arg0 As TArg0, arg1 As TArg1) As StringType Parameters
- TArg0
The type of the first object to format.
- TArg1
The type of the second object to format.
Parameters
- provider
- IFormatProvider
An object that supplies culture-specific formatting information.
- format
- CompositeFormat
- arg0
- TArg0
The first object to format.
- arg1
- TArg1
The second object to format.
Returns
The formatted string.
Exceptions
format is null.
The index of a format item is greater than or equal to the number of supplied arguments.
Applies to
Format<TArg0>(IFormatProvider, CompositeFormat, TArg0)
Replaces the format item or items in a CompositeFormat with the string representation of the corresponding objects in the specified format.
public:
generic <typename TArg0>
static System::String ^ Format(IFormatProvider ^ provider, System::Text::CompositeFormat ^ format, TArg0 arg0);public static string Format<TArg0> (IFormatProvider? provider, System.Text.CompositeFormat format, TArg0 arg0);static member Format : IFormatProvider * System.Text.CompositeFormat * 'TArg0 -> stringPublic Shared Function Format(Of TArg0) (provider As IFormatProvider, format As CompositeFormat, arg0 As TArg0) As StringType Parameters
- TArg0
The type of the first object to format.
Parameters
- provider
- IFormatProvider
An object that supplies culture-specific formatting information.
- format
- CompositeFormat
- arg0
- TArg0
The first object to format.
Returns
The formatted string.
Exceptions
format is null.
The index of a format item is greater than or equal to the number of supplied arguments.
Applies to
Feedback
Submit and view feedback for