Section 16.11. Length and Capacity Properties, EnsureCapacity Method and Indexer of Class StringBuilder

16.11. Length and Capacity Properties, EnsureCapacity Method and Indexer of Class StringBuilder

Class StringBuilder provides the Length and Capacity properties to return the number of characters currently in a StringBuilder and the number of characters that a StringBuilder can store without allocating more memory, respectively. These properties also can increase or decrease the length or the capacity of the StringBuilder.

Method EnsureCapacity allows you to reduce the number of times a StringBuilder's capacity must be increased. Method EnsureCapacity doubles the StringBuilder instance's current capacity. If this doubled value is greater than the value you wish to ensure, that value becomes the new capacity. Otherwise, EnsureCapacity alters the capacity by making it equal to the requested number. For example, if the current capacity is 17 and we wish to make it 40, 17 multiplied by 2 is not greater than or equal to 40, so the call will result in a new capacity of 40. If the current capacity is 23 and we wish to make it 40, 23 will be multiplied by 2 to result in a new capacity of 46. Both 40 and 46 are greater than or equal to 40, so a capacity of 40 is indeed ensured by method EnsureCapacity. Figure 16.10 demonstrates these methods and properties.

Figure 16.10. StringBuilder size manipulation.

  1  ' Fig. 16.10: StringBuilderFeatures.vb  2  ' Demonstrating some features of class StringBuilder.  3  Imports System.Text  4  5  Module StringBuilderFeatures  6     Sub Main()  7        Dim buffer As New StringBuilder("Hello, how are you?")  8  9        ' use Length and Capacity properties 10        Console.WriteLine( _ 11           "buffer = " & buffer.ToString() & vbCrLf & "Length = " & _ 12           buffer.Length & vbCrLf & "Capacity = " & buffer.Capacity) 13 14        buffer.EnsureCapacity(75) ' ensure a capacity of at least 75 15        Console.WriteLine(vbCrLf & "New capacity = " & buffer.Capacity) 16 17        ' truncate StringBuilder by setting Length property 18        buffer.Length = 10 19        Console.Write(vbCrLf & "New length = " & _ 20           buffer.Length & vbCrLf & "buffer = ") 21 22        ' use StringBuilder indexer 23        For i As Integer = 0 To  buffer.Length - 1 24           Console.Write(buffer(i)) 25        Next i 26 27        Console.WriteLine() 28     End Sub ' Main 29  End Module ' StringBuilderFeatures 

 buffer = Hello, how are you? Length = 19 Capacity = 32 New capacity = 75 New length = 10 buffer = Hello, how 

The program contains one StringBuilder, called buffer. Line 7 uses the StringBuilder constructor that takes a String argument to instantiate a StringBuilder and initialize its value to "Hello, how are you?". Lines 1012 output the content, length and capacity of the StringBuilder. In the output window, note that the capacity of the StringBuilder is initially 32. Remember, the StringBuilder constructor that takes a String argument creates a StringBuilder object with an initial capacity that is the smallest power of two greater than or equal to the number of characters in the String passed as an argument.

Line 14 expands the capacity of the StringBuilder to a minimum of 75 characters. The current capacity (32) multiplied by two is less than 75, so method EnsureCapacity increases the capacity to 75. If new characters are added to a StringBuilder so that its length exceeds its capacity, the capacity grows to accommodate the additional characters in the same manner as if method EnsureCapacity had been called.

Line 18 uses property Length to set the length of the StringBuilder to 10. If the specified length is less than the current number of characters in the StringBuilder, the contents of the StringBuilder are truncated to the specified length. If the specified length is greater than the number of characters currently in the StringBuilder, null characters (characters with the numeric representation 0) are appended to the StringBuilder until the total number of characters in the StringBuilder is equal to the specified length. Lines 2325 use the StringBuilder indexer to output the characters in the StringBuilder one character at a time.