StringBuilder.EnsureCapacity Method
[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
Ensures that the capacity of this instance of StringBuilder is at least the specified value.
Assembly: mscorlib (in mscorlib.dll)
Parameters
- capacity
- Type: System.Int32
The minimum capacity to ensure.
| Exception | Condition |
|---|---|
| ArgumentOutOfRangeException | capacity is less than zero. -or- Enlarging the value of this instance would exceed its maximum capacity. |
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 */
Show: