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 (String, Object)

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.

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

public StringBuilder AppendFormat (
	string format,
	Object arg0
)
public StringBuilder AppendFormat (
	String format, 
	Object arg0
)
public function AppendFormat (
	format : String, 
	arg0 : Object
) : StringBuilder
Not applicable.

Parameters

format

A composite format string.

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.

Exception typeCondition

ArgumentNullException

format is a null reference (Nothing in Visual Basic).

FormatException

format is invalid.

ArgumentOutOfRangeException

Enlarging the value of this instance 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 .NET Framework provides extensive formatting support, which is described in greater detail in the following formatting topics.

Format Specifications

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, a null reference (Nothing in Visual Basic)) provides the formatting; otherwise arg0.ToString() provides the formatting. If arg0 is a null reference (Nothing in Visual Basic) then an empty string is used in its place.

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.

Default Formatting

When the FormatString component 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."

The following code example demonstrates the AppendFormat method.

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
*/

// This example demonstrates the StringBuilder.AppendFormat method
import System.*;
import System.Text.*;
import System.Globalization.*;

class Sample
{
    private static StringBuilder sb = new StringBuilder();

    public static void main(String[] args)
    {
        int var1 = 111;
        float var2 = 2.22f;
        String var3 = "abcd";
        Object var4[] = { new Integer(3), new Double(4.4), new Character('X') };

        Console.WriteLine();
        Console.WriteLine("StringBuilder.AppendFormat method:");
        sb.AppendFormat("1) {0}", System.Convert.ToString(var1));
        Show(sb);
        sb.AppendFormat("2) {0}, {1}", System.Convert.ToString(var1), 
            System.Convert.ToString(var2));
        Show(sb);
        sb.AppendFormat("3) {0}, {1}, {2}", System.Convert.ToString(var1), 
            System.Convert.ToString(var2), System.Convert.ToString(var3));
        Show(sb);
        sb.AppendFormat("4) {0}, {1}, {2}", var4);
        Show(sb);
        CultureInfo ci = new CultureInfo("es-ES", true);
        sb.AppendFormat((IFormatProvider)ci, "5) {0}", 
            new Object[] { (System.Single)var2 });
        Show(sb);
    } //main

    public static void Show(StringBuilder sbs)
    {
        Console.WriteLine(sbs.ToString());
        sb.set_Length(0);
    } //Show
} //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
*/

Windows 98, Windows Server 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0, 1.1, 1.0
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

Show:
© 2014 Microsoft