Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

StringBuilder.AppendFormat Method (String, Object)

.NET Framework 1.1

Appends a formatted string, which contains zero or more format specifications, to this instance. Each format specification is replaced by the string representation of a corresponding object argument.

[Visual Basic]
Overloads Public Function AppendFormat( _
   ByVal format As String, _
   ByVal arg0 As Object _
) As StringBuilder
[C#]
public StringBuilder AppendFormat(
 string format,
 object arg0
);
[C++]
public: StringBuilder* AppendFormat(
 String* format,
 Object* arg0
);
[JScript]
public function AppendFormat(
   format : String,
 arg0 : Object
) : StringBuilder;

Parameters

format
A string containing zero or more format specifications.
arg0
An object to format.

Return Value

A reference to this instance with format appended. Any format specification in format is replaced by the string representation of the corresponding object argument.

Exceptions

Exception Type Condition
ArgumentNullException format is a null reference (Nothing in Visual Basic).
FormatException format is invalid.
ArgumentOutOfRangeException Enlarging the value of this instance would exceed MaxCapacity.

Remarks

This method replaces zero or more format specifications with the appropriately formatted value of an object. The format specifications are embedded within a string and are of the form {N:FormatString}, where N is a zero-based number indicating the argument to format and FormatString is a format string. If arg0 implements IFormattable then arg0.Format (format, null) provides the formatting; otherwise ToString provides the formatting. If arg0 is a null reference (Nothing in Visual Basic) then an empty string is used in its place.

To Pad With Spaces: You can define a region within the string argument in which the formatted value can be left or right justified. The format specification has an optional integer field: {N[,M]:FormatString}. The magnitude of M indicates the minimum number of spaces for the region and the sign of M indicates whether the value should be left (negative values) or right (positive values) justified within the region.

ToString is Used if the Format String is Omitted: The format string within a format specification is optional: {N[,M][:FormatString]}. When FormatString is omitted, the ToString method of the argument specified by N is used to replace the format specification. If M is given, then the result of ToString is padded with spaces as described above.

If the string assigned to 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 string assigned to format is "Brad's dog has {0,-8:G} fleas." and arg0 is an Int16 with the value 42, then the return value (where underscores represent padding spaces) will be "Brad's dog has 42______ fleas."

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, Common Language Infrastructure (CLI) Standard

See Also

StringBuilder Class | StringBuilder Members | System.Text Namespace | StringBuilder.AppendFormat Overload List | Formatting Overview

Show:
© 2015 Microsoft