Arrays and Strings - Beginning Java - page 190

This method returns the number of Unicode characters the object can currently hold. For aString defined
as shown, this is 32. When you create a StringBuffer object containing a string, its capacity is 16 charac-
ters greater than the minimum necessary to hold the string.
The ensureCapacity() method enables you to change the default capacity of a StringBuffer object.
You specify the minimum capacity you need as the argument to the method. For example:
aString.ensureCapacity(40);
If the current capacity of the aString object is less than 40, this increases the capacity of aString by al-
locating a new larger buffer, but not necessarily with a capacity of 40. The capacity is the larger of either the
value that you specify, 40 in this case, or twice the current capacity plus 2, which is 66, given that aString
is defined as before. You might want to do this sort of thing when you are reusing an existing StringBuffer
object in a new context where the strings are longer.
Changing the String Length for a StringBuffer Object
You can change the length of the string contained in a StringBuffer object with the method setLength() .
Note that the length is a property of the string the object holds, as opposed to the capacity, which is a prop-
erty of the string buffer. When you increase the length for a StringBuffer object, you are adding characters
to the existing string and the extra characters contain '\u0000' . A more common use of this method is to
decrease the length, in which case the string is truncated. If aString contains "A stitch in time" , the
statement
aString.setLength(8);
results in aString containing the string "A stitch" , and the value returned by the length() method is 8.
The characters that were cut from the end of the string by this operation are lost.
To increase the length to what it was before, you could write:
aString.setLength(16);
Now aString contains the string:
"A stitch\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000"
The setLength() method does not affect the capacity of the object unless you set the length to be greater
than the capacity. In this case the capacity is increased to accommodate the new string length to a value that
is twice the original capacity plus two if the length you set is less than this value. If you specify a length that
is greater than twice the original capacity plus two, the new capacity is the same as the length you set. If the
capacity of aString is 66, executing the statement
aString.setLength(100);
sets the capacity of the object, aString , to 134. If you supplied a value for the length of 150, then the new
capacity would be 150. You must not specify a negative length here. If you do, IndexOutOfBoundsExcep-
tion is thrown.
Adding to a StringBuffer Object
The append() method enables you to add a string to the end of the existing string stored in a StringBuffer
object. This method comes in quite a few flavors, but perhaps the simplest adds the string contained within
a String or a StringBuffer object to a StringBuffer object. This works with string literals too.
Suppose you define a StringBuffer object with the following statement: