Class StringBuffer

Once a String object is created, its contents can never change. We now discuss the features of class StringBuffer for creating and manipulating dynamic string informationthat is, modifiable strings. Every StringBuffer is capable of storing a number of characters specified by its capacity. If the capacity of a StringBuffer is exceeded, the capacity is automatically expanded to accommodate the additional characters. Class StringBuffer is also used to implement operators + and += for String concatenation.

Performance Tip 29.2

Performance Tip 29.3

29.4.1. StringBuffer Constructors

Class StringBuffer provides four constructors. Three of these constructors are demonstrated in Fig. 29.10. Line 8 uses the no-argument StringBuffer constructor to create a StringBuffer with no characters in it and an initial capacity of 16 characters (the default for a StringBuffer). Line 9 uses the StringBuffer constructor that takes an integer argument to create a StringBuffer with no characters in it and the initial capacity specified by the integer argument (i.e., 10). Line 10 uses the StringBuffer constructor that takes a String argument (in this case, a string literal) to create a StringBuffer containing the characters in the String argument. The initial capacity is the number of characters in the String argument plus 16.

Figure 29.10. StringBuffer class constructors.

The statements on lines 1214 uses StringBuffer method toString to output the StringBuffer with the printf method. In Section 29.4.4, we discuss how Java uses StringBuffer objects to implement the + and += operators for string concatenation.

29.4.2. StringBuffer Methods length, capacity, setLength and ensureCapacity

Class StringBuffer provides methods length and capacity to return the number of characters currently in a StringBuffer and the number of characters that can be stored in a StringBuffer without allocating more memory, respectively. Method ensureCapacity guarantees that a StringBuffer has at least the specified capacity. Method setLength increases or decreases the length of a StringBuffer. The application in Fig. 29.11 demonstrates these methods.

Figure 29.11. StringBuffer methods length and capacity.

(This item is displayed on page 1367 in the print version)

The application contains one StringBuffer called buffer. Line 8 uses the StringBuffer constructor that takes a String argument to initialize the StringBuffer with "Hello, how are you?". Lines 1011 print the contents, length and capacity of the StringBuffer. Note in the output window that the capacity of the StringBuffer is initially 35. Recall that the StringBuffer constructor that takes a String argument initializes the capacity to the length of the string passed as an argument plus 16.

Line 13 uses method ensureCapacity to expand the capacity of the StringBuffer to a minimum of 75 characters. Actually, if the original capacity is less than the argument, the method ensures a capacity that is the greater of the number specified as an argument and twice the original capacity plus 2. The StringBuffer's current capacity remains unchanged if it is more than the specified capacity.

Performance Tip 29.4

Line 16 uses method setLength to set the length of the StringBuffer to 10. If the specified length is less than the current number of characters in the StringBuffer, the buffer is truncated to the specified length (i.e., the characters in the StringBuffer after the specified length are discarded). If the specified length is greater than the number of characters currently in the StringBuffer, null characters (characters with the numeric representation 0) are appended to the StringBuffer until the total number of characters in the StringBuffer is equal to the specified length. See Section 14.7.1 for more details.

29.4.3. StringBuffer Methods charAt, setCharAt, getChars and reverse

Class StringBuffer provides methods charAt, setCharAt, getChars and reverse to manipulate the characters in a StringBuffer. Each of these methods is demonstrated in Fig. 29.12.

Figure 29.12. StringBuffer class character-manipulation methods.

Method charAt (line 12) takes an integer argument and returns the character in the StringBuffer at that index. Method getChars (line 15) copies characters from a StringBuffer into the character array passed as an argument. This method takes four argumentsthe starting index from which characters should be copied in the StringBuffer, the index one past the last character to be copied from the StringBuffer, the character array into which the characters are to be copied and the starting location in the character array where the first character should be placed. Method setCharAt (lines 21 and 22) takes an integer and a character argument and sets the character at the specified position in the StringBuffer to the character argument. Method reverse (line 25) reverses the contents of the StringBuffer.

Common Programming Error 29.3

29.4.4. StringBuffer append Methods

Class StringBuffer provides overloaded append methods to allow values of various types to be appended to the end of a StringBuffer. Versions are provided for each of the primitive types and for character arrays, Strings, Objects, StringBuffers and CharSequences. (Remember that method toString produces a string representation of any Object.) Each of the methods takes its argument, converts it to a string and appends it to the StringBuffer. The append methods are demonstrated in Fig. 29.13.

Figure 29.13. StringBuffer class append methods.

(This item is displayed on pages 1370 - 1371 in the print version)

Actually, StringBuffers and the append methods are used by the compiler to implement the + and += operators for String concatenation. For example, assuming the declarations

String string1 = "hello"; String string2 = "BC"; int value = 22;

the statement

String s = string1 + string2 + value;

concatenates "hello", "BC" and 22. The concatenation is performed as follows:

new StringBuffer().append( "hello" ).append( "BC" ).append( 22 ).toString();

First, Java creates an empty StringBuffer, then appends to the StringBuffer the string "hello", the string "BC" and the integer 22. Next, StringBuffer's method toString converts the StringBuffer to a String object to be assigned to String s. The statement

s += "!";

is performed as follows:

s = new StringBuffer().append( s ).append( "!" ).toString();

First, Java creates an empty StringBuffer, then appends to the StringBuffer the current contents of s followed by "!". Next, StringBuffer's method toString converts the StringBuffer to a string representation and the result is assigned to s.

29.4.5. StringBuffer Insertion and Deletion Methods

Class StringBuffer provides overloaded insert methods to allow values of various types to be inserted at any position in a StringBuffer. Versions are provided for each of the primitive types and for character arrays, Strings, Objects and CharSequences. Each of the methods takes its second argument, converts it to a string and inserts it immediately preceding the index specified by the first argument. The index specified by the first argument must be greater than or equal to 0 and less than the length of the StringBufferotherwise, a StringIndexOutOfBoundsException occurs. Class StringBuffer also provides methods delete and deleteCharAt for deleting characters at any position in a StringBuffer. Method delete takes two argumentsthe starting index and the index one past the end of the characters to delete. All characters beginning at the starting index up to but not including the ending index are deleted. Method deleteCharAt takes one argumentthe index of the character to delete. Invalid indices cause both methods to throw a String-IndexOutOfBoundsException. Methods insert, delete and deleteCharAt are demonstrated in Fig. 29.14.

Figure 29.14. StringBuffer methods insert and delete.

(This item is displayed on pages 1371 - 1372 in the print version)