20.13 The Class java.lang.StringBuffer

A string buffer is like a String (§20.12), but can be modified. At any point in time it contains some particular sequence of characters, but the length and content of the sequence can be changed through certain method calls. 

public class StringBuffer {
	public StringBuffer();
	public StringBuffer(int length)

		throws NegativeArraySizeException;
	public StringBuffer(String str);
	public String toString();
	public int length();
	public void setLength(int newLength)
		throws IndexOutOfBoundsException;
	public int capacity();
	public void ensureCapacity(int minimumCapacity);
	public char charAt(int index)
		throws IndexOutOfBoundsException;
	public void setCharAt(int index, char ch)
		throws IndexOutOfBoundsException;
	public void getChars(int srcBegin, int srcEnd,
			char[] dst, int dstBegin)

		throws NullPointerException, IndexOutOfBoundsException;
	public StringBuffer append(Object obj);
	public StringBuffer append(String str);
	public StringBuffer append(char[] str)
		throws NullPointerException;
	public StringBuffer append(char[] str, int offset, int len)
		throws NullPointerException, IndexOutOfBoundsException;
	public StringBuffer append(boolean b);
	public StringBuffer append(char c);
	public StringBuffer append(int i);
	public StringBuffer append(long l);
	public StringBuffer append(float f);
	public StringBuffer append(double d);
	public StringBuffer insert(int offset, Object obj)
		throws IndexOutOfBoundsException;
	public StringBuffer insert(int offset, String str)
		throws IndexOutOfBoundsException;
	public StringBuffer insert(int offset, char[] str)
		throws NullPointerException, IndexOutOfBoundsException;
	public StringBuffer insert(int offset, boolean b)
		throws IndexOutOfBoundsException;
	public StringBuffer insert(int offset, char c)
		throws IndexOutOfBoundsException;
	public StringBuffer insert(int offset, int i)
		throws IndexOutOfBoundsException;
	public StringBuffer insert(int offset, long l)
		throws IndexOutOfBoundsException;
	public StringBuffer insert(int offset, float f)
		throws IndexOutOfBoundsException;
	public StringBuffer insert(int offset, double d)
		throws IndexOutOfBoundsException;
	public StringBuffer reverse();
}

A string buffer has a capacity. As long as the length of the character sequence contained in the string buffer does not exceed the capacity, it is not necessary to create a new internal buffer array.

String buffers are safe for use by multiple threads. The methods are synchronized where necessary so that all the operations on any particular instance behave as if they occur in some serial order that is consistent with the order of the method calls made by each of the individual threads involved.

String buffers can be used by a compiler to implement the binary string concatenation operator + (§15.17.1). For example, suppose k has type int and a has type Object. Then the expression:

k + "/" + a

can be compiled as if it were the expression:

new StringBuffer().append(k).append("/").

										append(a).toString()

which creates a new string buffer (initially empty), appends the string representation of each operand to the string buffer in turn, and then converts the contents of the string buffer to a string. Overall, this avoids creating many temporary strings.

The principal operations on a StringBuffer are the append and insert methods, which are overloaded so as to accept data of any type. Each effectively converts a given datum to a string and then adds the characters of that string to the contents of the string buffer. The append method always adds these characters at the end of the buffer; the insert method adds the characters at a specified point.

For example, if z refers to a string buffer object whose current contents are the characters "start", then the method call z.append("le") would alter the string buffer to contain the characters "startle", but z.insert(4, "le") would alter the string buffer to contain the characters "starlet".

In general, if sb refers to an instance of a StringBuffer, then sb.append(x) has the same effect as sb.insert(sb.length(), x).

20.13.1 public StringBuffer()

This constructor initializes a newly created StringBuffer object so that it initially represents an empty character sequence and has capacity 16.

20.13.2 public StringBuffer(int length)
throws NegativeArraySizeException

This constructor initializes a newly created StringBuffer object so that it initially represents an empty character sequence, but has the capacity specified by the argument.

If the argument is negative, a NegativeArraySizeException is thrown.

20.13.3 public StringBuffer(String str)

This constructor initializes a newly created StringBuffer object so that it represents the same sequence of characters as the argument; in other words, the initial contents of the string buffer is a copy of the argument string. The initial capacity of the string buffer is 16 plus the length of the argument string.

20.13.4 public String toString()

A new String object is created and initialized to contain the character sequence currently represented by the string buffer; the new String is then returned. Any subsequent changes to the string buffer do not affect the contents of the returned string.

