StringBuilder.Length Property

Reference

Definition

Namespace:: System.Text

Assembly:: System.Runtime.dll

Assembly:: mscorlib.dll

Assembly:: netstandard.dll

Source:: StringBuilder.cs

Source:: StringBuilder.cs

Source:: StringBuilder.cs

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.

Gets or sets the length of the current StringBuilder object.

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

public int Length { get; set; }

member this.Length : int with get, set

Public Property Length As Integer

Property Value

Int32

The length of this instance.

Exceptions

ArgumentOutOfRangeException

The value specified for a set operation is less than zero or greater than MaxCapacity.

Examples

The following example demonstrates the Length property.

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

The length of a StringBuilder object is defined by its number of Char objects.

Like the String.Length property, the Length property indicates the length of the current string object. Unlike the String.Length property, which is read-only, the Length property allows you to modify the length of the string stored to the StringBuilder object.

If the specified length is less than the current length, the current StringBuilder object is truncated to the specified length. If the specified length is greater than the current length, the end of the string value of the current StringBuilder object is padded with the Unicode NULL character (U+0000).

If the specified length is greater than the current capacity, Capacity increases so that it is greater than or equal to the specified length.

Applies to

Jaa