String.Format Method (String, Object[]) (System)

Switch View

Format Method (String, Object[])

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.NET Framework Class Library

String..::.Format Method (String, array<Object>[]()[])

Updated: May 2009

Replaces the format item in a specified string with the string representation of a corresponding object in a specified array.

Namespace: System
Assembly: mscorlib (in mscorlib.dll)

Syntax

Visual Basic (Declaration)

Public Shared Function Format ( _
    format As String, _
    ParamArray args As Object() _
) As String

Visual Basic (Usage)

Dim format As String
Dim args As Object()
Dim returnValue As String

returnValue = String.Format(format, _
    args)

public static string Format(
    string format,
    params Object[] args
)

Visual C++

public:
static String^ Format(
    String^ format, 
    ... array<Object^>^ args
)

JScript

public static function Format(
    format : String, 
    ... args : Object[]
) : String

Parameters

format: Type: System..::.String
A composite format string.

args: Type: array<System..::.Object>[]()[]
An object array that contains zero or more objects to format.

Return Value

Type: System..::.String
A copy of format in which the format items have been replaced by the string representation of the corresponding objects in args.

Exceptions

Exception	Condition
ArgumentNullException	format or args is nullNothingnullptra null reference (Nothing in Visual Basic).
FormatException	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.

Exception

Condition

ArgumentNullException

format or args is nullNothingnullptra null reference (Nothing in Visual Basic).

FormatException

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 of the .NET Framework to convert the value of an object to its text representation and embed that representation in a string. The .NET Framework provides extensive formatting support, which is described in greater detail in the following formatting topics.

For more information about the composite formatting feature supported by methods such as Format, AppendFormat, and some overloads of WriteLine, see Composite Formatting.
For more information about numeric format specifiers, see Standard Numeric Format Strings and Custom Numeric Format Strings.
For more information about date and time format specifiers, see Standard Date and Time Format Strings and Custom Date and Time Format Strings.
For more information about enumeration format specifiers, see Enumeration Format Strings.
For more information about formatting, see Formatting Types and Formatting Overview.

The format parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to an object in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object.

The syntax of a format item is as follows:

{index[,length][:formatString]}

Elements in square brackets are optional. The following table describes each element.

Element	Description
index	The zero-based position in the parameter list of the object to be formatted. If the object specified by index is nullNothingnullptra null reference (Nothing in Visual Basic), the format item is replaced by String..::.Empty. If there is no parameter in the index position, a FormatException is thrown.
,length	The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.
:formatString	A standard or custom format string that is supported by the parameter.

Note:
For the standard and custom format strings used with date and time values, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. For the standard and custom format strings used with numeric values, see Standard Numeric Format Strings and Custom Numeric Format Strings. For the standard format strings used with enumerations, see Enumeration Format Strings.

The leading and trailing brace characters, '{' and '}', are required. To specify a single literal brace character in format, specify two leading or trailing brace characters; that is, "{{" or "}}".

If the value of format is, "Thank you for your purchase of {0:####} copies of Microsoft®.NET (Core Reference).", and arg[0] is an Int16 with the value 123, then the return value will be:

"Thank you for your purchase of 123 copies of Microsoft®.NET (Core Reference)."

If the value of format is, "Brad's dog has {0,-8:G} fleas.", arg[0]is an Int16 with the value 42, (and in this example, underscores represent padding spaces) then the return value will be:

"Brad's dog has 42______ fleas."

Examples

The following example demonstrates the standard formatting specifiers for numbers, dates, and enumerations. In this example, formatting is based on the conventions of the current culture, which, in this case, is the en-US culture.

Visual Basic

Public Enum Color
   Yellow = 1
   Blue = 2
   Green = 3
End Enum 

