StringBuilder Class

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

System::Object
  System.Text::StringBuilder

Namespace:  System.Text
Assembly:  mscorlib (in mscorlib.dll)

[SerializableAttribute]
[ComVisibleAttribute(true)]
public ref class StringBuilder sealed : ISerializable

The StringBuilder type exposes the following members.

  NameDescription
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryStringBuilder()Initializes a new instance of the StringBuilder class.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryStringBuilder(Int32)Initializes a new instance of the StringBuilder class using the specified capacity.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryStringBuilder(String)Initializes a new instance of the StringBuilder class using the specified string.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryStringBuilder(Int32, Int32)Initializes a new instance of the StringBuilder class that starts with a specified capacity and can grow to a specified maximum.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryStringBuilder(String, Int32)Initializes a new instance of the StringBuilder class using the specified string and capacity.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryStringBuilder(String, Int32, Int32, Int32)Initializes a new instance of the StringBuilder class from the specified substring and capacity.
Top

  NameDescription
Public propertySupported by the XNA FrameworkSupported by Portable Class LibraryCapacityGets or sets the maximum number of characters that can be contained in the memory allocated by the current instance.
Public propertySupported by the XNA FrameworkSupported by Portable Class LibraryCharsGets or sets the character at the specified character position in this instance.
Public propertySupported by the XNA FrameworkSupported by Portable Class LibraryLengthGets or sets the length of the current StringBuilder object.
Public propertyMaxCapacityGets the maximum capacity of this instance.
Top

  NameDescription
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(Boolean)Appends the string representation of a specified Boolean value to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(Byte)Appends the string representation of a specified 8-bit unsigned integer to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(Char)Appends the string representation of a specified Unicode character to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(array<Char>)Appends the string representation of the Unicode characters in a specified array to this instance.
Public methodAppend(Decimal)Appends the string representation of a specified decimal number to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(Double)Appends the string representation of a specified double-precision floating-point number to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(Int16)Appends the string representation of a specified 16-bit signed integer to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(Int32)Appends the string representation of a specified 32-bit signed integer to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(Int64)Appends the string representation of a specified 64-bit signed integer to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(Object)Appends the string representation of a specified object to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(SByte)Appends the string representation of a specified 8-bit signed integer to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(Single)Appends the string representation of a specified single-precision floating-point number to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(String)Appends a copy of the specified string to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(UInt16)Appends the string representation of a specified 16-bit unsigned integer to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(UInt32)Appends the string representation of a specified 32-bit unsigned integer to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(UInt64)Appends the string representation of a specified 64-bit unsigned integer to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(Char, Int32)Appends a specified number of copies of the string representation of a Unicode character to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(array<Char>, Int32, Int32)Appends the string representation of a specified subarray of Unicode characters to this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppend(String, Int32, Int32)Appends a copy of a specified substring to this instance.
Public methodAppendFormat(String, Object)Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a single argument.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppendFormat(String, array<Object>)Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding argument in a parameter array.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppendFormat(IFormatProvider, String, array<Object>)Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding argument in a parameter array using a specified format provider.
Public methodAppendFormat(String, Object, Object)Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of two arguments.
Public methodAppendFormat(String, Object, Object, Object)Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of three arguments.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppendLine()Appends the default line terminator to the end of the current StringBuilder object.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryAppendLine(String)Appends a copy of the specified string followed by the default line terminator to the end of the current StringBuilder object.
Public methodClearRemoves all characters from the current StringBuilder instance.
Public methodCopyToCopies the characters from a specified segment of this instance to a specified segment of a destination Char array.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryEnsureCapacityEnsures that the capacity of this instance of StringBuilder is at least the specified value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryEquals(StringBuilder)Returns a value indicating whether this instance is equal to a specified object.
Protected methodSupported by the XNA FrameworkSupported by Portable Class LibraryFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodInsert(Int32, Boolean)Inserts the string representation of a Boolean value into this instance at the specified character position.
Public methodInsert(Int32, Byte)Inserts the string representation of a specified 8-bit unsigned integer into this instance at the specified character position.
Public methodInsert(Int32, Char)Inserts the string representation of a specified Unicode character into this instance at the specified character position.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryInsert(Int32, array<Char>)Inserts the string representation of a specified array of Unicode characters into this instance at the specified character position.
Public methodInsert(Int32, Decimal)Inserts the string representation of a decimal number into this instance at the specified character position.
Public methodInsert(Int32, Double)Inserts the string representation of a double-precision floating-point number into this instance at the specified character position.
Public methodInsert(Int32, Int16)Inserts the string representation of a specified 16-bit signed integer into this instance at the specified character position.
Public methodInsert(Int32, Int32)Inserts the string representation of a specified 32-bit signed integer into this instance at the specified character position.
Public methodInsert(Int32, Int64)Inserts the string representation of a 64-bit signed integer into this instance at the specified character position.
Public methodInsert(Int32, Object)Inserts the string representation of an object into this instance at the specified character position.
Public methodInsert(Int32, SByte)Inserts the string representation of a specified 8-bit signed integer into this instance at the specified character position.
Public methodInsert(Int32, Single)Inserts the string representation of a single-precision floating point number into this instance at the specified character position.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryInsert(Int32, String)Inserts a string into this instance at the specified character position.
Public methodInsert(Int32, UInt16)Inserts the string representation of a 16-bit unsigned integer into this instance at the specified character position.
Public methodInsert(Int32, UInt32)Inserts the string representation of a 32-bit unsigned integer into this instance at the specified character position.
Public methodInsert(Int32, UInt64)Inserts the string representation of a 64-bit unsigned integer into this instance at the specified character position.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryInsert(Int32, String, Int32)Inserts one or more copies of a specified string into this instance at the specified character position.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryInsert(Int32, array<Char>, Int32, Int32)Inserts the string representation of a specified subarray of Unicode characters into this instance at the specified character position.
Protected methodSupported by the XNA FrameworkSupported by Portable Class LibraryMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryRemoveRemoves the specified range of characters from this instance.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryReplace(Char, Char)Replaces all occurrences of a specified character in this instance with another specified character.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryReplace(String, String)Replaces all occurrences of a specified string in this instance with another specified string.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryReplace(Char, Char, Int32, Int32)Replaces, within a substring of this instance, all occurrences of a specified character with another specified character.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryReplace(String, String, Int32, Int32)Replaces, within a substring of this instance, all occurrences of a specified string with another specified string.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryToString()Converts the value of this instance to a String. (Overrides Object::ToString().)
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryToString(Int32, Int32)Converts the value of a substring of this instance to a String.
Top

  NameDescription
