System.Text.StringBuilder Class

Summary

Represents a mutable string of characters. This class cannot be inherited.

C# Syntax:

[Serializable] public sealed class StringBuilder

This class represents a string-like object whose value is a mutable sequence of characters. The value is said to be mutable because it can be modified once it has been created by appending, removing, replacing, or inserting characters. For comparison, see the String class.

Most of the methods that modify an instance of this class return a reference to that same instance. Since a reference to the instance is returned, you can call a method or property on the reference. This can be convenient if you want to write a single statement that chains successive operations one after another.

The capacity of a StringBuilder is the maximum number of characters the instance can store at any given time, and is greater than or equal to the length of the string representation of the value of the instance. The capacity can be increased or decreased with the StringBuilder.Capacity property or StringBuilder.EnsureCapacity method, but it cannot be less than the value of the StringBuilder.Length property.

A StringBuilder can allocate more memory as needed to store characters when the value of an instance is enlarged, and the capacity is adjusted accordingly. A default capacity is used if no capacity is specified when an instance of StringBuilder is initialized.

Notes to implementors: The default capacity for this implementation is 16, and the maximum capacity is Int32.MaxValue. However, these values are implementation-specific and might be different in other or later implementations.

A StringBuilder can allocate more memory as needed to store characters when the string value of an instance is enlarged. The amount of memory allocated is implementation-specific. An ArgumentOutOfRangeException is thrown if the amount of memory required is greater than the maximum capacity.

The individual characters in the value of a StringBuilder can be accessed with the StringBuilder.Chars property. Index positions start from zero.

System.Text Namespace | String

System.Text.StringBuilder Member List:

Public Constructors

ctor #1	Overloaded: .ctor() Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the StringBuilder class.
ctor #2	Overloaded: .ctor(int capacity) Initializes a new instance of the StringBuilder class using the specified capacity.
ctor #3	Overloaded: .ctor(string value) Initializes a new instance of the StringBuilder class using the specified string.
ctor #4	Overloaded: .ctor(int capacity, int maxCapacity) Initializes a new instance of the StringBuilder class that starts with a specified capacity and can grow to a specified maximum.
ctor #5	Overloaded: .ctor(string value, int capacity) Initializes a new instance of the StringBuilder class using the specified string and capacity.
ctor #6	Overloaded: .ctor(string value, int startIndex, int length, int capacity) Initializes a new instance of the StringBuilder class from the specified substring and capacity.

Public Properties

Capacity	Read-write Gets or sets the maximum number of characters that can be contained in the memory allocated by the current instance.
Chars	Read-write Gets or sets the character at the specified character position in this instance.
Length	Read-write Gets or sets the length of this instance.
MaxCapacity	Read-only Gets the maximum capacity of this instance.

Public Methods

