StringBuilder::AppendFormat Method (IFormatProvider^, String^, Object^, Object^)
Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of two arguments using a specified format provider.
Assembly: mscorlib (in mscorlib.dll)
public:
StringBuilder^ AppendFormat(
IFormatProvider^ provider,
String^ format,
Object^ arg0,
Object^ arg1
)
Parameters
- provider
-
Type:
System::IFormatProvider^
An object that supplies culture-specific formatting information.
- format
-
Type:
System::String^
A composite format string (see Remarks).
- arg0
-
Type:
System::Object^
The first object to format.
- arg1
-
Type:
System::Object^
The second object to format.
Return Value
Type: System.Text::StringBuilder^A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of format where any format specification is replaced by the string representation of the corresponding object argument.
| Exception | Condition |
|---|---|
| ArgumentNullException | format is null. |
| FormatException | format is invalid. -or- The index of a format item is less than 0 (zero), or greater than or equal to 2 (two). |
| ArgumentOutOfRangeException | The length of the expanded string would exceed MaxCapacity. |
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 the current StringBuilder object.
The format parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects 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 null, 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 provider parameter specifies an IFormatProvider implementation that can provide formatting information for arg0 and arg1. provider can be any of the following:
A CultureInfo object that provides culture-specific formatting information.
A NumberFormatInfo object that provides culture-specific formatting information for arg0 or arg1 if they are numeric values.
A DateTimeFormatInfo object that provides culture-specific formatting information for arg0 or arg1 if they are date and time values.
A custom IFormatProvider implementation that provides formatting information for arg0 and arg1. Typically, such an implementation also implements the ICustomFormatter interface.
If the provider parameter is null, format provider information is obtained from the current culture.
arg0 and arg1 represent the objects to be formatted. Each format item in format is replaced with the string representation of the object that has the corresponding index. If the format item includes formatString and the corresponding argument implements the IFormattable interface, then the argument's ToString(formatString, provider) method defines the formatting. Otherwise, the argument's ToString() method defines the formatting.
Notes to Callers:
In the.NET Framework 4 and the .NET Framework 4.5, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) constructor, both the length and the capacity of the StringBuilder instance can grow beyond the value of its MaxCapacity property. This can occur particularly when you call the Append and AppendFormat methods to append small strings.
The following example uses the AppendFormat(IFormatProvider^, String^, Object^, Object^) method to display time and temperature data stored in a generic Dictionary<TKey, TValue> object. Note that the format string has three format items, although there are only to objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date.
Available since 10
.NET Framework
Available since 4.6
AppendFormat Overload
StringBuilder Class
System.Text Namespace
Formatting Types in the .NET Framework
Composite Formatting
How to: Define and Use Custom Numeric Format Providers
Standard Numeric Format Strings
Custom Numeric Format Strings
Standard Date and Time Format Strings
Custom Date and Time Format Strings
Standard TimeSpan Format Strings
Custom TimeSpan Format Strings
Enumeration Format Strings
