OBJECT-ORIENTED THINKING - Introduction to Java Programming: Comprehensive Version - page 395

10.11.2 The toString , capacity , length , setLength ,
and charAt Methods
The StringBuilder class provides the additional methods for manipulating a string builder
and obtaining its properties, as shown in Figure 10.20.

java.lang.StringBuilder

+toString(): String
+capacity(): int
+charAt(index: int): char
+length(): int
+setLength(newLength: int): void
+substring(startIndex: int): String
+substring(startIndex: int, endIndex: int):
String
+trimToSize(): void

Returns a string object from the string builder.
Returns the capacity of this string builder.
Returns the character at the specified index.
Returns the number of characters in this builder.
Sets a new length in this builder.
Returns a substring starting at startIndex .
Returns a substring from startIndex to endIndex-1 .

Reduces the storage size used for the string builder.

F IGURE 10.20

The StringBuilder class contains the methods for modifying string builders.

The capacity() method returns the current capacity of the string builder. The capacity is
the number of characters the string builder is able to store without having to increase its size.
The length() method returns the number of characters actually stored in the string
builder. The setLength(newLength) method sets the length of the string builder. If the
newLength argument is less than the current length of the string builder, the string builder is
truncated to contain exactly the number of characters given by the newLength argument. If
the newLength argument is greater than or equal to the current length, sufficient null char-
acters ( \u0000 ) are appended to the string builder so that length becomes the newLength
argument. The newLength argument must be greater than or equal to 0 .
The charAt(index) method returns the character at a specific index in the string
builder. The index is 0 based. The first character of a string builder is at index 0 , the next at
index 1 , and so on. The index argument must be greater than or equal to 0 , and less than the
length of the string builder.

capacity()

length()
setLength(int)

charAt(int)

Note
The length of the string is always less than or equal to the capacity of the builder. The
length is the actual size of the string stored in the builder, and the capacity is the current
size of the builder. The builder's capacity is automatically increased if more characters
are added to exceed its capacity. Internally, a string builder is an array of characters, so
the builder's capacity is the size of the array. If the builder's capacity is exceeded, the
array is replaced by a new array. The new array size is 2 * (the previous array
size + 1) .

length and capacity

Tip
You can use new StringBuilder(initialCapacity) to create a String-
Builder with a specified initial capacity. By carefully choosing the initial capacity, you
can make your program more efficient. If the capacity is always larger than the actual
length of the builder, the JVM will never need to reallocate memory for the builder. On
the other hand, if the capacity is too large, you will waste memory space. You can use
the trimToSize() method to reduce the capacity to the actual size.

initial capacity

trimToSize()