StringBuilder.Append Method (Char) (System.Text)

Switch View :
Classic
Lightweight
ScriptFree
.NET Framework Class Library
StringBuilder.Append Method (Char)

Updated: January 2012

Appends the string representation of a specified Unicode character to this instance.

Namespace:  System.Text
Assembly:  mscorlib (in mscorlib.dll)
Syntax
Visual Basic
Public Function Append ( _
	value As Char _
) As StringBuilder
C#
public StringBuilder Append(
	char value
)
Visual C++
public:
StringBuilder^ Append(
	wchar_t value
)
F#
member Append : 
        value:char -> StringBuilder

Parameters

value
Type: System.Char
The Unicode character to append.

Return Value

Type: System.Text.StringBuilder
A reference to this instance after the append operation has completed.
Exceptions
Exception Condition
ArgumentOutOfRangeException

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a StringBuilder object, as the following example illustrates.

Visual Basic

Dim str As String = "Characters in a string."
Dim sb As New System.Text.StringBuilder()
For Each ch In str
   sb.Append(" '").Append(ch).Append("' ")
Next
Console.WriteLine("Characters in the string:")
Console.WriteLine("  {0}", sb)
' The example displays the following output:
'    Characters in the string:
'       'C'  'h'  'a'  'r'  'a'  'c'  't'  'e'  'r'  's'  ' '  'i'  'n'  ' '  'a'  ' '  's'  't' 'r'  'i'  'n'  'g'  '.'
C#

string str = "Characters in a string.";
System.Text.StringBuilder sb = new System.Text.StringBuilder();
foreach (var ch in str)
   sb.Append(" '").Append(ch).Append("' ");

Console.WriteLine("Characters in the string:");
Console.WriteLine("  {0}", sb);
// The example displays the following output:
//    Characters in the string:
//       'C'  'h'  'a'  'r'  'a'  'c'  't'  'e'  'r'  's'  ' '  'i'  'n'  ' '  'a'  ' '  's'  't' 'r'  'i'  'n'  'g'  '.'

The capacity of this instance is adjusted as needed.

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.

Version Information

.NET Framework

Supported in: 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library
Platforms

Windows 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.
See Also

Reference

StringBuilder Class
Append Overload
System.Text Namespace
Char
Change History

Date

History

Reason

January 2012

Added the Notes to Callers section.

Content bug fix.

December 2010

Expanded the Remarks section and removed the example.

Customer feedback.
Community Content

Kyle Farlow
C++/CLI beware character literals
Because StringBuilder provides both Append(Byte) and Append(Char) overrides, C++/CLI users must be careful to use the wide-char literal specifier, L, to decorate each character literal passed to Append.   Calling Append(L'!') will append an exclamation point as expected.  But calling Append('!') will append the string "33", which is the decimal value of '!' when cast to a Byte.