Implementation advice: This method can be coded so as to create a new String object without allocating new memory to hold a copy of the character sequence. Instead, the string can share the memory used by the string buffer. Any subsequent operation that alters the content or capacity of the string buffer must then make a copy of the internal buffer at that time. This strategy is effective for reducing the amount of memory allocated by a string concatenation operation (§15.17.1) when it is implemented using a string buffer.

Overrides the toString method of Object (§20.1.2).

20.13.5 public int length()

This method returns the length of the sequence of characters currently represented by this StringBuffer object.

20.13.6 public int capacity()

The current capacity of this StringBuffer object is returned.

20.13.7 public void ensureCapacity(int minimumCapacity)

If the current capacity of this StringBuffer object is less than the argument, then a new internal buffer is created with greater capacity. The new capacity will be the larger of:

If the minimumCapacity argument is nonpositive, this method takes no action and simply returns.

20.13.8 public void setLength(int newLength)
throws IndexOutOfBoundsException

This string buffer is altered to represent a new character sequence whose length is specified by the argument. For every nonnegative index k less than newLength, the character at index k in the new character sequence is the same as the character at index k in the old sequence if k is less than the length of the old character sequence; otherwise, it is the null character '\u0000'. This method also calls the ensureCapacity method (§20.13.7) with argument newLength.

If the argument is negative, an IndexOutOfBoundsException is thrown.

20.13.9 public char charAt(int index)
throws IndexOutOfBoundsException

The specified character of the sequence currently represented by the string buffer, as indicated by the index argument, is returned. The first character of the sequence is at index 0, the next at index 1, and so on, as for array indexing.

If the index argument is negative or not less than the current length (§20.13.5) of the string buffer, an IndexOutOfBoundsException is thrown.

20.13.10 public void setCharAt(int index, char ch)
throws IndexOutOfBoundsException

The string buffer is altered to represent a new character sequence that is identical to the old character sequence, except that it contains the character ch at position index.

If the index argument is negative or not less than the current length (§20.13.5) of the string buffer, an IndexOutOfBoundsException is thrown.

20.13.11 public void getChars(int srcBegin, int srcEnd,
char[] dst, int dstBegin)
throws NullPointerException,
IndexOutOfBoundsException

Characters are copied from this StringBuffer object into the destination array dst. The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1 (thus, the total number of characters to be copied is srcEnd-srcBegin). The characters are copied into the subarray of dst starting at index dstBegin and ending at index dstbegin+(srcEnd-srcBegin)-1.

If dst is null, then a NullPointerException is thrown.

Otherwise, if any of the following is true, an IndexOutOfBoundsException is thrown and the destination is not modified:

20.13.12 public StringBuffer append(Object obj)

The argument is converted to a string as if by the method String.valueOf (§20.12.38) and the characters of that string are then appended (§20.13.13) to this StringBuffer object. A reference to this StringBuffer object is returned.

20.13.13 public StringBuffer append(String str)

The characters of the String argument are appended, in order, to the contents of this string buffer, increasing the length of this string buffer by the length of the argument. If str is null, then the four characters "null" are appended to this string buffer. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

Let n be the length of the old character sequence, the one contained in the string buffer just prior to execution of the append method. Then the character at index k in the new character sequence is equal to the character at index k in the old character sequence, if k is less than n; otherwise, it is equal to the character at index k-n in the argument str.

20.13.14 public StringBuffer append(char[] str)
throws NullPointerException

The characters of the array argument are appended, in order, to the contents of this string buffer, increasing the length of this string buffer by the length of the argument. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

The overall effect is exactly as if the argument were converted to a string by the method String.valueOf (§20.12.39) and the characters of that string were then appended (§20.13.13) to this StringBuffer object.

20.13.15 public StringBuffer append(char[] str,
int offset, int len)
throws NullPointerException,
IndexOutOfBoundsException

Characters of the character array str, starting at index offset, are appended, in order, to the contents of this string buffer, increasing the length of this string buffer by len. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

The overall effect is exactly as if the arguments were converted to a string by the method String.valueOf of three arguments (§20.12.40) and the characters of that string were then appended (§20.13.13) to this StringBuffer object.

20.13.16 public StringBuffer append(boolean b)

The argument is converted to a string as if by the method String.valueOf (§20.12.41) and the characters of that string are then appended (§20.13.13) to this StringBuffer object. A reference to this StringBuffer object is returned.