Append	Overloaded: Append(bool value) Appends the string representation of a specified Boolean value to the end of this instance.
Append	Overloaded: Append(byte value) Appends the string representation of a specified 8-bit unsigned integer to the end of this instance.
Append	Overloaded: Append(char value) Appends the string representation of a specified Unicode character to the end of this instance.
Append	Overloaded: Append(char[] value) Appends the string representation of the Unicode characters in a specified array to the end of this instance.
Append	Overloaded: Append(decimal value) Appends the string representation of a specified decimal number to the end of this instance.
Append	Overloaded: Append(double value) Appends the string representation of a specified double-precision floating-point number to the end of this instance.
Append	Overloaded: Append(short value) Appends the string representation of a specified 16-bit signed integer to the end of this instance.
Append	Overloaded: Append(int value) Appends the string representation of a specified 32-bit signed integer to the end of this instance.
Append	Overloaded: Append(long value) Appends the string representation of a specified 64-bit signed integer to the end of this instance.
Append	Overloaded: Append(object value) Appends the string representation of a specified object to the end of this instance.
Append	Overloaded: Append(sbyte value) Appends the string representation of a specified 8-bit signed integer to the end of this instance.
Append	Overloaded: Append(float value) Appends the string representation of a specified single-precision floating-point number to the end of this instance.
Append	Overloaded: Append(string value) Appends a copy of the specified string to the end of this instance.
Append	Overloaded: Append(ushort value) Appends the string representation of a specified 16-bit unsigned integer to the end of this instance.
Append	Overloaded: Append(uint value) Appends the string representation of a specified 32-bit unsigned integer to the end of this instance.
Append	Overloaded: Append(ulong value) Appends the string representation of a specified 64-bit unsigned integer to the end of this instance.
Append	Overloaded: Append(char value, int repeatCount) Appends a specified number of copies of the string representation of a Unicode character to the end of this instance.
Append	Overloaded: Append(char[] value, int startIndex, int charCount) Appends the string representation of a specified subarray of Unicode characters to the end of this instance.
Append	Overloaded: Append(string value, int startIndex, int count) Appends a copy of a specified substring to the end of this instance.
AppendFormat	Overloaded: AppendFormat(string format, object arg0) 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.
AppendFormat	Overloaded: AppendFormat(string format, params object[] args) 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.
AppendFormat	Overloaded: AppendFormat(IFormatProvider provider, string format, params object[] args) 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.
AppendFormat	Overloaded: AppendFormat(string format, object arg0, object arg1) 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.
AppendFormat	Overloaded: AppendFormat(string format, object arg0, object arg1, object arg2) 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.
EnsureCapacity	Ensures that the capacity of this instance of StringBuilder is at least the specified value.
Equals (inherited from System.Object)	Overloaded: Equals(object obj) See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
Equals	Overloaded: Equals(StringBuilder sb) Returns a value indicating whether this instance is equal to a specified object.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
Insert	Overloaded: Insert(int index, bool value) Inserts the string representation of a Boolean value into this instance at the specified character position.
Insert	Overloaded: Insert(int index, byte value) Inserts the string representation of a specified 8-bit unsigned integer into this instance at the specified character position.
Insert	Overloaded: Insert(int index, char value) Inserts the string representation of a specified Unicode character into this instance at the specified character position.
Insert	Overloaded: Insert(int index, char[] value) Inserts the string representation of a specified array of Unicode characters into this instance at the specified character position.
Insert	Overloaded: Insert(int index, decimal value) Inserts the string representation of a decimal number into this instance at the specified character position.
Insert	Overloaded: Insert(int index, double value) Inserts the string representation of a double-precision floating-point number into this instance at the specified character position.
Insert	Overloaded: Insert(int index, short value) Inserts the string representation of a specified 16-bit signed integer into this instance at the specified character position.
Insert	Overloaded: Insert(int index, int value) Inserts the string representation of a specified 32-bit signed integer into this instance at the specified character position.
Insert	Overloaded: Insert(int index, long value) Inserts the string representation of a 64-bit signed integer into this instance at the specified character position.
Insert	Overloaded: Insert(int index, object value) Inserts the string representation of an object into this instance at the specified character position.
Insert	Overloaded: Insert(int index, sbyte value) Inserts the string representation of a specified 8-bit signed integer into this instance at the specified character position.
Insert	Overloaded: Insert(int index, float value) Inserts the string representation of a single-precision floating point number into this instance at the specified character position.
Insert	Overloaded: Insert(int index, string value) Inserts a string into this instance at the specified character position.
Insert	Overloaded: Insert(int index, ushort value) Inserts the string representation of a 16-bit unsigned integer into this instance at the specified character position.
Insert	Overloaded: Insert(int index, uint value) Inserts the string representation of a 32-bit unsigned integer into this instance at the specified character position.
Insert	Overloaded: Insert(int index, ulong value) Inserts the string representation of a 64-bit unsigned integer into this instance at the specified character position.
Insert	Overloaded: Insert(int index, string value, int count) Inserts one or more copies of a specified string into this instance at the specified character position.
Insert	Overloaded: Insert(int index, char[] value, int startIndex, int charCount) Inserts the string representation of a specified subarray of Unicode characters into this instance at the specified character position.
Remove	Removes the specified range of characters from this instance.
Replace	Overloaded: Replace(char oldChar, char newChar) Replaces all occurrences of a specified character in this instance with another specified character.
Replace	Overloaded: Replace(string oldValue, string newValue) Replaces all occurrences of a specified substring in this instance with another specified string.
Replace	Overloaded: Replace(char oldChar, char newChar, int startIndex, int count) Replaces all occurrences of a specified character in a substring of this instance with another specified character.
Replace	Overloaded: Replace(string oldValue, string newValue, int startIndex, int count) Replaces all occurrences of a specified string in a substring of this instance with another specified string.
ToString	Overloaded: ToString() Overridden: Converts this instance to a String.
ToString	Overloaded: ToString(int startIndex, int length) Converts a substring of the current StringBuilder to a String.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.Text.StringBuilder

