StringBuilder.Append Method

Definition

Appends the string representation of a specified object to this instance.

Overloads

Append(StringBuilder)

Appends the string representation of a specified string builder to this instance.

Append(StringBuilder+AppendInterpolatedStringHandler)

Appends the specified interpolated string to this instance.

Append(UInt16)

Appends the string representation of a specified 16-bit unsigned integer to this instance.

Append(UInt32)

Appends the string representation of a specified 32-bit unsigned integer to this instance.

Append(Char, Int32)

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

Append(Char[], Int32, Int32)

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

Append(IFormatProvider, StringBuilder+AppendInterpolatedStringHandler)

Appends the specified interpolated string to this instance using the specified format.

Append(String)

Appends a copy of the specified string to this instance.

Append(String, Int32, Int32)

Appends a copy of a specified substring to this instance.

Append(StringBuilder, Int32, Int32)

Appends a copy of a substring within a specified string builder to this instance.

Append(Char*, Int32)

Appends an array of Unicode characters starting at a specified address to this instance.

Append(Single)

Appends the string representation of a specified single-precision floating-point number to this instance.

Append(UInt64)

Appends the string representation of a specified 64-bit unsigned integer to this instance.

Append(ReadOnlySpan<Char>)

Appends the string representation of a specified read-only character span to this instance.

Append(SByte)

Appends the string representation of a specified 8-bit signed integer to this instance.

Append(Boolean)

Appends the string representation of a specified Boolean value to this instance.

Append(Byte)

Appends the string representation of a specified 8-bit unsigned integer to this instance.

Append(Char)

Appends the string representation of a specified Char object to this instance.

Append(Decimal)

Appends the string representation of a specified decimal number to this instance.

Append(Double)

Appends the string representation of a specified double-precision floating-point number to this instance.

Append(Char[])

Appends the string representation of the Unicode characters in a specified array to this instance.

Append(Int16)

Appends the string representation of a specified 16-bit signed integer to this instance.

Append(Int32)

Appends the string representation of a specified 32-bit signed integer to this instance.

Append(Int64)

Appends the string representation of a specified 64-bit signed integer to this instance.

Append(Object)

Appends the string representation of a specified object to this instance.

Append(ReadOnlyMemory<Char>)

Appends the string representation of a specified read-only character memory region to this instance.

Append(StringBuilder)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of a specified string builder to this instance.

C#
public System.Text.StringBuilder Append(System.Text.StringBuilder? value);
C#
public System.Text.StringBuilder Append(System.Text.StringBuilder value);

Parameters

value
StringBuilder

The string builder to append.

Returns

A reference to this instance after the append operation is completed.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Standard 2.1

Append(StringBuilder+AppendInterpolatedStringHandler)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the specified interpolated string to this instance.

C#
public System.Text.StringBuilder Append(ref System.Text.StringBuilder.AppendInterpolatedStringHandler handler);

Parameters

handler
StringBuilder.AppendInterpolatedStringHandler

The interpolated string to append.

Returns

A reference to this instance after the append operation has completed.

Applies to

.NET 9 and other versions
Product Versions
.NET 6, 7, 8, 9

Append(UInt16)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Important

This API is not CLS-compliant.

Appends the string representation of a specified 16-bit unsigned integer to this instance.

C#
[System.CLSCompliant(false)]
public System.Text.StringBuilder Append(ushort value);

Parameters

value
UInt16

The value to append.

Returns

A reference to this instance after the append operation has completed.

Attributes

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(UInt16) 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.

C#
System.Text.StringBuilder sb = new 
            System.Text.StringBuilder("The range of a 16-bit unsigned integer: ");
sb.Append(UInt16.MinValue).Append(" to ").Append(UInt16.MaxValue);
Console.WriteLine(sb);
// The example displays the following output:
//       The range of a 16-bit unsigned integer: 0 to 65535

The Append(UInt16) method calls the UInt16.ToString(IFormatProvider) method to get the string representation of value. To control the formatting of value, call the AppendFormat method.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(UInt32)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Important

This API is not CLS-compliant.

Appends the string representation of a specified 32-bit unsigned integer to this instance.