Public Module Example
   Private thisDate As DateTime = #06/30/2009 7:14PM#

   Public Sub Main()
      ' Store the output of the String.Format method in a string.
      Dim s As String = ""

      ' Format a negative integer or floating-point number in various ways.
      Console.WriteLine("Standard Numeric Format Strings")
      s = String.Format( _
                        "(C) Currency: . . . . . . . . {0:C}" & vbCrLf & _
                        "(D) Decimal:. . . . . . . . . {0:D}" & vbCrLf & _
                        "(E) Scientific: . . . . . . . {1:E}" & vbCrLf & _
                        "(F) Fixed point:. . . . . . . {1:F}" & vbCrLf & _
                        "(G) General:. . . . . . . . . {0:G}" & vbCrLf & _
                        "    (default):. . . . . . . . {0} (default = 'G')" & vbCrLf & _
                        "(N) Number: . . . . . . . . . {0:N}" & vbCrLf & _
                        "(P) Percent:. . . . . . . . . {1:P}" & vbCrLf & _
                        "(R) Round-trip: . . . . . . . {3:R}" & vbCrLf & _
                        "(X) Hexadecimal:. . . . . . . {0:X}" & vbCrLf, _
                        -123, -123.45, -.126, -1.5322980781265591)
      Console.WriteLine(s)

      ' Format a date in various ways.
      Console.WriteLine("Standard Date and Time Format Strings")
      s = String.Format( _
                        "(d) Short date: . . . . . . . {0:d}" & vbCrLf & _
                        "(D) Long date:. . . . . . . . {0:D}" & vbCrLf & _
                        "(t) Short time: . . . . . . . {0:t}" & vbCrLf & _
                        "(T) Long time:. . . . . . . . {0:T}" & vbCrLf & _
                        "(f) Full date/short time: . . {0:f}" & vbCrLf & _
                        "(F) Full date/long time:. . . {0:F}" & vbCrLf & _
                        "(g) General date/short time:. {0:g}" & vbCrLf & _
                        "(G) General date/long time: . {0:G}" & vbCrLf & _
                        "    (default):. . . . . . . . {0} (default = 'G')" & vbCrLf & _
                        "(M) Month:. . . . . . . . . . {0:M}" & vbCrLf & _
                        "(R) RFC1123:. . . . . . . . . {0:R}" & vbCrLf & _
                        "(s) Sortable: . . . . . . . . {0:s}" & vbCrLf & _
                        "(u) Universal sortable: . . . {0:u} (invariant)" & vbCrLf & _
                        "(U) Universal full: . . . . . {0:U}" & vbCrLf & _
                        "(Y) Year: . . . . . . . . . . {0:Y}" & vbCrLf, _
                        thisDate)
      Console.WriteLine(s)

      ' Format an enumeration value in various ways.
      Console.WriteLine("Standard Enumeration Format Specifiers")
      s = String.Format( _
                        "(G) General:. . . . . . . . . {0:G}" & vbCrLf & _
                        "    (default):. . . . . . . . {0} (default = 'G')" & vbCrLf & _
                        "(F) Flags:. . . . . . . . . . {1:F}" & vbCrLf & _
                        "(D) Decimal number: . . . . . {0:D}" & vbCrLf & _
                        "(X) Hexadecimal:. . . . . . . {0:X}" & vbCrLf, _
                        Color.Green, AttributeTargets.Class Or AttributeTargets.Struct)
      Console.WriteLine(s)
   End Sub 
