String.Format Method (System) (original) (raw)
Source:
Source:
Source:
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
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 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
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's 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. The 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 Get 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