StringBuilder.EnsureCapacity(Int32) Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Ensures that the capacity of this instance of StringBuilder is at least the specified value.
public:
int EnsureCapacity(int capacity);
public int EnsureCapacity (int capacity);
member this.EnsureCapacity : int -> int
Public Function EnsureCapacity (capacity As Integer) As Integer
Parameters
- capacity
- Int32
The minimum capacity to ensure.
Returns
The new capacity of this instance.
Exceptions
Examples
The following example demonstrates the EnsureCapacity method.
using namespace System;
using namespace System::Text;
int main()
{
StringBuilder^ sb1 = gcnew StringBuilder( "abc" );
StringBuilder^ sb2 = gcnew StringBuilder( "abc",16 );
Console::WriteLine();
Console::WriteLine( "a1) sb1->Length = {0}, sb1->Capacity = {1}", sb1->Length, sb1->Capacity );
Console::WriteLine( "a2) sb2->Length = {0}, sb2->Capacity = {1}", sb2->Length, sb2->Capacity );
Console::WriteLine( "a3) sb1 = \"{0}\", sb2 = \"{1}\"", sb1, sb2 );
Console::WriteLine( "a4) sb1 equals sb2: {0}", sb1->Equals( sb2 ) );
Console::WriteLine();
Console::WriteLine( "Ensure sb1 has a capacity of at least 50 characters." );
sb1->EnsureCapacity( 50 );
Console::WriteLine();
Console::WriteLine( "b1) sb1->Length = {0}, sb1->Capacity = {1}", sb1->Length, sb1->Capacity );
Console::WriteLine( "b2) sb2->Length = {0}, sb2->Capacity = {1}", sb2->Length, sb2->Capacity );
Console::WriteLine( "b3) sb1 = \"{0}\", sb2 = \"{1}\"", sb1, sb2 );
Console::WriteLine( "b4) sb1 equals sb2: {0}", sb1->Equals( sb2 ) );
Console::WriteLine();
Console::WriteLine( "Set the length of sb1 to zero." );
Console::WriteLine( "Set the capacity of sb2 to 51 characters." );
sb1->Length = 0;
sb2->Capacity = 51;
Console::WriteLine();
Console::WriteLine( "c1) sb1->Length = {0}, sb1->Capacity = {1}", sb1->Length, sb1->Capacity );
Console::WriteLine( "c2) sb2->Length = {0}, sb2->Capacity = {1}", sb2->Length, sb2->Capacity );
Console::WriteLine( "c3) sb1 = \"{0}\", sb2 = \"{1}\"", sb1, sb2 );
Console::WriteLine( "c4) sb1 equals sb2: {0}", sb1->Equals( sb2 ) );
}
/*
The example displays the following output:
a1) sb1->Length = 3, sb1->Capacity = 16
a2) sb2->Length = 3, sb2->Capacity = 16
a3) sb1 = "abc", sb2 = "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 = "abc", sb2 = "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 = "", sb2 = "abc"
c4) sb1 equals sb2: False
*/
using System;
using System.Text;
class Sample
{
public static void Main()
{
StringBuilder sb1 = new StringBuilder("abc");
StringBuilder sb2 = new StringBuilder("abc", 16);
Console.WriteLine();
Console.WriteLine("a1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity);
Console.WriteLine("a2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity);
Console.WriteLine("a3) sb1.ToString() = \"{0}\", sb2.ToString() = \"{1}\"",
sb1.ToString(), sb2.ToString());
Console.WriteLine("a4) sb1 equals sb2: {0}", sb1.Equals(sb2));
Console.WriteLine();
Console.WriteLine("Ensure sb1 has a capacity of at least 50 characters.");
sb1.EnsureCapacity(50);
Console.WriteLine();
Console.WriteLine("b1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity);
Console.WriteLine("b2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity);
Console.WriteLine("b3) sb1.ToString() = \"{0}\", sb2.ToString() = \"{1}\"",
sb1.ToString(), sb2.ToString());
Console.WriteLine("b4) sb1 equals sb2: {0}", sb1.Equals(sb2));
Console.WriteLine();
Console.WriteLine("Set the length of sb1 to zero.");
Console.WriteLine("Set the capacity of sb2 to 51 characters.");
sb1.Length = 0;
sb2.Capacity = 51;
Console.WriteLine();
Console.WriteLine("c1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity);
Console.WriteLine("c2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity);
Console.WriteLine("c3) sb1.ToString() = \"{0}\", sb2.ToString() = \"{1}\"",
sb1.ToString(), sb2.ToString());
Console.WriteLine("c4) sb1 equals sb2: {0}", sb1.Equals(sb2));
}
}
/*
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
*/
open System.Text
let sb1 = StringBuilder "abc"
let sb2 = StringBuilder("abc", 16)
printfn $"a1) sb1.Length = {sb1.Length}, sb1.Capacity = {sb1.Capacity}"
printfn $"a2) sb2.Length = {sb2.Length}, sb2.Capacity = {sb2.Capacity}"
printfn $"a3) sb1.ToString() = \"{sb1}\", sb2.ToString() = \"{sb2}\""
printfn $"a4) sb1 equals sb2: {sb1.Equals sb2}"
printfn "\nEnsure sb1 has a capacity of at least 50 characters."
sb1.EnsureCapacity 50 |> ignore
printfn $"\nb1) sb1.Length = {sb1.Length}, sb1.Capacity = {sb1.Capacity}"
printfn $"b2) sb2.Length = {sb2.Length}, sb2.Capacity = {sb2.Capacity}"
printfn $"b3) sb1.ToString() = \"{sb1}\", sb2.ToString() = \"{sb2}\""
printfn $"b4) sb1 equals sb2: {sb1.Equals sb2}"
printfn "\nSet the length of sb1 to zero."
printfn "Set the capacity of sb2 to 51 characters."
sb1.Length <- 0
sb2.Capacity <- 51
printfn $"\nc1) sb1.Length = {sb1.Length}, sb1.Capacity = {sb1.Capacity}"
printfn $"c2) sb2.Length = {sb2.Length}, sb2.Capacity = {sb2.Capacity}"
printfn $"c3) sb1.ToString() = \"{sb1}\", sb2.ToString() = \"{sb2}\""
printfn $"c4) sb1 equals sb2: {sb1.Equals sb2}"
// 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
Imports System.Text
Class Sample
Public Shared Sub Main()
Dim sb1 As New StringBuilder("abc")
Dim sb2 As New StringBuilder("abc", 16)
Console.WriteLine()
Console.WriteLine("a1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity)
Console.WriteLine("a2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity)
Console.WriteLine("a3) sb1.ToString() = ""{0}"", sb2.ToString() = ""{1}""", _
sb1.ToString(), sb2.ToString())
Console.WriteLine("a4) sb1 equals sb2: {0}", sb1.Equals(sb2))
Console.WriteLine()
Console.WriteLine("Ensure sb1 has a capacity of at least 50 characters.")
sb1.EnsureCapacity(50)
Console.WriteLine()
Console.WriteLine("b1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity)
Console.WriteLine("b2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity)
Console.WriteLine("b3) sb1.ToString() = ""{0}"", sb2.ToString() = ""{1}""", _
sb1.ToString(), sb2.ToString())
Console.WriteLine("b4) sb1 equals sb2: {0}", sb1.Equals(sb2))
Console.WriteLine()
Console.WriteLine("Set the length of sb1 to zero.")
Console.WriteLine("Set the capacity of sb2 to 51 characters.")
sb1.Length = 0
sb2.Capacity = 51
Console.WriteLine()
Console.WriteLine("c1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity)
Console.WriteLine("c2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity)
Console.WriteLine("c3) sb1.ToString() = ""{0}"", sb2.ToString() = ""{1}""", _
sb1.ToString(), sb2.ToString())
Console.WriteLine("c4) sb1 equals sb2: {0}", sb1.Equals(sb2))
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
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.