This topic has not yet been rated - Rate this topic

StringBuilder.Capacity Property

April 12, 2014

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

Namespace:  System.Text
Assembly:  mscorlib (in mscorlib.dll)
public int Capacity { get; set; }

Property Value

Type: System.Int32
The maximum number of characters that can be contained in the memory allocated by the current instance.
ExceptionCondition
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.


using System;
using System.Text;

class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      StringBuilder sb1 = new StringBuilder("abc");
      StringBuilder sb2 = new StringBuilder("abc", 16);

      outputBlock.Text += "\n";
      outputBlock.Text += String.Format("a1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity) + "\n";
      outputBlock.Text += String.Format("a2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity) + "\n";
      outputBlock.Text += String.Format("a3) sb1.ToString() = \"{0}\", sb2.ToString() = \"{1}\"",
                             sb1.ToString(), sb2.ToString()) + "\n";
      outputBlock.Text += String.Format("a4) sb1 equals sb2: {0}", sb1.Equals(sb2)) + "\n";

      outputBlock.Text += "\n";
      outputBlock.Text += "Ensure sb1 has a capacity of at least 50 characters." + "\n";
      sb1.EnsureCapacity(50);

      outputBlock.Text += "\n";
      outputBlock.Text += String.Format("b1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity) + "\n";
      outputBlock.Text += String.Format("b2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity) + "\n";
      outputBlock.Text += String.Format("b3) sb1.ToString() = \"{0}\", sb2.ToString() = \"{1}\"",
                             sb1.ToString(), sb2.ToString()) + "\n";
      outputBlock.Text += String.Format("b4) sb1 equals sb2: {0}", sb1.Equals(sb2)) + "\n";

      outputBlock.Text += "\n";
      outputBlock.Text += "Set the length of sb1 to zero." + "\n";
      outputBlock.Text += "Set the capacity of sb2 to 51 characters." + "\n";
      sb1.Length = 0;
      sb2.Capacity = 51;

      outputBlock.Text += "\n";
      outputBlock.Text += String.Format("c1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity) + "\n";
      outputBlock.Text += String.Format("c2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity) + "\n";
      outputBlock.Text += String.Format("c3) sb1.ToString() = \"{0}\", sb2.ToString() = \"{1}\"",
                             sb1.ToString(), sb2.ToString()) + "\n";
      outputBlock.Text += String.Format("c4) sb1 equals sb2: {0}", sb1.Equals(sb2)) + "\n";
   }
}
/*
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
*/


Windows Phone OS

Supported in: 8.1, 8.0, 7.1, 7.0

Windows Phone

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.