This topic has not yet been rated - Rate this topic

StringBuilder.EnsureCapacity Method

April 12, 2014

Ensures that the capacity of this instance of StringBuilder is at least the specified value.

Namespace:  System.Text
Assembly:  mscorlib (in mscorlib.dll)
public int EnsureCapacity(
	int capacity
)

Parameters

capacity
Type: System.Int32
The minimum capacity to ensure.

Return Value

Type: System.Int32
The new capacity of this instance.
ExceptionCondition
ArgumentOutOfRangeException

capacity is less than zero.

-or-

Enlarging the value of this instance would exceed its maximum capacity.

If the current capacity is less than the capacity parameter, memory for this instance is reallocated to hold at least capacity number of characters; otherwise, no memory is changed.

The following code example demonstrates the EnsureCapacity method.


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.