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 that a StringBuilder's capacity must be increased. The method doubles the StringBuilder instance's current capacity. If this doubled value is greater than the value that the programmer wishes to ensure, that value becomes the new capacity. Otherwise, EnsureCapacity alters the capacity to make 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 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. The program in Fig. 16.10 demonstrates the use of these methods and properties.

Figure 16.10. StringBuilder size manipulation.

 1 // Fig. 16.10: StringBuilderFeatures.cs
 2 // Demonstrating some features of class StringBuilder.
 3 using System;
 4 using System.Text;
 5
 6 class StringBuilderFeatures
 7 {
 8 public static void Main()
 9 {
10 StringBuilder buffer = 
11  new StringBuilder( "Hello, how are you?" );
12
13 // use Length and Capacity properties
14 Console.WriteLine( "buffer = " + buffer +
15 "
Length = " + buffer.Length +
16 "
Capacity = " + buffer.Capacity );
17
18 buffer.EnsureCapacity( 75 ); // ensure a capacity of at least 75
19 Console.WriteLine( "
New capacity = " +
20 buffer.Capacity );
21

22 // truncate StringBuilder by setting Length property 23 buffer.Length = 10; 24 Console.Write( " New length = " + 25 buffer.Length + " buffer = " ); 26 27 // use StringBuilder indexer 28 for ( int i = 0; i < buffer.Length; i++ ) 29 Console.Write( buffer[ i ] ); 30 31 Console.WriteLine( " " ); 32 } // end method Main 33 } // end class 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. Lines 1011 of the program use the StringBuilder constructor that takes a string argument to instantiate the StringBuilder and initialize its value to "Hello, how are you?". Lines 1316 output the content, length and capacity of the StringBuilder. In the output window, notice 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 18 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 23 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, space characters are appended to the StringBuilder until the total number of characters in the StringBuilder is equal to the specified length.

Common Programming Error 16 3

Assigning null to a string reference can lead to logic errors if you attempt to compare null to an empty string. The keyword null is a value that represents a null reference (i.e., a reference that does not refer to an object), not an empty string (which is a string object that is of length 0 and contains no characters).