System.Text.StringBuilder Member Details

Summary

Initializes a new instance of the StringBuilder class.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

public StringBuilder();

The string value of this instance is set to String.Empty, and the capacity is set to the implementation-specific default capacity.

Return to top

Summary

Initializes a new instance of the StringBuilder class using the specified capacity.

C# Syntax:

public StringBuilder(    int capacity );

capacity

The suggested starting size of this instance.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	capacity is less than zero.

The string value of this instance is set to String.Empty. If capacity is zero, the implementation-specific default capacity is used.

Return to top

Summary

Initializes a new instance of the StringBuilder class using the specified string.

C# Syntax:

public StringBuilder(    string value );

value

The string used to initialize the value of the instance. If value is null, the new StringBuilder will contain the empty string (that is, it contains String.Empty).

If value is null, the new StringBuilder will contain the empty string (that is, it contains String.Empty).

Return to top

Summary

Initializes a new instance of the StringBuilder class that starts with a specified capacity and can grow to a specified maximum.

C# Syntax:

public StringBuilder(    int capacity,    int maxCapacity );

capacity

The suggested starting size of the StringBuilder.

maxCapacity

The maximum number of characters the current string can contain.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	maxCapacity is less than one, capacity is less than zero, or capacity is greater than maxCapacity.

If capacity is zero, the implementation-specific default capacity is used.

Return to top

Summary

Initializes a new instance of the StringBuilder class using the specified string and capacity.

C# Syntax:

public StringBuilder(    string value,    int capacity );

value

The string used to initialize the value of the instance. If value is null, the new StringBuilder will contain the empty string (that is, it contains String.Empty).

capacity

The suggested starting size of the StringBuilder.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	capacity is less than zero.

The maximum number of characters value can contain is set by capacity.

Return to top

Summary

Initializes a new instance of the StringBuilder class from the specified substring and capacity.

C# Syntax:

public StringBuilder(    string value,    int startIndex,    int length,    int capacity );

value

The string that contains the substring used to initialize the value of the instance. If value is null, the new StringBuilder will contain the empty string (that is, it contains String.Empty).

startIndex

The position where the substring begins.

length

The number of characters in the substring.

capacity

The suggested starting size of the StringBuilder. The maximum number of characters the current string can contain is set by capacity.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	capacity is less than zero. -or- startIndex plus length is not a position within value.
ArgumentNullException	value is null or the empty string and startIndex, length, and capacity are not zero.

Return to top

Summary

Gets or sets the maximum number of characters that can be contained in the memory allocated by the current instance.

C# Syntax:

public int Capacity {get; set;}

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	Capacity is less than the current length of this instance. -or- Capacity is greater than the maximum capacity.

StringBuilder.Capacity does not affect the string value of the current instance. StringBuilder.Capacity can be decreased as long as it is not less than StringBuilder.Length.