C#
[System.CLSCompliant(false)]
public System.Text.StringBuilder Append(uint value);

Parameters

value
UInt32

The value to append.

Returns

A reference to this instance after the append operation has completed.

Attributes

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(UInt32) 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.

C#
System.Text.StringBuilder sb = new 
            System.Text.StringBuilder("The range of a 32-bit unsigned integer: ");
sb.Append(UInt32.MinValue).Append(" to ").Append(UInt32.MaxValue);
Console.WriteLine(sb);
// The example displays the following output:
//       The range of a 32-bit unsigned integer: 0 to 4294967295

The Append(UInt32) calls the UInt32.ToString method to get the string representation of value for the current culture. To control the formatting of value, call the AppendFormat method.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(Char, Int32)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

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

C#
public System.Text.StringBuilder Append(char value, int repeatCount);

Parameters

value
Char

The character to append.

repeatCount
Int32

The number of times to append value.

Returns

A reference to this instance after the append operation has completed.

Exceptions

repeatCount is less than zero.

-or-

Enlarging the value of this instance would exceed MaxCapacity.

Out of memory.

Remarks

The Append(Char, Int32) 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.

C#
decimal value = 1346.19m;
System.Text.StringBuilder sb = new System.Text.StringBuilder();
sb.Append('*', 5).AppendFormat("{0:C2}", value).Append('*', 5);
Console.WriteLine(sb);
// The example displays the following output:
//       *****$1,346.19*****

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(Char[], Int32, Int32)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

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

C#
public System.Text.StringBuilder Append(char[] value, int startIndex, int charCount);
C#
public System.Text.StringBuilder Append(char[]? value, int startIndex, int charCount);

Parameters

value
Char[]

A character array.

startIndex
Int32

The starting position in value.

charCount
Int32

The number of characters to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

value is null, and startIndex and charCount are not zero.

charCount is less than zero.

-or-

startIndex is less than zero.

-or-

startIndex + charCount is greater than the length of value.

-or-

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

This method appends the specified range of characters in value to the current instance. If value is null and startIndex and count are both zero, no changes are made.

The Append(Char[], Int32, Int32) 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.

C#
char[] chars = { 'a', 'b', 'c', 'd', 'e'};
System.Text.StringBuilder sb = new System.Text.StringBuilder();
int startPosition = Array.IndexOf(chars, 'a');
int endPosition = Array.IndexOf(chars, 'c');
if (startPosition >= 0 && endPosition >= 0) {
   sb.Append("The array from positions ").Append(startPosition).
             Append(" to ").Append(endPosition).Append(" contains ").
             Append(chars, startPosition, endPosition + 1).Append(".");
   Console.WriteLine(sb);
}             
// The example displays the following output:
//       The array from positions 0 to 2 contains abc.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(IFormatProvider, StringBuilder+AppendInterpolatedStringHandler)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the specified interpolated string to this instance using the specified format.

C#
public System.Text.StringBuilder Append(IFormatProvider? provider, ref System.Text.StringBuilder.AppendInterpolatedStringHandler handler);

Parameters

provider
IFormatProvider

An object that supplies culture-specific formatting information.

handler
StringBuilder.AppendInterpolatedStringHandler

The interpolated string to append.

Returns

A reference to this instance after the append operation has completed.

Applies to

.NET 9 and other versions
Product Versions
.NET 6, 7, 8, 9

Append(String)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends a copy of the specified string to this instance.

C#
public System.Text.StringBuilder Append(string value);
C#
public System.Text.StringBuilder Append(string? value);

Parameters

value
String

The string to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(String) 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.

C#
bool flag = false;
System.Text.StringBuilder sb = new System.Text.StringBuilder();
sb.Append("The value of the flag is ").Append(flag).Append(".");
Console.WriteLine(sb.ToString());
// The example displays the following output:
//       The value of the flag is False.

If value is null, no changes are made.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(String, Int32, Int32)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends a copy of a specified substring to this instance.

C#
public System.Text.StringBuilder Append(string value, int startIndex, int count);
C#
public System.Text.StringBuilder Append(string? value, int startIndex, int count);

Parameters

value
String

The string that contains the substring to append.

startIndex
Int32