End Module 
' The example displays the following output:
'    Standard Numeric Format Specifiers
'    (C) Currency: . . . . . . . . ($123.00)
'    (D) Decimal:. . . . . . . . . -123
'    (E) Scientific: . . . . . . . -1.234500E+002
'    (F) Fixed point:. . . . . . . -123.45
'    (G) General:. . . . . . . . . -123
'        (default):. . . . . . . . -123 (default = 'G')
'    (N) Number: . . . . . . . . . -123.00
'    (P) Percent:. . . . . . . . . -12,345.00 %
'    (R) Round-trip: . . . . . . . -123.45
'    (X) Hexadecimal:. . . . . . . FFFFFF85
'    
'    Standard DateTime Format Specifiers
'    (d) Short date: . . . . . . . 6/30/2009
'    (D) Long date:. . . . . . . . Tuesday, June 30, 2009
'    (t) Short time: . . . . . . . 7:14 PM
'    (T) Long time:. . . . . . . . 7:14:00 PM
'    (f) Full date/short time: . . Tuesday, June 30, 2009 7:14 PM
'    (F) Full date/long time:. . . Tuesday, June 30, 2009 7:14:00 PM
'    (g) General date/short time:. 6/30/2009 7:14 PM
'    (G) General date/long time: . 6/30/2009 7:14:00 PM
'        (default):. . . . . . . . 6/30/2009 7:14:00 PM (default = 'G')
'    (M) Month:. . . . . . . . . . June 30
'    (R) RFC1123:. . . . . . . . . Tue, 30 Jun 2009 19:14:00 GMT
'    (s) Sortable: . . . . . . . . 2009-06-30T19:14:00
'    (u) Universal sortable: . . . 2009-06-30 19:14:00Z (invariant)
'    (U) Universal full: . . . . . Wednesday, July 01, 2009 2:14:00 AM
'    (Y) Year: . . . . . . . . . . June, 2009
'    
'    Standard Enumeration Format Specifiers
'    (G) General:. . . . . . . . . Green
'        (default):. . . . . . . . Green (default = 'G')
'    (F) Flags:. . . . . . . . . . Class, Struct
'    (D) Decimal number: . . . . . 3
'    (X) Hexadecimal:. . . . . . . 00000003

using System;

public enum Color {Yellow = 1, Blue, Green};

class Example
{
   static DateTime thisDate = new DateTime(2009, 6, 30, 19, 14, 0);

