StringBuilder.Capacity Propriété

Définition

Espace de noms:

System.Text

Assemblys:

netstandard.dll, System.Runtime.dll

Source:

StringBuilder.cs

Obtient ou définit le nombre maximal de caractères pouvant être contenus dans la mémoire allouée par l’instance actuelle.

public:
 property int Capacity { int get(); void set(int value); };

public int Capacity { get; set; }

member this.Capacity : int with get, set

Public Property Capacity As Integer

Valeur de propriété

Int32

Nombre maximal de caractères pouvant être contenus dans la mémoire allouée par l’instance actuelle. Sa valeur peut aller de Length à MaxCapacity.

Exceptions

ArgumentOutOfRangeException

La valeur spécifiée pour une opération set est inférieure à la longueur actuelle de cette instance.

- ou -

La valeur spécifiée pour une opération de jeu est supérieure à la capacité maximale.

Exemples

L’exemple suivant illustre la Capacity propriété.

using System;
using System.Text;

StringBuilder sb1 = new("abc");
StringBuilder sb2 = new("abc", 16);

Console.WriteLine();
Console.WriteLine($"a1) sb1.Length = {sb1.Length}, sb1.Capacity = {sb1.Capacity}");
Console.WriteLine($"a2) sb2.Length = {sb2.Length}, sb2.Capacity = {sb2.Capacity}");
Console.WriteLine($"a3) sb1.ToString() = \"{sb1}\", sb2.ToString() = \"{sb2}\"");
Console.WriteLine($"a4) sb1 equals sb2: {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 = {sb1.Length}, sb1.Capacity = {sb1.Capacity}");
Console.WriteLine($"b2) sb2.Length = {sb2.Length}, sb2.Capacity = {sb2.Capacity}");
Console.WriteLine($"b3) sb1.ToString() = \"{sb1}\", sb2.ToString() = \"{sb2}\"");
Console.WriteLine($"b4) sb1 equals sb2: {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 = {sb1.Length}, sb1.Capacity = {sb1.Capacity}");
Console.WriteLine($"c2) sb2.Length = {sb2.Length}, sb2.Capacity = {sb2.Capacity}");
Console.WriteLine($"c3) sb1.ToString() = \"{sb1}\", sb2.ToString() = \"{sb2}\"");
Console.WriteLine($"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: True (False on .NET Framework)

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: True (False on .NET Framework)
//       
//       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: True (False on .NET Framework)
'       
'       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

Remarques

Capacity n’affecte pas la valeur de chaîne de l’instance actuelle. Capacity peut être diminué tant qu’il n’est pas inférieur à Length.

L’allocation StringBuilder dynamique d’un espace supplémentaire lorsque nécessaire et augmente Capacity en conséquence. Pour des raisons de performances, un StringBuilder peut allouer plus de mémoire que nécessaire. La quantité de mémoire allouée est spécifique à l’implémentation.