Updated: January 2012
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 three arguments.
Assembly: mscorlib (in mscorlib.dll)
Public Function AppendFormat ( _ format As String, _ arg0 As Object, _ arg1 As Object, _ arg2 As Object _ ) As StringBuilder
public StringBuilder AppendFormat( string format, Object arg0, Object arg1, Object arg2 )
public:
StringBuilder^ AppendFormat(
String^ format,
Object^ arg0,
Object^ arg1,
Object^ arg2
)
member AppendFormat : format:string * arg0:Object * arg1:Object * arg2:Object -> StringBuilder
Parameters
- 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.
- arg2
- Type: System.Object
The third object to format.
Return Value
Type: System.Text.StringBuilderA reference to this instance with format appended. Each format item in format 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 3. |
| 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 arg0 through arg3, the 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. |
arg0, arg1, and arg2 represent the objects to be formatted. Each format item in format is replaced with the string representation of either arg0, arg1, or arg2, depending on the index of the format item. If the format item includes formatString and the corresponding object in args implements the IFormattable interface, then argx.ToString(formatString, null) defines the formatting, where x is the index of the argument. Otherwise, argx.ToString() defines the formatting.
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, 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, the return value (where underscores represent padding spaces) will be "Brad's dog has 42______ fleas."
Notes to Callers
In the .NET Framework 4, when you instantiate the StringBuilder object by calling the StringBuilder 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 demonstrates the AppendFormat method.
Imports System Imports System.Text Imports System.Globalization Class Sample Private Shared sb As New StringBuilder() Public Shared Sub Main() Dim var1 As Integer = 111 Dim var2 As Single = 2.22F Dim var3 As String = "abcd" Dim var4 As Object() = {3, 4.4, "X"c} Console.WriteLine() Console.WriteLine("StringBuilder.AppendFormat method:") sb.AppendFormat("1) {0}", var1) Show(sb) sb.AppendFormat("2) {0}, {1}", var1, var2) Show(sb) sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3) Show(sb) sb.AppendFormat("4) {0}, {1}, {2}", var4) Show(sb) Dim ci As New CultureInfo("es-ES", True) sb.AppendFormat(ci, "5) {0}", var2) Show(sb) End Sub 'Main Public Shared Sub Show(sbs As StringBuilder) Console.WriteLine(sbs.ToString()) sb.Length = 0 End Sub 'Show End Class 'Sample ' 'This example produces the following results: ' 'StringBuilder.AppendFormat method: '1) 111 '2) 111, 2.22 '3) 111, 2.22, abcd '4) 3, 4.4, X '5) 2,22
using System; using System.Text; using System.Globalization; class Sample { static StringBuilder sb = new StringBuilder(); public static void Main() { int var1 = 111; float var2 = 2.22F; string var3 = "abcd"; object[] var4 = {3, 4.4, 'X'}; Console.WriteLine(); Console.WriteLine("StringBuilder.AppendFormat method:"); sb.AppendFormat("1) {0}", var1); Show(sb); sb.AppendFormat("2) {0}, {1}", var1, var2); Show(sb); sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3); Show(sb); sb.AppendFormat("4) {0}, {1}, {2}", var4); Show(sb); CultureInfo ci = new CultureInfo("es-ES", true); sb.AppendFormat(ci, "5) {0}", var2); Show(sb); } public static void Show(StringBuilder sbs) { Console.WriteLine(sbs.ToString()); sb.Length = 0; } } /* This example produces the following results: StringBuilder.AppendFormat method: 1) 111 2) 111, 2.22 3) 111, 2.22, abcd 4) 3, 4.4, X 5) 2,22 */
using namespace System; using namespace System::Text; using namespace System::Globalization; void Show( StringBuilder^ sbs ) { Console::WriteLine( sbs ); sbs->Length = 0; } int main() { StringBuilder^ sb = gcnew StringBuilder; int var1 = 111; float var2 = 2.22F; String^ var3 = "abcd"; array<Object^>^var4 = {3,4.4,(Char)'X'}; Console::WriteLine(); Console::WriteLine( "StringBuilder.AppendFormat method:" ); sb->AppendFormat( "1) {0}", var1 ); Show( sb ); sb->AppendFormat( "2) {0}, {1}", var1, var2 ); Show( sb ); sb->AppendFormat( "3) {0}, {1}, {2}", var1, var2, var3 ); Show( sb ); sb->AppendFormat( "4) {0}, {1}, {2}", var4 ); Show( sb ); CultureInfo^ ci = gcnew CultureInfo( "es-ES",true ); array<Object^>^temp1 = {var2}; sb->AppendFormat( ci, "5) {0}", temp1 ); Show( sb ); } /* This example produces the following results: StringBuilder.AppendFormat method: 1) 111 2) 111, 2.22 3) 111, 2.22, abcd 4) 3, 4.4, X 5) 2,22 */
.NET Framework
Supported in: 4, 3.5, 3.0, 2.0, 1.1, 1.0.NET Framework Client Profile
Supported in: 4, 3.5 SP1Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Reference
Other Resources
|
Date |
History |
Reason |
|---|---|---|
|
January 2012 |
Added the Notes to Callers section. |
Content bug fix. |
Note