Export (0) Print
Expand All

String.Format Method (String, Object[])

.NET Framework 1.1

Replaces the format item in a specified String with the text equivalent of the value of a corresponding Object instance in a specified array.

[Visual Basic]
Overloads Public Shared Function Format( _
   ByVal format As String, _
   ByVal ParamArray args() As Object _
) As String
[C#]
public static string Format(
 string format,
   params object[] args
);
[C++]
public: static String* Format(
 String* format,
 Object* args __gc[]
);
[JScript]
public static function Format(
   format : String,
 args : Object[]
) : String;

Parameters

format
A String containing zero or more format items.
args
An Object array containing zero or more objects to format.

Return Value

A copy of format in which the format items have been replaced by the String equivalent of the corresponding instances of Object in args.

Exceptions

Exception Type Condition
ArgumentNullException format or args is a null reference (Nothing in Visual Basic).
FormatException format is invalid.

-or-

The number indicating an argument to format is less than zero, or greater than or equal to the length of the args array.

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 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."

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 Language Filter 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

Show:
© 2014 Microsoft