The StringBuilder dynamically allocates more space when required and increases StringBuilder.Capacity accordingly. For performance reasons, a StringBuilder might allocate more memory than needed. The amount of memory allocated is implementation-specific.

Return to top

Summary

Gets or sets the character at the specified character position in this instance.

C# Syntax:

No member name public char this[int index] {get; set;}

index

The position of the character.

The index parameter is the position of a character within the StringBuilder. The first character in the string is at index 0. The length of a string is the number of characters it contains. The last accessible character of a StringBuilder instance is at index StringBuilder.Length - 1.

Return to top

Summary

Gets or sets the length of this instance.

C# Syntax:

public int Length {get; set;}

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The value specified for a set operation is less than zero or greater than Int32.MaxValue.

If the specified length is less than the current length, this instance is truncated to the specified length. If the specified length is greater than the current length, the end of the string value of this instance is padded with spaces. If the specified length is greater than the current capacity, StringBuilder.Capacity is set to the specified length.

Return to top

Summary

Gets the maximum capacity of this instance.

C# Syntax:

public int MaxCapacity {get;}

Notes to implementors: The maximum capacity for this implementation is Int32.MaxValue. However, this value is implementation-specific and might be different in other or later implementations.

Return to top

Summary

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

C# Syntax:

public StringBuilder Append(    bool value );

value

A Boolean value.

Return Value:

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

Boolean.ToString is used to get a string representation of the Boolean value. The capacity is adjusted as needed.

Return to top

Summary

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

C# Syntax:

public StringBuilder Append(    byte value );

value

The integer to append.

Return Value:

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

Byte.ToString is used to get a string representation of the integer. The capacity is adjusted as needed.

Return to top

Summary

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

C# Syntax:

public StringBuilder Append(    char value );

value

The Unicode character to append.

Return Value:

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

The capacity is adjusted as needed.

Return to top

Summary

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

C# Syntax:

public StringBuilder Append(    char[] value );

value

A character array to append.

Return Value:

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

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 capacity is adjusted as needed.

Return to top

Summary

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

C# Syntax:

public StringBuilder Append(    decimal value );

value

The number to append.

Return Value:

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

Decimal.ToString is used to get a string representation of the number. The capacity is adjusted as needed.

Return to top

Summary

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

C# Syntax:

public StringBuilder Append(    double value );

value

The number to append.

Return Value:

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

Double.ToString is used to get a string representation of the number. The capacity is adjusted as needed.

Return to top

Summary

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

C# Syntax:

public StringBuilder Append(    short value );

value

The integer to append.

Return Value:

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

Int16.ToString is used to get a string representation of the integer. The capacity is adjusted as needed.

Return to top

Summary

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

C# Syntax:

public StringBuilder Append(    int value );

value

The integer to append.

Return Value:

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

Int32.ToString is used to get a string representation of the integer. The capacity is adjusted as needed.

Return to top

Summary

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

C# Syntax:

public StringBuilder Append(    long value );

value

The integer to append.

Return Value:

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

Int64.ToString is used to get a string representation of the integer. The capacity is adjusted as needed.

Return to top

Summary

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

C# Syntax:

public StringBuilder Append(    object value );

value

The object to append.

Return Value:

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

Object.ToString is used to get a string representation of the integer. If value is null, no changes are made.

The capacity is adjusted as needed.

Return to top

Summary

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

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public StringBuilder Append(    sbyte value );

value

The integer to append.

Return Value:

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

SByte.ToString is used to get a string representation of the integer. The capacity is adjusted as needed.

Return to top

Summary

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

C# Syntax:

public StringBuilder Append(    float value );

value

The number to append.

Return Value:

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

Single.ToString is used to get a string representation of the number. The capacity is adjusted as needed.

Return to top

Summary

Appends a copy of the specified string to the end of this instance.

C# Syntax:

public StringBuilder Append(    string value );

value

The String to append.

Return Value:

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

If value is null, no changes are made.

