This documentation is archived and is not being maintained.

StringBuilder.Capacity Property

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

[Visual Basic]
Public Property Capacity As Integer
[C#]
public int Capacity {get; set;}
[C++]
public: __property int get_Capacity();
public: __property void set_Capacity(int);
[JScript]
public function get Capacity() : int;
public function set Capacity(int);

Property Value

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

Exceptions

Exception Type Condition
ArgumentOutOfRangeException The value specified for a set operation is less than the current length of this instance.

-or-

The value specified for a set operation is greater than the maximum capacity.

Remarks

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

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

Example

[Visual Basic] 
' This example demonstrates StringBuilder.EnsureCapacity
'                           StringBuilder.Capacity
'                           StringBuilder.Length
'                           StringBuilder.Equals
Imports System
Imports System.Text

Class Sample
   Public Shared Sub Main()
      Dim sb1 As New StringBuilder("abc")
      Dim sb2 As New StringBuilder("abc", 16)
      
      Console.WriteLine()
      Console.WriteLine("a1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity)
      Console.WriteLine("a2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity)
      Console.WriteLine("a3) sb1.ToString() = ""{0}"", sb2.ToString() = ""{1}""", _
                             sb1.ToString(),           sb2.ToString())
      Console.WriteLine("a4) sb1 equals sb2: {0}", sb1.Equals(sb2))
      
      Console.WriteLine()
      Console.WriteLine("Ensure sb1 has a capacity of at least 50 characters.")
      sb1.EnsureCapacity(50)
      
      Console.WriteLine()
      Console.WriteLine("b1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity)
      Console.WriteLine("b2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity)
      Console.WriteLine("b3) sb1.ToString() = ""{0}"", sb2.ToString() = ""{1}""", _
                             sb1.ToString(),           sb2.ToString())
      Console.WriteLine("b4) sb1 equals sb2: {0}", sb1.Equals(sb2))
      
      Console.WriteLine()
      Console.WriteLine("Set the length of sb1 to zero.")
      Console.WriteLine("Set the capacity of sb2 to 51 characters.")
      sb1.Length = 0
      sb2.Capacity = 51
      
      Console.WriteLine()
      Console.WriteLine("c1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity)
      Console.WriteLine("c2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity)
      Console.WriteLine("c3) sb1.ToString() = ""{0}"", sb2.ToString() = ""{1}""", _
                             sb1.ToString(),           sb2.ToString())
      Console.WriteLine("c4) sb1 equals sb2: {0}", sb1.Equals(sb2))
   End Sub 'Main
End Class 'Sample
'
'This example produces the following results:
'
'a1) sb1.Length = 3, sb1.Capacity = 16
'a2) sb2.Length = 3, sb2.Capacity = 16
'a3) sb1.ToString() = "abc", sb2.ToString() = "abc"
'a4) sb1 equals sb2: True
'
'Ensure sb1 has a capacity of at least 50 characters.
'
'b1) sb1.Length = 3, sb1.Capacity = 51
'b2) sb2.Length = 3, sb2.Capacity = 16
'b3) sb1.ToString() = "abc", sb2.ToString() = "abc"
'b4) sb1 equals sb2: False
'
'Set the length of sb1 to zero.
'Set the capacity of sb2 to 51 characters.
'
'c1) sb1.Length = 0, sb1.Capacity = 51
'c2) sb2.Length = 3, sb2.Capacity = 51
'c3) sb1.ToString() = "", sb2.ToString() = "abc"
'c4) sb1 equals sb2: False
'

[C#] 
// This example demonstrates StringBuilder.EnsureCapacity
//                           StringBuilder.Capacity
//                           StringBuilder.Length
//                           StringBuilder.Equals
using System;
using System.Text;

class Sample 
{
    public static void Main() 
    {
    StringBuilder sb1 = new StringBuilder("abc");
    StringBuilder sb2 = new StringBuilder("abc", 16);

    Console.WriteLine();
    Console.WriteLine("a1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity);
    Console.WriteLine("a2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity);
    Console.WriteLine("a3) sb1.ToString() = \"{0}\", sb2.ToString() = \"{1}\"", 
                           sb1.ToString(),       sb2.ToString());
    Console.WriteLine("a4) sb1 equals sb2: {0}", sb1.Equals(sb2));

    Console.WriteLine();
    Console.WriteLine("Ensure sb1 has a capacity of at least 50 characters.");
    sb1.EnsureCapacity(50);

    Console.WriteLine();
    Console.WriteLine("b1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity);
    Console.WriteLine("b2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity);
    Console.WriteLine("b3) sb1.ToString() = \"{0}\", sb2.ToString() = \"{1}\"", 
                           sb1.ToString(),       sb2.ToString());
    Console.WriteLine("b4) sb1 equals sb2: {0}", sb1.Equals(sb2));

    Console.WriteLine();
    Console.WriteLine("Set the length of sb1 to zero.");
    Console.WriteLine("Set the capacity of sb2 to 51 characters.");
    sb1.Length = 0;
    sb2.Capacity = 51;

    Console.WriteLine();
    Console.WriteLine("c1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity);
    Console.WriteLine("c2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity);
    Console.WriteLine("c3) sb1.ToString() = \"{0}\", sb2.ToString() = \"{1}\"", 
                           sb1.ToString(),       sb2.ToString());
    Console.WriteLine("c4) sb1 equals sb2: {0}", sb1.Equals(sb2));
    }
}
/*
This example produces the following results:

a1) sb1.Length = 3, sb1.Capacity = 16
a2) sb2.Length = 3, sb2.Capacity = 16
a3) sb1.ToString() = "abc", sb2.ToString() = "abc"
a4) sb1 equals sb2: True

Ensure sb1 has a capacity of at least 50 characters.

b1) sb1.Length = 3, sb1.Capacity = 51
b2) sb2.Length = 3, sb2.Capacity = 16
b3) sb1.ToString() = "abc", sb2.ToString() = "abc"
b4) sb1 equals sb2: False

Set the length of sb1 to zero.
Set the capacity of sb2 to 51 characters.

c1) sb1.Length = 0, sb1.Capacity = 51
c2) sb2.Length = 3, sb2.Capacity = 51
c3) sb1.ToString() = "", sb2.ToString() = "abc"
c4) sb1 equals sb2: False
*/

[C++] 
// This example demonstrates StringBuilder.EnsureCapacity
//                           StringBuilder.Capacity
//                           StringBuilder.Length
//                           StringBuilder.Equals
#using <mscorlib.dll>
using namespace System;
using namespace System::Text;

int main() 
    {
    StringBuilder* sb1 = new StringBuilder(S"abc");
    StringBuilder* sb2 = new StringBuilder(S"abc", 16);

    Console::WriteLine();
    Console::WriteLine(S"a1) sb1->Length = {0}, sb1->Capacity = {1}", __box(sb1->Length), __box(sb1->Capacity));
    Console::WriteLine(S"a2) sb2->Length = {0}, sb2->Capacity = {1}", __box(sb2->Length), __box(sb2->Capacity));
    Console::WriteLine(S"a3) sb1 = \"{0}\", sb2 = \"{1}\"",sb1,sb2);
    Console::WriteLine(S"a4) sb1 equals sb2: {0}", __box(sb1->Equals(sb2)));

    Console::WriteLine();
    Console::WriteLine(S"Ensure sb1 has a capacity of at least 50 characters.");
    sb1->EnsureCapacity(50);

    Console::WriteLine();
    Console::WriteLine(S"b1) sb1->Length = {0}, sb1->Capacity = {1}", __box(sb1->Length), __box(sb1->Capacity));
    Console::WriteLine(S"b2) sb2->Length = {0}, sb2->Capacity = {1}", __box(sb2->Length), __box(sb2->Capacity));
    Console::WriteLine(S"b3) sb1 = \"{0}\", sb2 = \"{1}\"",sb1,sb2);
    Console::WriteLine(S"b4) sb1 equals sb2: {0}", __box(sb1->Equals(sb2)));

    Console::WriteLine();
    Console::WriteLine(S"Set the length of sb1 to zero.");
    Console::WriteLine(S"Set the capacity of sb2 to 51 characters.");
    sb1->Length = 0;
    sb2->Capacity = 51;

    Console::WriteLine();
    Console::WriteLine(S"c1) sb1->Length = {0}, sb1->Capacity = {1}", __box(sb1->Length), __box(sb1->Capacity));
    Console::WriteLine(S"c2) sb2->Length = {0}, sb2->Capacity = {1}", __box(sb2->Length), __box(sb2->Capacity));
    Console::WriteLine(S"c3) sb1 = \"{0}\", sb2 = \"{1}\"",sb1,sb2);
    Console::WriteLine(S"c4) sb1 equals sb2: {0}", __box(sb1->Equals(sb2)));
}
/*
This example produces the following results:

a1) sb1.Length = 3, sb1.Capacity = 16
a2) sb2.Length = 3, sb2.Capacity = 16
a3) sb1.ToString() = "abc", sb2.ToString() = "abc"
a4) sb1 equals sb2: True

Ensure sb1 has a capacity of at least 50 characters.

b1) sb1.Length = 3, sb1.Capacity = 51
b2) sb2.Length = 3, sb2.Capacity = 16
b3) sb1.ToString() = "abc", sb2.ToString() = "abc"
b4) sb1 equals sb2: False

Set the length of sb1 to zero.
Set the capacity of sb2 to 51 characters.

c1) sb1.Length = 0, sb1.Capacity = 51
c2) sb2.Length = 3, sb2.Capacity = 51
c3) sb1.ToString() = "", sb2.ToString() = "abc"
c4) sb1 equals sb2: False
*/

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework, Common Language Infrastructure (CLI) Standard

See Also

StringBuilder Class | StringBuilder Members | System.Text Namespace

Show: