Export (0) Print
Expand All
0 out of 2 rated this helpful - Rate this topic

StringBuilder.Length Property

Gets or sets the length of this instance.

[Visual Basic]
Public Property Length As Integer
[C#]
public int Length {get; set;}
[C++]
public: __property int get_Length();
public: __property void set_Length(int);
[JScript]
public function get Length() : int;
public function set Length(int);

Property Value

The length of this instance.

Exceptions

Exception Type Condition
ArgumentOutOfRangeException The value specified for a set operation is less than zero or greater than MaxCapacity.

Remarks

If the specified length is less than the current length, this instance is truncated to the specified length. If the specified length is greater than the current length, the end of the string value of this instance is padded with spaces. If the specified length is greater than the current capacity, Capacity is set to the specified length.

Example

[Visual Basic] 
' This example demonstrates StringBuilder.EnsureCapacity
'                           StringBuilder.Capacity
'                           StringBuilder.Length
'                           StringBuilder.Equals
Imports System
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 'Main
End Class 'Sample
'
'This example produces the following results:
'
'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 = 51
'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 = 51
'c2) sb2.Length = 3, sb2.Capacity = 51
'c3) sb1.ToString() = "", sb2.ToString() = "abc"
'c4) sb1 equals sb2: False
'

[C#] 
// This example demonstrates StringBuilder.EnsureCapacity
//                           StringBuilder.Capacity
//                           StringBuilder.Length
//                           StringBuilder.Equals
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));
    }
}
/*
This example produces the following results:

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 = 51
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 = 51
c2) sb2.Length = 3, sb2.Capacity = 51
c3) sb1.ToString() = "", sb2.ToString() = "abc"
c4) sb1 equals sb2: False
*/

[C++] 
// This example demonstrates StringBuilder.EnsureCapacity
//                           StringBuilder.Capacity
//                           StringBuilder.Length
//                           StringBuilder.Equals
#using <mscorlib.dll>
using namespace System;
using namespace System::Text;

int main() 
    {
    StringBuilder* sb1 = new StringBuilder(S"abc");
    StringBuilder* sb2 = new StringBuilder(S"abc", 16);

    Console::WriteLine();
    Console::WriteLine(S"a1) sb1->Length = {0}, sb1->Capacity = {1}", __box(sb1->Length), __box(sb1->Capacity));
    Console::WriteLine(S"a2) sb2->Length = {0}, sb2->Capacity = {1}", __box(sb2->Length), __box(sb2->Capacity));
    Console::WriteLine(S"a3) sb1 = \"{0}\", sb2 = \"{1}\"",sb1,sb2);
    Console::WriteLine(S"a4) sb1 equals sb2: {0}", __box(sb1->Equals(sb2)));

    Console::WriteLine();
    Console::WriteLine(S"Ensure sb1 has a capacity of at least 50 characters.");
    sb1->EnsureCapacity(50);

    Console::WriteLine();
    Console::WriteLine(S"b1) sb1->Length = {0}, sb1->Capacity = {1}", __box(sb1->Length), __box(sb1->Capacity));
    Console::WriteLine(S"b2) sb2->Length = {0}, sb2->Capacity = {1}", __box(sb2->Length), __box(sb2->Capacity));
    Console::WriteLine(S"b3) sb1 = \"{0}\", sb2 = \"{1}\"",sb1,sb2);
    Console::WriteLine(S"b4) sb1 equals sb2: {0}", __box(sb1->Equals(sb2)));

    Console::WriteLine();
    Console::WriteLine(S"Set the length of sb1 to zero.");
    Console::WriteLine(S"Set the capacity of sb2 to 51 characters.");
    sb1->Length = 0;
    sb2->Capacity = 51;

    Console::WriteLine();
    Console::WriteLine(S"c1) sb1->Length = {0}, sb1->Capacity = {1}", __box(sb1->Length), __box(sb1->Capacity));
    Console::WriteLine(S"c2) sb2->Length = {0}, sb2->Capacity = {1}", __box(sb2->Length), __box(sb2->Capacity));
    Console::WriteLine(S"c3) sb1 = \"{0}\", sb2 = \"{1}\"",sb1,sb2);
    Console::WriteLine(S"c4) sb1 equals sb2: {0}", __box(sb1->Equals(sb2)));
}
/*
This example produces the following results:

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 = 51
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 = 51
c2) sb2.Length = 3, sb2.Capacity = 51
c3) sb1.ToString() = "", sb2.ToString() = "abc"
c4) sb1 equals sb2: False
*/

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework, Common Language Infrastructure (CLI) Standard

See Also

StringBuilder Class | StringBuilder Members | System.Text Namespace

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.