StringBuilder.AppendFormat Method (String, array<Object[])

Microsoft Silverlight will reach end of support after October 2021. Learn more.

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 corresponding argument in a parameter array.

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

Syntax

'Declaration
Public Function AppendFormat ( _
    format As String, _
    ParamArray args As Object() _
) As StringBuilder
public StringBuilder AppendFormat(
    string format,
    params Object[] args
)

Parameters

  • format
    Type: System.String
    A composite format string (see Remarks).
  • args
    Type: array<System.Object[]
    An array of objects to format.

Return Value

Type: System.Text.StringBuilder
A reference to this instance with format appended. Each format item in format is replaced by the string representation of the corresponding object argument.

Exceptions

Exception Condition
ArgumentNullException

format or args is nulla null reference (Nothing in Visual Basic).

FormatException

format is invalid.

-or-

The index of a format item is less than 0 (zero), or greater than or equal to the length of the args array.

ArgumentOutOfRangeException

The length of the expanded string would exceed the maximum capacity of this instance.

Remarks

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 nulla null reference (Nothing in Visual Basic), 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.

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.

args represents the objects to be formatted. Each format item in format is replaced with the string representation of the corresponding object in args. If the format item includes formatString and the corresponding object in args implements the IFormattable interface, then args[index].Format(formatString, provider) defines the formatting. Otherwise, args[index].ToString(provider) defines the formatting.

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, 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, the return value (where underscores represent padding spaces) will be "Brad's dog has 42______ fleas."

Examples

The following code example demonstrates the AppendFormat method.

Imports System.Text
Imports System.Globalization

Class Example
   Private Shared sb As New StringBuilder()

   Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      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}

      outputBlock.Text &= vbCrLf
      outputBlock.Text &= "StringBuilder.AppendFormat method:" & vbCrLf
      sb.AppendFormat("1) {0}", var1)
      Show(outputBlock, sb)
      sb.AppendFormat("2) {0}, {1}", var1, var2)
      Show(outputBlock, sb)
      sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3)
      Show(outputBlock, sb)
      sb.AppendFormat("4) {0}, {1}, {2}", var4)
      Show(outputBlock, sb)
      Dim ci As New CultureInfo("es-ES")
      sb.AppendFormat(ci, "5) {0}", var2)
      Show(outputBlock, sb)
   End Sub 'Main

   Public Shared Sub Show(ByVal outputBlock As System.Windows.Controls.TextBlock, ByVal sbs As StringBuilder)
      outputBlock.Text &= sbs.ToString() & vbCrLf
      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 Example
{
   static StringBuilder sb = new StringBuilder();

   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      int var1 = 111;
      float var2 = 2.22F;
      string var3 = "abcd";
      object[] var4 = { 3, 4.4, 'X' };

      outputBlock.Text += "\n";
      outputBlock.Text += "StringBuilder.AppendFormat method:" + "\n";
      sb.AppendFormat("1) {0}", var1);
      Show(outputBlock, sb);
      sb.AppendFormat("2) {0}, {1}", var1, var2);
      Show(outputBlock, sb);
      sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3);
      Show(outputBlock, sb);
      sb.AppendFormat("4) {0}, {1}, {2}", var4);
      Show(outputBlock, sb);
      CultureInfo ci = new CultureInfo("es-ES");
      sb.AppendFormat(ci, "5) {0}", var2);
      Show(outputBlock, sb);
   }

   public static void Show(System.Windows.Controls.TextBlock outputBlock, StringBuilder sbs)
   {
      outputBlock.Text += sbs.ToString() + "\n";
      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
*/

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.