The starting position of the substring within value.

count
Int32

The number of characters in value to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

value is null, and startIndex and count are not zero.

count less than zero.

-or-

startIndex less than zero.

-or-

startIndex + count is greater than the length of value.

-or-

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

This method appends the specified range of characters in value to the current instance. If value is null and startIndex and count are both zero, no changes are made.

The Append(String, Int32, Int32) 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.

C#
string str = "First;George Washington;1789;1797";
int index = 0;
System.Text.StringBuilder sb = new System.Text.StringBuilder();
int length = str.IndexOf(';', index);      
sb.Append(str, index, length).Append(" President of the United States: ");
index += length + 1;
length = str.IndexOf(';', index) - index;
sb.Append(str, index, length).Append(", from ");
index += length + 1;
length = str.IndexOf(';', index) - index;
sb.Append(str, index, length).Append(" to ");
index += length + 1;
sb.Append(str, index, str.Length - index);
Console.WriteLine(sb);
// The example displays the following output:
//    First President of the United States: George Washington, from 1789 to 1797

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(StringBuilder, Int32, Int32)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends a copy of a substring within a specified string builder to this instance.

C#
public System.Text.StringBuilder Append(System.Text.StringBuilder? value, int startIndex, int count);
C#
public System.Text.StringBuilder Append(System.Text.StringBuilder value, int startIndex, int count);

Parameters

value
StringBuilder

The string builder that contains the substring to append.

startIndex
Int32

The starting position of the substring within value.

count
Int32

The number of characters in value to append.

Returns

A reference to this instance after the append operation has completed.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Standard 2.1

Append(Char*, Int32)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Important

This API is not CLS-compliant.

CLS-compliant alternative
System.Text.StringBuilder.Append(Char[], Int32, Int32)

Appends an array of Unicode characters starting at a specified address to this instance.

C#
[System.CLSCompliant(false)]
[System.Security.SecurityCritical]
public System.Text.StringBuilder Append(char* value, int valueCount);
C#
[System.CLSCompliant(false)]
public System.Text.StringBuilder Append(char* value, int valueCount);

Parameters

value
Char*

A pointer to an array of characters.

valueCount
Int32

The number of characters in the array.

Returns

A reference to this instance after the append operation has completed.

Attributes

Exceptions

valueCount is less than zero.

-or-

Enlarging the value of this instance would exceed MaxCapacity.

value is a null pointer.

Remarks

This method appends valueCount characters starting at address value to the current instance.

The Append(Char*, Int32) 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.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(Single)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of a specified single-precision floating-point number to this instance.

C#
public System.Text.StringBuilder Append(float value);

Parameters

value
Single

The value to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(Single) 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.

C#
float value = 1034769.47f;
System.Text.StringBuilder sb = new System.Text.StringBuilder();
sb.Append('*', 5).Append(value).Append('*', 5);
Console.WriteLine(sb);
// The example displays the following output:
//       *****1034769.47*****

The Append(Single) method calls the Single.ToString method to get the string representation of value for the current culture. To control the formatting of value, call the AppendFormat method.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(UInt64)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Important

This API is not CLS-compliant.

Appends the string representation of a specified 64-bit unsigned integer to this instance.

C#
[System.CLSCompliant(false)]
public System.Text.StringBuilder Append(ulong value);

Parameters

value
UInt64

The value to append.

Returns

A reference to this instance after the append operation has completed.

Attributes

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(UInt64) 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.

C#
System.Text.StringBuilder sb = new 
            System.Text.StringBuilder("The range of a 64-bit unsigned integer: ");
sb.Append(UInt64.MinValue).Append(" to ").Append(UInt64.MaxValue);
Console.WriteLine(sb);
// The example displays the following output:
//       The range of a 64-bit unsigned integer: 0 to 18446744073709551615

The Append(UInt64) method calls the UInt64.ToString(IFormatProvider) method to get the string representation of value for the current culture. To control the formatting of value, call the AppendFormat method.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(ReadOnlySpan<Char>)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of a specified read-only character span to this instance.

C#
public System.Text.StringBuilder Append(ReadOnlySpan<char> value);

Parameters

value
ReadOnlySpan<Char>