The capacity is adjusted as needed.

Return to top

Summary

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

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public StringBuilder Append(    ushort value );

value

The integer to append.

Return Value:

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

UInt16.ToString is used to get a string representation of the integer. The capacity is adjusted as needed.

Return to top

Summary

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

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public StringBuilder Append(    uint value );

value

The integer to append.

Return Value:

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

UInt32.ToString is used to get a string representation of the integer. The capacity is adjusted as needed.

Return to top

Summary

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

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public StringBuilder Append(    ulong value );

value

The integer to append.

Return Value:

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

UInt64.ToString is used to get a string representation of the integer. The capacity is adjusted as needed.

Return to top

Summary

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

C# Syntax:

public StringBuilder Append(    char value,    int repeatCount );

value

The character to append.

repeatCount

The number of times to append value.

Return Value:

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

The capacity is adjusted as needed.

Return to top

Summary

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

C# Syntax:

public StringBuilder Append(    char[] value,    int startIndex,    int charCount );

value

The array of characters to append.

startIndex

The starting position in value .

charCount

The number of characters append.

Return Value:

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

Exceptions

Exception Type	Condition
ArgumentNullException	value is null, and startIndex and charCount are not zero.
ArgumentOutOfRangeException	charCount is less than zero. -or- startIndex is less than zero. -or- startIndex + charCount is less than the length of value.

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 capacity is adjusted as needed.

Return to top

Summary

Appends a copy of a specified substring to the end of this instance.

C# Syntax:

public StringBuilder Append(    string value,    int startIndex,    int count );

value

The String to append.

startIndex

The starting position in value .

count

The number of characters to append.

Return Value:

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

Exceptions

Exception Type	Condition
ArgumentNullException	value is null, and startIndex and count are not zero.
ArgumentOutOfRangeException	count less than zero. -or- startIndex less than zero. -or- startIndex + count is less than the length of value.

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 capacity is adjusted as needed.

Return to top

Summary

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.

C# Syntax:

public StringBuilder AppendFormat(    string format,    object arg0 );

format

A string containing zero or more format specifications.

arg0

An object to format.

Return Value:

A reference to this instance with format appended. Any format specification in format is replaced by the string representation of the corresponding object argument.

Exceptions

Exception Type	Condition
ArgumentNullException	arg0 is null.
FormatException	format is invalid.

This method replaces zero or more format specifications with the appropriately formatted value of an object. The 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 arg0 implements IFormattable then arg0.Format (format, null) provides the formatting; otherwise Object.ToString provides the formatting. If arg0 is null then an empty string is used in its place.

To 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.

Object.ToString is Used if the Format String is Omitted: The format string within a format specification is optional: {N[,M][:FormatString]}. When FormatString is omitted, the Object.ToString method of the argument specified by N is used to replace the format specification. If M is given, then the result of Object.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 will be "Brad's dog has 42 fleas."

Return to top

Summary

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.

C# Syntax:

public StringBuilder AppendFormat(    string format,    params object[] args );

format

A string containing zero or more format specifications.

args

An array of objects to format.

Return Value:

A reference to this instance with format appended. Any format specification in format is replaced by the string representation of the corresponding object argument.

Exceptions

Exception Type	Condition
ArgumentNullException	Any of the object parameters is null.
FormatException	format is invalid.

The 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, null) provides the formatting; otherwise Object.ToString provides the formatting. If args[N] is null then an empty string is used in its place.

To 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.

Object.ToString is Used if the Format String is Omitted: The format string within a format specification is optional: {N[,M][:FormatString]}. When FormatString is omitted, the Object.ToString method of the argument specified by N is used to replace the format specification. If M is given, then the result of Object.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 will be "Brad's dog has 42 fleas."

Return to top

Summary

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.

C# Syntax:

public StringBuilder AppendFormat(    IFormatProvider provider,    string format,    params object[] args );

provider