20.13.17 public StringBuffer append(char c)

The argument is appended to the contents of this string buffer, increasing the length of this string buffer by 1. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

The overall effect is exactly as if the argument were converted to a string by the method String.valueOf (§20.12.42) and the character in that string were then appended (§20.13.13) to this StringBuffer object.

20.13.18 public StringBuffer append(int i)

The argument is converted to a string as if by the method String.valueOf (§20.12.43) and the characters of that string are then appended (§20.13.13) to this StringBuffer object. A reference to this StringBuffer object is returned.

20.13.19 public StringBuffer append(long l)

The argument is converted to a string as if by the method String.valueOf (§20.12.44) and the characters of that string are then appended (§20.13.13) to this StringBuffer object. A reference to this StringBuffer object is returned.

20.13.20 public StringBuffer append(float f)

The argument is converted to a string as if by the method String.valueOf (§20.12.45) and the characters of that string are then appended (§20.13.13) to this StringBuffer object. A reference to this StringBuffer object is returned.

20.13.21 public StringBuffer append(double d)

The argument is converted to a string as if by the method String.valueOf (§20.12.46) and the characters of that string are then appended (§20.13.13) to this StringBuffer object. A reference to this StringBuffer object is returned.

20.13.22 public StringBuffer insert(int offset, Object obj)
throws IndexOutOfBoundsException

The argument is converted to a string as if by the method String.valueOf (§20.12.38) and the characters of that string are then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset. A reference to this StringBuffer object is returned.

20.13.23 public StringBuffer insert(int offset, String str)
throws IndexOutOfBoundsException

The characters of the String argument are inserted, in order, into the string buffer at the position indicated by offset, moving up any characters originally above that position and increasing the length of the string buffer by the length of the argument. If str is null, then the four characters "null" are inserted into this string buffer. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

Let n be the length of the old character sequence, the one contained in the string buffer just prior to execution of the append method. Then the character at index k in the new character sequence is equal to:

20.13.24 public StringBuffer insert(int offset, char[] str)
throws NullPointerException,
IndexOutOfBoundsException

The characters of the array argument, taken in order, are inserted into this string buffer, increasing the length of the string buffer by the length of the argument. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

The overall effect is exactly as if the argument were converted to a string by the method String.valueOf (§20.12.39) and the characters of that string were then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset.

Note that while the StringBuffer class provides an append method that takes an offset, a character array, and two other arguments (§20.13.15), it does not currently provide an insert method that takes an offset, a character array, and two other arguments.

20.13.25 public StringBuffer insert(int offset, boolean b)
throws IndexOutOfBoundsException

The argument is converted to a string as if by the method String.valueOf (§20.12.41) and the characters of that string are then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset. A reference to this StringBuffer object is returned.

20.13.26 public StringBuffer insert(int offset, char c)
throws IndexOutOfBoundsException

The argument is inserted into the contents of this string buffer at the position indicated by offset, increasing the length of this string buffer by 1. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

The overall effect is exactly as if the argument were converted to a string by the method String.valueOf (§20.12.42) and the character in that string were then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset.

20.13.27 public StringBuffer insert(int offset, int i)
throws IndexOutOfBoundsException

The argument is converted to a string as if by the method String.valueOf (§20.12.43) and the characters of that string are then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset. A reference to this StringBuffer object is returned.

20.13.28 public StringBuffer insert(int offset, long l)
throws IndexOutOfBoundsException

The argument is converted to a string as if by the method String.valueOf (§20.12.44) and the characters of that string are inserted (§20.13.23) into this StringBuffer object at the position indicated by offset. A reference to this StringBuffer object is returned.

20.13.29 public StringBuffer insert(int offset, float f)
throws IndexOutOfBoundsException

The argument is converted to a string as if by the method String.valueOf (§20.12.45) and the characters of that string are then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset. A reference to this StringBuffer object is returned.

20.13.30 public StringBuffer insert(int offset, double d)
throws IndexOutOfBoundsException

The argument is converted to a string as if by the method String.valueOf (§20.12.46) and the characters of that string are then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset. A reference to this StringBuffer object is returned.

20.13.31 public StringBuffer reverse()

The character sequence contained in this StringBuffer object is replaced by the reverse of that sequence. A reference to this StringBuffer object is returned.

Let n be the length of the old character sequence, the one contained in the string buffer just prior to execution of the reverse method. Then the character at index k in the new character sequence is equal to the character at index n-k-1 in the old character sequence.