The read-only character span to append.

Returns

A reference to this instance after the append operation is completed.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Standard 2.1

Append(SByte)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Important

This API is not CLS-compliant.

Appends the string representation of a specified 8-bit signed integer to this instance.

C#
[System.CLSCompliant(false)]
public System.Text.StringBuilder Append(sbyte value);

Parameters

value
SByte

The value to append.

Returns

A reference to this instance after the append operation has completed.

Attributes

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(SByte) 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.

C#
System.Text.StringBuilder sb = new 
            System.Text.StringBuilder("The range of an 8-bit signed integer: ");
sb.Append(SByte.MinValue).Append(" to ").Append(SByte.MaxValue);
Console.WriteLine(sb);
// The example displays the following output:
//       The range of an 8-bit unsigned integer: -128 to 127

The Append(SByte) method calls the SByte.ToString(IFormatProvider) method to get the string representation of value for the current culture. To control the formatting of value, call the AppendFormat method.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(Boolean)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of a specified Boolean value to this instance.

C#
public System.Text.StringBuilder Append(bool value);

Parameters

value
Boolean

The Boolean value to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(Boolean) 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.

C#
bool flag = false;
System.Text.StringBuilder sb = new System.Text.StringBuilder();
sb.Append("The value of the flag is ").Append(flag).Append(".");
Console.WriteLine(sb.ToString());
// The example displays the following output:
//       The value of the flag is False.

The Append(Boolean) method calls the Boolean.ToString() method to get the string representation of value. The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(Byte)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of a specified 8-bit unsigned integer to this instance.

C#
public System.Text.StringBuilder Append(byte value);

Parameters

value
Byte

The value to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(Byte) 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.

C#
Byte[] bytes = { 16, 132, 27, 253 };
System.Text.StringBuilder sb = new System.Text.StringBuilder();
foreach (var value in bytes)
   sb.Append(value).Append(" ");         

Console.WriteLine("The byte array: {0}", sb.ToString());
// The example displays the following output:
//         The byte array: 16 132 27 253

The Append(Byte) method calls the ToString(IFormatProvider) method to get the string representation of value for the current culture. To control the formatting of value, call the AppendFormat method.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(Char)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of a specified Char object to this instance.

C#
public System.Text.StringBuilder Append(char value);

Parameters

value
Char

The UTF-16-encoded code unit to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(Char) 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.

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 .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(Decimal)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of a specified decimal number to this instance.

C#
public System.Text.StringBuilder Append(decimal value);

Parameters

value
Decimal

The value to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(Decimal) 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.

C#
decimal value = 1346.19m;
System.Text.StringBuilder sb = new System.Text.StringBuilder();
sb.Append('*', 5).Append(value).Append('*', 5);
Console.WriteLine(sb);
// The example displays the following output:
//       *****1346.19*****

The Append(Decimal) method calls the Decimal.ToString(IFormatProvider) method to get the string representation of value for the current culture. To control the formatting of value, call the AppendFormat method.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(Double)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of a specified double-precision floating-point number to this instance.

C#
public System.Text.StringBuilder Append(double value);

Parameters

value
Double

The value to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(Double) 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.

C#
double value = 1034769.47;
System.Text.StringBuilder sb = new System.Text.StringBuilder();
sb.Append('*', 5).Append(value).Append('*', 5);
Console.WriteLine(sb);
// The example displays the following output:
//       *****1034769.47*****

The Append(Double) method calls the Double.ToString(IFormatProvider) method to get the string representation of value for the current culture. To control the formatting of value, call the AppendFormat method.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(Char[])

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of the Unicode characters in a specified array to this instance.

C#
public System.Text.StringBuilder Append(char[] value);
C#
public System.Text.StringBuilder Append(char[]? value);

Parameters

value
Char[]

The array of characters to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

This method appends all the characters in the specified array to the current instance in the same order as they appear in value. If value is null, no changes are made.

The Append(Char[]) 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.

C#
char[] chars = { 'a', 'e', 'i', 'o', 'u' };
System.Text.StringBuilder sb = new System.Text.StringBuilder();
sb.Append("The characters in the array: ").Append(chars);
Console.WriteLine(sb);
// The example displays the following output:
//      The characters in the array: aeiou

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(Int16)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of a specified 16-bit signed integer to this instance.