The IFormatProvider used to change the way in which formatting codes are interpreted by a type.

format

A string containing zero or more format specifications.

args

An array of objects to format.

Return Value:

A reference to this instance with format appended. Any format specification in format is replaced by the string representation of the corresponding object argument.

Exceptions

Exception Type	Condition
ArgumentNullException	Any of the object parameters is null.
FormatException	format is invalid.

The 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, null) provides the formatting; otherwise args[N].ToString( ) provides the formatting. If args[N] is null then an empty string is used in its place.

The provider parameter specifies the format provider that the NumberFormatInfo is obtained from. NumberFormatInfo supplies information such as the characters to use for decimal and group separators, and determines the spelling and placement of currency symbols in monetary values. If provider is null, the numeric format information is obtained from the current culture.

To 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.

Object.ToString is Used if the Format String is Omitted: The format string within a format specification is optional: {N[,M][:FormatString]}. When FormatString is omitted, the Object.ToString method of the argument specified by N is used to replace the format specification. If M is given, then the result of Object.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 will be "Brad's dog has 42 fleas."

Return to top

Summary

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.

C# Syntax:

public StringBuilder AppendFormat(    string format,    object arg0,    object arg1 );

format

A string containing zero or more format specifications.

arg0

The first object to format.

arg1

The second object to format.

Return Value:

A reference to this instance with format appended. Any format specification in format is replaced by the string representation of the corresponding object argument.

Exceptions

Exception Type	Condition
ArgumentNullException	Any of the object parameters is null.
FormatException	format is invalid.

The 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 argN implements IFormattable then argN.Format (format, null) provides the formatting; otherwise Object.ToString provides the formatting. If arg0 or arg1 is null then an empty string is used in its place.

To 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.

Object.ToString is Used if the Format String is Omitted: The format string within a format specification is optional: {N[,M][:FormatString]}. When FormatString is omitted, the Object.ToString method of the argument specified by N is used to replace the format specification. If M is given, then the result of Object.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 will be "Brad's dog has 42 fleas."

Return to top

Summary

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.

C# Syntax:

public StringBuilder AppendFormat(    string format,    object arg0,    object arg1,    object arg2 );

format

A string containing zero or more format specifications.

arg0

The first object to format.

arg1

The second object to format.

arg2

The third object to format.

Return Value:

A reference to this instance with format appended. Any format specification in format is replaced by the string representation of the corresponding object argument.

Exceptions

Exception Type	Condition
ArgumentNullException	Any of the object parameters is null.
FormatException	format is invalid.

The 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 argN implements IFormattable then argN.Format (format, null) provides the formatting; otherwise Object.ToString provides the formatting. If arg0, arg1, or arg2 is null then an empty string is used in its place.

To 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.

Object.ToString is Used if the Format String is Omitted: The format string within a format specification is optional: {N[,M][:FormatString]}. When FormatString is omitted, the Object.ToString method of the argument specified by N is used to replace the format specification. If M is given, then the result of Object.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 will be "Brad's dog has 42 fleas."

Return to top

Summary

Ensures that the capacity of this instance of StringBuilder is at least the specified value.

C# Syntax:

public int EnsureCapacity(    int capacity );

capacity

The minimum capacity to ensure.

Return Value:

The current capacity of this instance.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	capacity is less than zero.

If the number of characters in this instance is less than or equal to the capacity parameter, memory for this instance is reallocated to hold at least capacity number of characters; otherwise, no memory is changed. In either case, the current value of the StringBuilder.Capacity property is returned.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Returns a value indicating whether this instance is equal to a specified object.

C# Syntax:

public bool Equals(    StringBuilder sb );

sb

An object to compare with this instance or null.

Return Value:

true if this instance and sb have the same value; otherwise, false.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~StringBuilder();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Inserts the string representation of a Boolean value into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    bool value );

index

The position at which to insert.

value

The value to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

Boolean.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the empty string is inserted.

Return to top

Summary

