Export (0) Print
Expand All

StringBuilder.EnsureCapacity Method

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

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

'Declaration
Public Function EnsureCapacity ( _
	capacity As Integer _
) As Integer

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.


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


Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Community Additions

ADD
Show:
© 2014 Microsoft