StringBuilder.Length Property
Microsoft Silverlight will reach end of support after October 2021. Learn more.
Gets or sets the length of the current StringBuilder object.
Namespace: System.Text
Assembly: mscorlib (in mscorlib.dll)
Syntax
'Declaration
Public Property Length As Integer
public int Length { get; set; }
Property Value
Type: System.Int32
The length of this instance.
Exceptions
| Exception | Condition |
|---|---|
| ArgumentOutOfRangeException | The value specified for a set operation is less than zero or greater than the maximum capacity of this instance. |
Remarks
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 is set to the specified length.
Examples
The following code example demonstrates the Length property.
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
using System;
using System.Text;
class Example
{
public static void Demo(System.Windows.Controls.TextBlock outputBlock)
{
StringBuilder sb1 = new StringBuilder("abc");
StringBuilder sb2 = new StringBuilder("abc", 16);
outputBlock.Text += "\n";
outputBlock.Text += String.Format("a1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity) + "\n";
outputBlock.Text += String.Format("a2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity) + "\n";
outputBlock.Text += String.Format("a3) sb1.ToString() = \"{0}\", sb2.ToString() = \"{1}\"",
sb1.ToString(), sb2.ToString()) + "\n";
outputBlock.Text += String.Format("a4) sb1 equals sb2: {0}", sb1.Equals(sb2)) + "\n";
outputBlock.Text += "\n";
outputBlock.Text += "Ensure sb1 has a capacity of at least 50 characters." + "\n";
sb1.EnsureCapacity(50);
outputBlock.Text += "\n";
outputBlock.Text += String.Format("b1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity) + "\n";
outputBlock.Text += String.Format("b2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity) + "\n";
outputBlock.Text += String.Format("b3) sb1.ToString() = \"{0}\", sb2.ToString() = \"{1}\"",
sb1.ToString(), sb2.ToString()) + "\n";
outputBlock.Text += String.Format("b4) sb1 equals sb2: {0}", sb1.Equals(sb2)) + "\n";
outputBlock.Text += "\n";
outputBlock.Text += "Set the length of sb1 to zero." + "\n";
outputBlock.Text += "Set the capacity of sb2 to 51 characters." + "\n";
sb1.Length = 0;
sb2.Capacity = 51;
outputBlock.Text += "\n";
outputBlock.Text += String.Format("c1) sb1.Length = {0}, sb1.Capacity = {1}", sb1.Length, sb1.Capacity) + "\n";
outputBlock.Text += String.Format("c2) sb2.Length = {0}, sb2.Capacity = {1}", sb2.Length, sb2.Capacity) + "\n";
outputBlock.Text += String.Format("c3) sb1.ToString() = \"{0}\", sb2.ToString() = \"{1}\"",
sb1.ToString(), sb2.ToString()) + "\n";
outputBlock.Text += String.Format("c4) sb1 equals sb2: {0}", sb1.Equals(sb2)) + "\n";
}
}
/*
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
*/
Version Information
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
Platforms
For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.