Inserts the string representation of a specified 8-bit unsigned integer into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    byte value );

index

The position at which to insert.

value

The value to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

Byte.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the empty string is inserted.

Return to top

Summary

Inserts the string representation of a specified Unicode character into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    char value );

index

The position at which to insert.

value

The value to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

Char.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the empty string is inserted.

Return to top

Summary

Inserts the string representation of a specified array of Unicode characters into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    char[] value );

index

The position at which to insert.

value

The character array to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance.

Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the StringBuilder is not changed.

Return to top

Summary

Inserts the string representation of a decimal number into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    decimal value );

index

The position at which to insert.

value

The value to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

Decimal.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the empty string is inserted.

Return to top

Summary

Inserts the string representation of a double-precision floating-point number into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    double value );

index

The position at which to insert.

value

The value to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

Double.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the empty string is inserted.

Return to top

Summary

Inserts the string representation of a specified 16-bit signed integer into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    short value );

index

The position at which to insert.

value

The value to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

Int16.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the empty string is inserted.

Return to top

Summary

Inserts the string representation of a specified 32-bit signed integer into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    int value );

index

The position at which to insert.

value

The value to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

Int32.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the empty string is inserted.

Return to top

Summary

Inserts the string representation of a 64-bit signed integer into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    long value );

index

The position at which to insert.

value

The value to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

Int64.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the empty string is inserted.

Return to top

Summary

Inserts the string representation of an object into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    object value );

index

The position at which to insert.

value

The object to insert or null.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	index is greater than the length of this instance. -or- index is less than zero.

Object.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the value of this instance is unchanged.

Return to top

Summary

Inserts the string representation of a specified 8-bit signed integer into this instance at the specified character position.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public StringBuilder Insert(    int index,    sbyte value );

index

The position at which to insert.

value

The value to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

SByte.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the empty string is inserted.

Return to top

Summary

Inserts the string representation of a single-precision floating point number into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    float value );

index

The position at which to insert.

value

The value to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

Single.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the empty string is inserted.

Return to top

Summary

Inserts a string into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    string value );

index

The position at which to insert.

value

The string to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

Boolean.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value equals String.Empty, the StringBuilder is not changed. If value is null, the empty string is inserted.

Return to top

Summary

Inserts the string representation of a 16-bit unsigned integer into this instance at the specified character position.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public StringBuilder Insert(    int index,    ushort value );

index

The position at which to insert.

value

The value to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

UInt16.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the empty string is inserted.

Return to top

Summary

Inserts the string representation of a 32-bit unsigned integer into this instance at the specified character position.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public StringBuilder Insert(    int index,    uint value );

index

The position at which to insert.

value

The value to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

UInt32.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the empty string is inserted.

Return to top

Summary

Inserts the string representation of a 64-bit unsigned integer into this instance at the specified character position.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public StringBuilder Insert(    int index,    ulong value );

index

The position at which to insert.

value

The value to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index is not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

UInt64.ToString is used to get a string representation of value. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

If value is null, the empty string is inserted.

Return to top

Summary

Inserts one or more copies of a specified string into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    string value,    int count );

index

The position at which to insert.

value

The string to insert.

count

The number of times to insert value.

Return Value:

A reference to this instance after insertion has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null and index and count are not zero.
ArgumentOutOfRangeException	index is less than zero or greater than the length of this instance. -or- count is less than one.

Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

Return to top

Summary

Inserts the string representation of a specified subarray of Unicode characters into this instance at the specified character position.

C# Syntax:

public StringBuilder Insert(    int index,    char[] value,    int startIndex,    int charCount );

index

The position at which to insert.

value

A character array.

startIndex

The starting index within value.

charCount

The number of characters to insert.

Return Value:

A reference to this instance after the insert operation has occurred.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null, and startIndex and charCount are not zero.
ArgumentOutOfRangeException	index, startIndex, or charCount is less than zero. -or- index is greater than the length of this instance. -or- startIndex plus charCount is not a position within value.

