Export (0) Print
Expand All

StringBuilder.AppendFormat Method (IFormatProvider, 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 (
	IFormatProvider provider,
	string format,
	params Object[] args
)
public StringBuilder AppendFormat (
	IFormatProvider provider, 
	String format, 
	Object[] args
)
public function AppendFormat (
	provider : IFormatProvider, 
	format : String, 
	... args : Object[]
) : StringBuilder

Parameters

provider

A IFormatProvider that determines the way formatting specifications in format are interpreted.

format

A string containing zero or more format specifications.

args

An array of objects to format.

Return Value

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 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 section briefly describes how the composite formatting feature of the .NET Framework applies to the format parameter. For more information about formatting, see Formatting Overview. For more information about the composite formatting feature, see Composite Formatting. For more information about format specifiers for numeric, date and time, and enumeration values, see Numeric Format Strings, Date and Time Format Strings, and Enumeration Format Strings.

Format Specifications

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 args[N] implements IFormattable then args[N].Format(format, a null reference (Nothing in Visual Basic)) provides the formatting; otherwise args[N].ToString() provides the formatting. If args[N] is a null reference (Nothing in Visual Basic) then an empty string is used in its place.

The provider parameter specifies an appropriate format provider, such as a NumberFormatInfo or DateTimeFormatInfo object. The format provider supplies information such as the characters to use for decimal and group separators, or the spelling and placement of currency symbols in monetary values. If the provider parameter is a null reference (Nothing in Visual Basic), format provider information is obtained from the current culture.

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 arg[0] 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 arg[0] 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 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 .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0

Community Additions

ADD
Show:
© 2014 Microsoft