StringBuilder Class

System.Text

Represents a mutable sequence of characters. This class provides methods to append, insert, remove, and replace characters and strings efficiently. It is particularly useful for building strings in performance-critical scenarios where multiple modifications are required.

Syntax


public ref class StringBuilder sealed : System::Object
{
    // Constructor overloads...
    public:
    StringBuilder();
    StringBuilder(int capacity);
    StringBuilder(int capacity, int maxCapacity);
    StringBuilder(string^ value);
    // ... other constructors

    // Property overloads...
    public:
    property int Capacity { int get(); void set(int value); }
    property int MaxCapacity { int get(); }
    property int Length { int get(); void set(int value); }
    property int Capacity { int get(); void set(int value); }

    // Method overloads...
    public:
    int Append(string^ value);
    int Append(char value);
    int Append(char* value, int count);
    // ... many more overloads for Append

    int Insert(int index, string^ value);
    int Insert(int index, char value);
    // ... other Insert overloads

    StringBuilder^ Remove(int startIndex, int length);
    StringBuilder^ Replace(char oldChar, char newChar);
    StringBuilder^ Replace(string^ oldValue, string^ newValue);
    // ... other Replace overloads

    string^ ToString();
    string^ ToString(int startIndex, int length);

    // ... other methods
};

Constructors

Name	Description
`StringBuilder()`	Initializes a new instance of the StringBuilder class.
`StringBuilder(int capacity)`	Initializes a new instance of the StringBuilder class using the specified initial capacity.
`StringBuilder(int capacity, int maxCapacity)`	Initializes a new instance of the StringBuilder class using the specified initial capacity and maximum capacity.
`StringBuilder(string value)`	Initializes a new instance of the StringBuilder class to the specified string value.

Properties

Name	Description
`Capacity`	Gets or sets the capacity of this instance.
`Length`	Gets or sets the current length of the string.
`MaxCapacity`	Gets the maximum capacity of this instance.

Methods

Name	Description
`Append(string value)`	Appends the string representation of a value to the end of this instance.
`Append(char value)`	Appends the specified character to the end of this instance.
`Insert(int index, string value)`	Inserts the specified string at the specified position in this instance.
`Remove(int startIndex, int length)`	Removes the specified number of characters from the current StringBuilder object starting at the specified index.
`Replace(char oldChar, char newChar)`	Replaces all occurrences of a specified character in this instance with another specified character.
`ToString()`	Converts to a `string`.

Remarks The StringBuilder class is designed for scenarios where a string is modified multiple times. For example, when processing a large text file or building a complex query string, using StringBuilder is significantly more efficient than repeated string concatenations using the + operator. Each modification to a string creates a new string object, which can lead to substantial overhead. StringBuilder manages an internal buffer that can grow as needed, minimizing memory allocations and copying. You can control the initial capacity and maximum capacity to fine-tune performance based on your expected usage.

Exceptions

ArgumentOutOfRangeException: Thrown when an index or length parameter is invalid.
ArgumentNullException: Thrown when a null string is passed to a method that does not allow it.

See Also