String.Format Method (String, Object)
Replaces the format item in a specified String with the text equivalent of the value of a specified Object instance.
[Visual Basic] Overloads Public Shared Function Format( _ ByVal format As String, _ ByVal arg0 As Object _ ) As String [C#] public static string Format( string format, object arg0 ); [C++] public: static String* Format( String* format, Object* arg0 ); [JScript] public static function Format( format : String, arg0 : Object ) : String;
Parameters
Return Value
A copy of format in which the first format item has been replaced by the String equivalent of arg0.
Exceptions
| Exception Type | Condition |
|---|---|
| ArgumentNullException | format is a null reference (Nothing in Visual Basic). |
| FormatException | The format item in format is invalid.
-or- The number indicating an argument to format is less than zero, or greater than or equal to the number of specified objects to format. |
Remarks
For more information about formatting, see Formatting Types and Formatting Overview. For more information about the composite formatting feature supported by Format, see Composite Formatting.
The format parameter is embedded with zero or more format items of the form, {index[,alignment][:formatString]}, where:
- index
- A zero-based integer that indicates which element in a list of objects to format. If the object specified by index is a null reference (Nothing in Visual Basic), then the format item is replaced by the empty string ("").
- alignment
- An optional integer indicating the minimum width of the region to contain the formatted value. If the length of the formatted value is less than alignment, then the region is padded with spaces. If alignment is negative, the formatted value is left justified in the region; if alignment is positive, the formatted value is right justified. If alignment is not specified, the length of the region is the length of the formatted value. The comma is required if alignment is specified.
- formatString
- An optional string of formatting codes. If formatString is not specified and the corresponding argument implements the IFormattable interface, then a null reference (Nothing) is used as the IFormattable.ToString format string. Therefore, all implementations of IFormattable.ToString are required to allow a null reference (Nothing) as a format string, and return default formatting of the object representation as a String. The colon is required if formatString is specified.
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 arg0 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.", arg0 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."
Example
[Visual Basic, C#, C++] The following example demonstrates formatting multiple values.
[Visual Basic] <Serializable()> Public Class LogicalCallContextData Implements ILogicalThreadAffinative Private _nAccesses As Integer Private _principal As IPrincipal Public ReadOnly Property numOfAccesses() As String Get Return [String].Format("The identity of {0} has been accessed {1} times.", _principal.Identity.Name, _nAccesses) End Get End Property Public ReadOnly Property Principal() As IPrincipal Get _nAccesses += 1 Return _principal End Get End Property Public Sub New(p As IPrincipal) _nAccesses = 0 _principal = p End Sub 'New End Class 'LogicalCallContextData [C#] [Serializable] public class LogicalCallContextData : ILogicalThreadAffinative { int _nAccesses; IPrincipal _principal; public string numOfAccesses { get { return String.Format("The identity of {0} has been accessed {1} times.", _principal.Identity.Name, _nAccesses); } } public IPrincipal Principal { get { _nAccesses ++; return _principal; } } public LogicalCallContextData(IPrincipal p) { _nAccesses = 0; _principal = p; } } [C++] [Serializable] public __gc class LogicalCallContextData : public ILogicalThreadAffinative { int _nAccesses; IPrincipal* _principal; public: __property String* get_numOfAccesses() { return String::Format(S"The identity of {0} has been accessed {1} times.", _principal->Identity->Name, __box(_nAccesses)); } public: __property IPrincipal* get_Principal() { _nAccesses ++; return _principal; } public: LogicalCallContextData(IPrincipal* p) { _nAccesses = 0; _principal = p; } };
[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button
in the upper-left corner of the page.
Requirements
Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework, Common Language Infrastructure (CLI) Standard
See Also
String Class | String Members | System Namespace | String.Format Overload List | Object | Formatting Overview | Formatting Types