StringBuilder.Capacity Property
[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
Gets or sets the maximum number of characters that can be contained in the memory allocated by the current instance.
Assembly: mscorlib (in mscorlib.dll)
Property Value
Type: System.Int32The maximum number of characters that can be contained in the memory allocated by the current instance.
| Exception | 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. |
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.
The following code example demonstrates the Capacity property.
Imports System.Text Class Example Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock) Dim sb1 As New StringBuilder("abc") Dim sb2 As New StringBuilder("abc", 16) outputBlock.Text &= vbCrLf outputBlock.Text += String.Format("a1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity) & vbCrLf outputBlock.Text += String.Format("a2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity) & vbCrLf outputBlock.Text += String.Format("a3) sb1.ToString() = ""{0}"", sb2.ToString() & vbCrLf = ""{1}""", _ sb1.ToString(), sb2.ToString()) outputBlock.Text += String.Format("a4) sb1 equals sb2: {0}", sb1.Equals(sb2)) & vbCrLf outputBlock.Text &= vbCrLf outputBlock.Text &= "Ensure sb1 has a capacity of at least 50 characters." & vbCrLf sb1.EnsureCapacity(50) outputBlock.Text &= vbCrLf outputBlock.Text += String.Format("b1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity) & vbCrLf outputBlock.Text += String.Format("b2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity) & vbCrLf outputBlock.Text += String.Format("b3) sb1.ToString() = ""{0}"", sb2.ToString() & vbCrLf = ""{1}""", _ sb1.ToString(), sb2.ToString()) outputBlock.Text += String.Format("b4) sb1 equals sb2: {0}", sb1.Equals(sb2)) & vbCrLf outputBlock.Text &= vbCrLf outputBlock.Text &= "Set the length of sb1 to zero." & vbCrLf outputBlock.Text &= "Set the capacity of sb2 to 51 characters." & vbCrLf sb1.Length = 0 sb2.Capacity = 51 outputBlock.Text &= vbCrLf outputBlock.Text += String.Format("c1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity) & vbCrLf outputBlock.Text += String.Format("c2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity) & vbCrLf outputBlock.Text += String.Format("c3) sb1.ToString() = ""{0}"", sb2.ToString() & vbCrLf = ""{1}""", _ sb1.ToString(), sb2.ToString()) outputBlock.Text += String.Format("c4) sb1 equals sb2: {0}", sb1.Equals(sb2)) & vbCrLf End Sub End Class ' The example displays the following output: ' 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 = 50 ' 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 = 50 ' c2) sb2.Length = 3, sb2.Capacity = 51 ' c3) sb1.ToString() = "", sb2.ToString() = "abc" ' c4) sb1 equals sb2: False