   public static void Main() 
   {
      // Store the output of the String.Format method in a string.
      string s = "";

      // Format a negative integer or floating-point number in various ways.
      Console.WriteLine("Standard Numeric Format Strings");
      s = String.Format( 
          "(C) Currency: . . . . . . . . {0:C}\n" +
          "(D) Decimal:. . . . . . . . . {0:D}\n" +
          "(E) Scientific: . . . . . . . {1:E}\n" +
          "(F) Fixed point:. . . . . . . {1:F}\n" +
          "(G) General:. . . . . . . . . {0:G}\n" +
          "    (default):. . . . . . . . {0} (default = 'G')\n" +
          "(N) Number: . . . . . . . . . {0:N}\n" +
          "(P) Percent:. . . . . . . . . {2:P}\n" +
          "(R) Round-trip: . . . . . . . {3:R}\n" +
          "(X) Hexadecimal:. . . . . . . {0:X}\n",
          -123, -123.45, -.126, -1.5322980781265591); 
      Console.WriteLine(s);

      // Format a date in various ways.
      Console.WriteLine("Standard Date and Time Format Strings");
      s = String.Format(  
          "(d) Short date: . . . . . . . {0:d}\n" +
          "(D) Long date:. . . . . . . . {0:D}\n" +
          "(t) Short time: . . . . . . . {0:t}\n" +
          "(T) Long time:. . . . . . . . {0:T}\n" +
          "(f) Full date/short time: . . {0:f}\n" +
          "(F) Full date/long time:. . . {0:F}\n" +
          "(g) General date/short time:. {0:g}\n" +
          "(G) General date/long time: . {0:G}\n" +
          "    (default):. . . . . . . . {0} (default = 'G')\n" +
          "(M) Month:. . . . . . . . . . {0:M}\n" +
          "(R) RFC1123:. . . . . . . . . {0:R}\n" +
          "(s) Sortable: . . . . . . . . {0:s}\n" +
          "(u) Universal sortable: . . . {0:u} (invariant)\n" +
          "(U) Universal full: . . . . . {0:U}\n" +
          "(Y) Year: . . . . . . . . . . {0:Y}\n", 
          thisDate);
      Console.WriteLine(s);

      // Format an enumeration value in various ways.
      Console.WriteLine("Standard Enumeration Format Specifiers");
      s = String.Format(
          "(G) General:. . . . . . . . . {0:G}\n" +
          "    (default):. . . . . . . . {0} (default = 'G')\n" +
          "(F) Flags:. . . . . . . . . . {1:F}\n" +
          "(D) Decimal number: . . . . . {0:D}\n" +
          "(X) Hexadecimal:. . . . . . . {0:X}\n", 
          Color.Green, AttributeTargets.Class | AttributeTargets.Struct);       
      Console.WriteLine(s);
   }
}
// The example displays the following output:
//    Standard Numeric Format Specifiers
//    (C) Currency: . . . . . . . . (�123.00)
//    (D) Decimal:. . . . . . . . . -123
//    (E) Scientific: . . . . . . . -1.234500E+002
//    (F) Fixed point:. . . . . . . -123.45
//    (G) General:. . . . . . . . . -123
//        (default):. . . . . . . . -123 (default = 'G')
//    (N) Number: . . . . . . . . . -123.00
//    (P) Percent:. . . . . . . . . -12,345.00 %
//    (R) Round-trip: . . . . . . . -123.45
//    (X) Hexadecimal:. . . . . . . FFFFFF85
//    
//    Standard DateTime Format Specifiers
//    (d) Short date: . . . . . . . 07/09/2007
//    (D) Long date:. . . . . . . . Monday, 09 July 2007
//    (t) Short time: . . . . . . . 13:48
//    (T) Long time:. . . . . . . . 13:48:05
//    (f) Full date/short time: . . Monday, 09 July 2007 13:48
//    (F) Full date/long time:. . . Monday, 09 July 2007 13:48:05
//    (g) General date/short time:. 07/09/2007 13:48
//    (G) General date/long time: . 07/09/2007 13:48:05
//        (default):. . . . . . . . 07/09/2007 13:48:05 (default = 'G')
//    (M) Month:. . . . . . . . . . July 09
//    (R) RFC1123:. . . . . . . . . Mon, 09 Jul 2007 13:48:05 GMT
//    (s) Sortable: . . . . . . . . 2007-07-09T13:48:05
//    (u) Universal sortable: . . . 2007-07-09 13:48:05Z (invariant)
//    (U) Universal full: . . . . . Monday, 09 July 2007 20:48:05
//    (Y) Year: . . . . . . . . . . 2007 July
//    
//    Standard Enumeration Format Specifiers
//    (G) General:. . . . . . . . . Green
//        (default):. . . . . . . . Green (default = 'G')
//    (F) Flags:. . . . . . . . . . Green (flags or integer)
//    (D) Decimal number: . . . . . 3
//    (X) Hexadecimal:. . . . . . . 00000003

Platforms

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0

Reference

Other Resources

Formatting Overview

Formatting Types

Composite Formatting

Change History

Date	History	Reason
May 2009	Replaced the example.	Customer feedback.
October 2008	Expanded the Remarks section.	Customer feedback.

Date

History

Reason

May 2009

Replaced the example.

Customer feedback.

October 2008

Expanded the Remarks section.

Customer feedback.

The ParamArray Attribute and the Method Call

Note that the ParamArray attribute is applied to the args parameter. (See http://msdn.microsoft.com/en-us/library/system.paramarrayattribute.aspx for documentation on the ParamArrayAttribute class.) This means that the arguments can be specified to the method in either of two forms: either as a comma-delimited list of values, or as an array. So both

str = String.Format("Her name is {0} and she's {1} years old", args);

and

str = String.Format("Her name is {0} and she's {1} years old", args[0], args[1]);

as well as

string name;
int age;
str = String.Format("Her name is {0} and she's {1} years old", name, age);

all compile and execute successfully.