StringBuilder.Length Property
[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
Gets or sets the length of the current StringBuilder object.
Assembly: mscorlib (in mscorlib.dll)
| Exception | Condition |
|---|---|
| ArgumentOutOfRangeException | The value specified for a set operation is less than zero or greater than the maximum capacity of this instance. |
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.
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