Explicit interface implemetationPrivate methodISerializable::GetObjectDataInfrastructure. Populates a System.Runtime.Serialization::SerializationInfo object with the data necessary to deserialize the current StringBuilder object.
Top

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 instance 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 Capacity property or EnsureCapacity method, 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 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.

Memory Allocation

The default capacity for this implementation is 16, and the default maximum capacity is Int32::MaxValue.

A StringBuilder object can allocate more memory to store characters when the value of an instance is enlarged, and the capacity is adjusted accordingly. For example, the Append, AppendFormat, EnsureCapacity, Insert, and Replace methods can enlarge the value of an instance.

The amount of memory allocated is implementation-specific, and an exception (either ArgumentOutOfRangeException or OutOfMemoryException) is thrown if the amount of memory required is greater than the maximum capacity.

Notes to Callers

In the .NET Framework 4, when you instantiate the StringBuilder object by calling the StringBuilder constructor, both the length and the capacity of the StringBuilder instance can grow beyond the value of its MaxCapacity property. This can occur particularly when you call the Append and AppendFormat methods to append small strings.

The following example shows how to call many of the methods defined by the StringBuilder class.


using namespace System;
using namespace System::Text;

int main()
{
    // Create a StringBuilder that expects to hold 50 characters.
    // Initialize the StringBuilder with "ABC".
    StringBuilder^ sb = gcnew StringBuilder("ABC", 50);

    // Append three characters (D, E, and F) to the end of the
    // StringBuilder.
    sb->Append(gcnew array<Char>{'D', 'E', 'F'});

    // Append a format string to the end of the StringBuilder.
    sb->AppendFormat("GHI{0}{1}", (Char)'J', (Char)'k');

    // Display the number of characters in the StringBuilder
    // and its string.
    Console::WriteLine("{0} chars: {1}", sb->Length, sb->ToString());

    // Insert a string at the beginning of the StringBuilder.
    sb->Insert(0, "Alphabet: ");

    // Replace all lowercase k's with uppercase K's.
    sb->Replace('k', 'K');

    // Display the number of characters in the StringBuilder
    // and its string.
    Console::WriteLine("{0} chars: {1}", sb->Length, sb->ToString());
}

// This code produces the following output.
//
// 11 chars: ABCDEFGHIJk
// 21 chars: Alphabet: ABCDEFGHIJK


.NET Framework

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

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft