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.

Namespace: System.Text
Assembly: mscorlib (in mscorlib.dll)

Syntax

Public Function EnsureCapacity ( _
    capacity As Integer _
) As Integer
public int EnsureCapacity(
    int capacity
)

Parameters

Return Value

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

Exceptions

Exception Condition
ArgumentOutOfRangeException

capacity is less than zero.

-or-

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

Remarks

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.

Examples

The following code example demonstrates the EnsureCapacity method.

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
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
*/

Version Information

Windows Phone OS

Supported in: 8.1, 8.0, 7.1, 7.0

Platforms

Windows Phone

See Also

Reference

StringBuilder Class

System.Text Namespace