StringBuilder.AppendFormat Method (IFormatProvider, 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 using a specified format provider.
Namespace: System.Text
Assembly: mscorlib (in mscorlib.dll)
Syntax
'Declaration
Public Function AppendFormat ( _
provider As IFormatProvider, _
format As String, _
ParamArray args As Object() _
) As StringBuilder
public StringBuilder AppendFormat(
IFormatProvider provider,
string format,
params Object[] args
)
Parameters
- provider
Type: System.IFormatProvider
An object that supplies culture-specific formatting information.
- 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 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 each format item is replaced by the string representation of the corresponding object argument.
Exceptions
| Exception | Condition |
|---|---|
| ArgumentNullException | format 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. |
.gif "Note") 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. |
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 numeric values in args.
A DateTimeFormatInfo object that provides culture-specific formatting information for date and time values in args.
A custom IFormatProvider implementation that provides formatting information for one or more of the objects in args. Typically, such an implementation also implements the ICustomFormatter interface. The second example in the next section illustrates an StringBuilder.AppendFormat(IFormatProvider, String, array<Object[]) method call with a custom IFormatProvider implementation.
If the provider parameter is nulla null reference (Nothing in Visual Basic), format provider information is obtained from the current culture.
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.
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
*/
The following example defines a custom IFormatProvider implementation named CustomerFormatter that formats a 10-digit customer number with hyphens after the fourth and seventh digits. It is passed to the StringBuilder.AppendFormat(IFormatProvider, String, array<Object[]) method to create a string that includes the formatted customer number and customer name.
Imports System.Text
Public Class Customer
Private custName As String
Private custNumber As Integer
Public Sub New(ByVal name As String, ByVal number As Integer)
custName = name
custNumber = number
End Sub
Public ReadOnly Property Name() As String
Get
Return Me.custName
End Get
End Property
Public ReadOnly Property CustomerNumber() As Integer
Get
Return Me.custNumber
End Get
End Property
End Class
Public Class CustomerNumberFormatter
Implements IFormatProvider, ICustomFormatter
Public Function GetFormat(ByVal formatType As Type) As Object _
Implements IFormatProvider.GetFormat
If formatType Is GetType(ICustomFormatter) Then
Return Me
End If
Return Nothing
End Function
Public Function Format(ByVal fmt As String, ByVal arg As Object, ByVal provider As IFormatProvider) As String _
Implements ICustomFormatter.Format
If TypeOf arg Is Int32 Then
Dim custNumber As String = CInt(arg).ToString("D10")
Return custNumber.Substring(0, 4) + "-" + custNumber.Substring(4, 3) + _
"-" + custNumber.Substring(7, 3)
Else
Return Nothing
End If
End Function
End Class
Module Example
Public Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
Dim customer As New Customer("A Plus Software", 903654)
Dim sb As New StringBuilder()
sb.AppendFormat(New CustomerNumberFormatter, "{0}: {1}", _
customer.CustomerNumber, customer.Name)
outputBlock.Text &= sb.ToString() & vbCrLf
End Sub
End Module
' The example displays the following output:
' 0000-903-654: A Plus Software
using System;
using System.Text;
public class Customer
{
private string custName;
private int custNumber;
public Customer(string name, int number)
{
this.custName = name;
this.custNumber = number;
}
public string Name
{
get { return this.custName; }
}
public int CustomerNumber
{
get { return this.custNumber; }
}
}
public class CustomerNumberFormatter : IFormatProvider, ICustomFormatter
{
public object GetFormat(Type formatType)
{
if (formatType == typeof(ICustomFormatter))
return this;
return null;
}
public string Format(string format, object arg, IFormatProvider provider)
{
if (arg is Int32)
{
string custNumber = ((int)arg).ToString("D10");
return custNumber.Substring(0, 4) + "-" + custNumber.Substring(4, 3) +
"-" + custNumber.Substring(7, 3);
}
else
{
return null;
}
}
}
public class Example
{
public static void Demo(System.Windows.Controls.TextBlock outputBlock)
{
Customer customer = new Customer("A Plus Software", 903654);
StringBuilder sb = new StringBuilder();
sb.AppendFormat(new CustomerNumberFormatter(), "{0}: {1}",
customer.CustomerNumber, customer.Name);
outputBlock.Text += sb.ToString() + "\n";
}
}
// The example displays the following output:
// 0000-903-654: A Plus Software
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.
See Also