Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
Represents a mutable string of characters. This class cannot be inherited.
Inheritance Hierarchy
System. . :: . .Object
System.Text..::..StringBuilder
Namespace: System.Text
Assembly: mscorlib (in mscorlib.dll)
Syntax
'Declaration
Public NotInheritable Class StringBuilder
public sealed class StringBuilder
public ref class StringBuilder sealed
[<Sealed>]
type StringBuilder = class end
public final class StringBuilder
The StringBuilder type exposes the following members.
Constructors
| Name | Description | |
|---|---|---|
.gif "Public method") |
StringBuilder() () () () | Initializes a new instance of the StringBuilder class. |
|
StringBuilder(Int32) | Initializes a new instance of the StringBuilder class using the specified capacity. |
|
StringBuilder(String) | Initializes a new instance of the StringBuilder class using the specified string. |
|
StringBuilder(Int32, Int32) | Initializes a new instance of the StringBuilder class that starts with a specified capacity and can grow to a specified maximum. |
|
StringBuilder(String, Int32) | Initializes a new instance of the StringBuilder class using the specified string and capacity. |
|
StringBuilder(String, Int32, Int32, Int32) | Initializes a new instance of the StringBuilder class from the specified substring and capacity. |
Top
Properties
| Name | Description | |
|---|---|---|
.gif "Public property") |
Capacity | Gets or sets the maximum number of characters that can be contained in the memory allocated by the current instance. |
|
Item | |
|
Length | Gets or sets the length of the current StringBuilder object. |
|
MaxCapacity | Gets the maximum capacity of this instance. |
Top
Methods
| Name | Description | |
|---|---|---|
|
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 Unicode character to this instance. |
|
Append(array<Char> [] () [] []) | Appends the string representation of the Unicode characters in a specified array to this instance. |
|
Append(Double) | Appends the string representation of a specified double-precision floating-point number 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(SByte) | Appends the string representation of a specified 8-bit signed integer to this instance. |
|
Append(Single) | Appends the string representation of a specified single-precision floating-point number to this instance. |
|
Append(String) | Appends a copy of the specified 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(UInt64) | Appends the string representation of a specified 64-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(array<Char> [] () [] [], Int32, Int32) | Appends the string representation of a specified subarray of Unicode characters to this instance. |
|
Append(String, Int32, Int32) | Appends a copy of a specified substring to this instance. |
|
AppendLine() () () () | Appends the default line terminator to the end of the current StringBuilder object. |
|
AppendLine(String) | Appends a copy of the specified string followed by the default line terminator to the end of the current StringBuilder object. |
|
Clear | Removes all characters from the current StringBuilder instance. |
|
Equals(Object) | Determines whether the specified Object is equal to the current Object. (Inherited from Object.) |
|
GetHashCode | Serves as a hash function for a particular type. (Inherited from Object.) |
|
GetType | Gets the Type of the current instance. (Inherited from Object.) |
|
Insert(Int32, String, Int32) | Inserts one or more copies of a specified string into this instance at the specified character position. |
|
Insert(Int32, array<Char> [] () [] [], Int32, Int32) | 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(Char, Char) | Replaces all occurrences of a specified character in this instance with another specified character. |
|
Replace(String, String) | Replaces all occurrences of a specified string in this instance with another specified string. |
|
Replace(Char, Char, Int32, Int32) | Replaces, within a substring of this instance, all occurrences of a specified character with another specified character. |
|
Replace(String, String, Int32, Int32) | Replaces, within a substring of this instance, all occurrences of a specified string with another specified string. |
|
ToString() () () () | Converts the value of this instance to a String. (Overrides Object. . :: . .ToString() () () ().) |
|
ToString(Int32, Int32) | Converts the value of a substring of this instance to a String. |
Top
Remarks
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 after creation 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, and 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.
The capacity of a StringBuilder instance is the maximum number of characters the instance can store at any given time. The capacity 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 Capacity property, but it cannot be less than the value of the Length property.
If you don't specify capacity or maximum capacity when you initialize an instance of StringBuilder, implementation-specific default values are used. For more information, see the Memory Allocation section.
StringBuilder Functionality
The current size of a StringBuilder object is defined by its Length property. You can access the characters in the value of a StringBuilder object by using the Chars property. Index positions start from zero.
The StringBuilder class includes methods that can reduce the size of the current instance. The Clear method removes all characters and sets the Length property to zero. The Remove method deletes a range of characters.
The StringBuilder class also includes methods that can expand the current instance. The Append and AppendLine methods add data to the end of the StringBuilder object, and the Insert method inserts data at a specified character position in the current StringBuilder object. The AppendFormat method uses the composite formatting feature to add formatted text to the end of a StringBuilder object.
The Replace method replaces all occurrences of a character or a string in the entire StringBuilder object or in a particular character range.
You must convert the StringBuilder object to a String object before you can pass the string represented by the StringBuilder object to a method that has a String parameter or display it in the user interface. You perform this conversion by calling the ToString method.
Performance Considerations
A String object concatenation operation always creates a new object from the existing string and the new data. A StringBuilder object maintains a buffer to accommodate the concatenation of new data. New data is appended to the buffer if room is available; otherwise, a new, larger buffer is allocated, data from the original buffer is copied to the new buffer, and the new data is then appended to the new buffer.
The performance of a concatenation operation for a String or StringBuilder object depends on the frequency of memory allocations. A String concatenation operation always allocates memory, whereas a StringBuilder concatenation operation allocates memory only if the StringBuilder object buffer is too small to accommodate the new data. Use the String class if you are concatenating a fixed number of String objects. In that case, the compiler may even combine individual concatenation operations into a single operation. Use a StringBuilder object if you are concatenating an arbitrary number of strings; for example, if you're using a loop to concatenate a random number of strings of user input.
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.