C#
public System.Text.StringBuilder Append(short value);

Parameters

value
Int16

The value to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(Int16) 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.

C#
System.Text.StringBuilder sb = new 
       System.Text.StringBuilder("The range of a 16-bit integer: ");
sb.Append(Int16.MinValue).Append(" to ").Append(Int16.MaxValue);
Console.WriteLine(sb);
// The example displays the following output:
//       The range of a 16-bit integer: -32768 to 32767

The Append(Int16) method calls the Int16.ToString(IFormatProvider) method to get the string representation of value for the current culture. To control the formatting of value, call the AppendFormat method.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(Int32)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of a specified 32-bit signed integer to this instance.

C#
public System.Text.StringBuilder Append(int value);

Parameters

value
Int32

The value to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(Int32) 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.

C#
System.Text.StringBuilder sb = new 
       System.Text.StringBuilder("The range of a 32-bit integer: ");
sb.Append(Int32.MinValue).Append(" to ").Append(Int32.MaxValue);
Console.WriteLine(sb);
// The example displays the following output:
//       The range of a 32-bit integer: -2147483648 to 2147483647

The Append(Int32) method calls the Int32.ToString(IFormatProvider) method to get the string representation of value for the current culture. To control the formatting of value, call the AppendFormat method.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(Int64)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of a specified 64-bit signed integer to this instance.

C#
public System.Text.StringBuilder Append(long value);

Parameters

value
Int64

The value to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(Int64) 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.

C#
System.Text.StringBuilder sb = new 
            System.Text.StringBuilder("The range of a 64-bit integer: ");
sb.Append(Int64.MinValue).Append(" to ").Append(Int64.MaxValue);
Console.WriteLine(sb);
// The example displays the following output:
//       The range of a 64-bit integer:  -9223372036854775808 to 9223372036854775807

The Append(Int64) method calls the Int64.ToString(IFormatProvider) to get the string representation of value for the current culture. To control the formatting of value, call the AppendFormat method.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(Object)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of a specified object to this instance.

C#
public System.Text.StringBuilder Append(object value);
C#
public System.Text.StringBuilder Append(object? value);

Parameters

value
Object

The object to append.

Returns

A reference to this instance after the append operation has completed.

Exceptions

Enlarging the value of this instance would exceed MaxCapacity.

Remarks

The Append(Object) 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. It defines a Dog class, creates a Dog object, and makes three calls to the Append method to create a string that contains the dog's name and breed.

C#
using System;

public class Dog
{
   private string dogBreed;
   private string dogName;
   
   public Dog(string name, string breed)
   {
      this.dogName = name;
      this.dogBreed = breed;
   }
   
   public string Breed {
      get { return this.dogBreed; }
   }
   
   public string Name {
      get { return this.dogName; }
   }
   
   public override string ToString()
   {
      return this.dogName;
   }
}

public class Example
{
   public static void Main()
   {
      Dog dog1 = new Dog("Yiska", "Alaskan Malamute");
      System.Text.StringBuilder sb = new System.Text.StringBuilder();     
      sb.Append(dog1).Append(", Breed: ").Append(dog1.Breed);  
      Console.WriteLine(sb);
   }
}
// The example displays the following output:
//        Yiska, Breed: Alaskan Malamute

The Append(Object) method calls the Object.ToString method to get the string representation of value. If value is null, no changes are made to the StringBuilder object.

The capacity of this instance is adjusted as needed.

Notes to Callers

In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) 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(String) and AppendFormat(String, Object) methods to append small strings.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Append(ReadOnlyMemory<Char>)

Source:
StringBuilder.cs
Source:
StringBuilder.cs
Source:
StringBuilder.cs

Appends the string representation of a specified read-only character memory region to this instance.

C#
public System.Text.StringBuilder Append(ReadOnlyMemory<char> value);

Parameters

value
ReadOnlyMemory<Char>

The read-only character memory region to append.

Returns

A reference to this instance after the append operation is completed.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 3.0, Core 3.1, 5, 6, 7, 8, 9