Existing characters are shifted to make room for the new text. The capacity is adjusted as needed.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Removes the specified range of characters from this instance.

C# Syntax:

public StringBuilder Remove(    int startIndex,    int length );

startIndex

The position where removal begins.

length

The number of characters to remove.

Return Value:

A reference to this instance after the excise operation has occurred.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	If startIndex or length is less than zero, or startIndex + length is greater than the length of this instance.

The current method removes the specified range of characters from the current instance. The characters at (startIndex + length) are moved to startIndex, and the string value of the current instance is shortened by length. The capacity is unaffected.

Replace(string oldValue, null) can be used to remove all instances of a string from a StringBuilder.

Return to top

Summary

Replaces all occurrences of a specified character in this instance with another specified character.

C# Syntax:

public StringBuilder Replace(    char oldChar,    char newChar );

oldChar

The character to replace.

newChar

The character that replaces oldChar.

Return Value:

A reference to this instance with oldChar replaced by newChar.

A StringBuilder with all instances of oldChar replaced with newChar. The size of the StringBuilder is unchanged because characters are only replaced. This method is case-sensitive.

Return to top

Summary

Replaces all occurrences of a specified substring in this instance with another specified string.

C# Syntax:

public StringBuilder Replace(    string oldValue,    string newValue );

oldValue

The string to replace.

newValue

The string that replaces oldValue.

Return Value:

A reference to this instance with all instances of oldValue replaced by newValue.

Exceptions

Exception Type	Condition
ArgumentNullException	oldValue is null.
ArgumentException	The length of oldvalue is zero.

The strings to replace are checked on an ordinal basis (for example, not culture-aware). If newValue is null, instances of oldValue are removed (for example, replaced by nothing). This method is case-sensitive.

Return to top

Summary

Replaces all occurrences of a specified character in a substring of this instance with another specified character.

C# Syntax:

public StringBuilder Replace(    char oldChar,    char newChar,    int startIndex,    int count );

oldChar

The character to replace.

newChar

The character that replaces oldChar.

startIndex

The position where the substring begins.

count

The length of the substring.

Return Value:

A reference to this instance with oldChar replaced by newChar in the range startIndex + count -1.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	startIndex + count is greater than the length of the value of this instance. -or- startIndex or count is less than zero.

The size of the StringBuilder is unchanged because characters are only replaced. Characters are replaced in the range from startIndex to startIndex + count - 1. This method is case-sensitive.

Return to top

Summary

Replaces all occurrences of a specified string in a substring of this instance with another specified string.

C# Syntax:

public StringBuilder Replace(    string oldValue,    string newValue,    int startIndex,    int count );

oldValue

The string to replace or null.

newValue

The string that replaces oldValue or null.

startIndex

The position where the substring begins.

count

The length of the substring.

Return Value:

A reference to this instance with all instances of oldValue replaced by newValue in the range from startIndex to startIndex + count - 1.

Exceptions

Exception Type	Condition
ArgumentNullException	oldValue is null.
ArgumentException	The length of oldvalue is zero.
ArgumentOutOfRangeException	startIndex or count is less than zero. -or- startIndex plus count indicates a character position not within oldValue.

The strings to replace are checked on an ordinal basis (for example, not culture-aware). If newValue is null, instances of oldValue are removed. This method is case-sensitive.

Return to top

Summary

Converts this instance to a String.

C# Syntax:

public override string ToString();

Return Value:

A string whose value is the same as this instance.

Return to top

Summary

Converts a substring of the current StringBuilder to a String.

C# Syntax:

public string ToString(    int startIndex,    int length );

startIndex

The starting position of the substring.

length

The length of the substring.

Return Value:

A string whose value is the same as the specified substring of the value of this instance.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	startIndex or length is less than zero. -or- The sum of startIndex and length is greater than the length of the current instance.

Return to top

Top of page