Windows apps
Collapse the table of content
Expand the table of content
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

StringBuilder::AppendFormat Method (IFormatProvider^, String^, Object^)

.NET Framework (current version)
 

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 a single argument using a specified format provider.

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

public:
StringBuilder^ AppendFormat(
	IFormatProvider^ provider,
	String^ format,
	Object^ arg0
)

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 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 in which any format specification is replaced by the string representation of arg0.

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 one (1).

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 arg0 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. The index of each format item must be zero (0) since this method includes an argument list with a single argument. The formatting process replaces each format item with the string representation of arg0.

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. In this case, since the AppendFormat(IFormatProvider^, String^, Object^) method has a single argument in the argument list, the value of index must always be 0. If it is not, 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.

System_CAPS_noteNote

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 the objects in args. 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 if it is a numeric value.

  • A DateTimeFormatInfo object that provides culture-specific formatting information for arg0 if it is a date and time value.

  • A custom IFormatProvider implementation that provides formatting information for arg0. Typically, such an implementation also implements the ICustomFormatter interface.

If the provider parameter is null, formatting information is obtained from the current culture.

arg0 represents the object to be formatted. Each format item in format is replaced with the string representation of arg0. If the format item includes formatString and arg0 implements the IFormattable interface, then arg0.ToString(formatString, provider) defines the formatting. Otherwise, arg0.ToString() 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 includes two calls to the AppendFormat(IFormatProvider^, String^, Object^) method. Both use the formatting conventions of the English-Great Britain (en-GB) culture. The first inserts the string representation of a Decimal value currency in a result string. The second inserts a DateTime value in two places in a result string, the first including only the short date string and the second the short time string.

No code example is currently available or this language may not be supported.

Universal Windows Platform
Available since 10
.NET Framework
Available since 4.6
Return to top
Show:
© 2017 Microsoft