java.lang

Class StringBuffer

public final class StringBuffer extends Object implements Serializable, CharSequence, Appendable

StringBuffer represents a changeable String. It provides the operations required to modify the StringBuffer, including insert, replace, delete, append, and reverse. It is thread-safe; meaning that all modifications to a buffer are in synchronized methods.

StringBuffers are variable-length in nature, so even if you initialize them to a certain size, they can still grow larger than that. Capacity indicates the number of characters the StringBuffer can have in it before it has to grow (growing the char array is an expensive operation involving new).

Incidentally, compilers often implement the String operator "+" by using a StringBuffer operation:
a + b
is the same as
new StringBuffer().append(a).append(b).toString().

Classpath's StringBuffer is capable of sharing memory with Strings for efficiency. This will help when a StringBuffer is converted to a String and the StringBuffer is not changed after that (quite common when performing string concatenation).

Since: 1.0

See Also: String

UNKNOWN: updated to 1.4

Constructor Summary
	StringBuffer() Create a new StringBuffer with default capacity 16.
	StringBuffer(int capacity) Create an empty `StringBuffer` with the specified initial capacity.
	StringBuffer(String str) Create a new `StringBuffer` with the characters in the specified `String`.
	StringBuffer(CharSequence seq) Create a new `StringBuffer` with the characters in the specified `CharSequence`.

Method Summary
StringBuffer	append(Object obj) Append the `String` value of the argument to this `StringBuffer`.
StringBuffer	append(String str) Append the `String` to this `StringBuffer`.
StringBuffer	append(StringBuffer stringBuffer) Append the `StringBuffer` value of the argument to this `StringBuffer`.
StringBuffer	append(char[] data) Append the `char` array to this `StringBuffer`.
StringBuffer	append(char[] data, int offset, int count) Append part of the `char` array to this `StringBuffer`.
StringBuffer	append(boolean bool) Append the `String` value of the argument to this `StringBuffer`.
StringBuffer	append(char ch) Append the `char` to this `StringBuffer`.
StringBuffer	append(CharSequence seq) Append the characters in the `CharSequence` to this buffer.
StringBuffer	append(CharSequence seq, int start, int end) Append some characters from the `CharSequence` to this buffer.
StringBuffer	append(int inum) Append the `String` value of the argument to this `StringBuffer`.
StringBuffer	append(long lnum) Append the `String` value of the argument to this `StringBuffer`.
StringBuffer	append(float fnum) Append the `String` value of the argument to this `StringBuffer`.
StringBuffer	append(double dnum) Append the `String` value of the argument to this `StringBuffer`.
StringBuffer	appendCodePoint(int code) Append the code point to this `StringBuffer`.
int	capacity() Get the total number of characters this `StringBuffer` can support before it must be grown.
char	charAt(int index) Get the character at the specified index.
int	codePointAt(int index) Get the code point at the specified index.
int	codePointBefore(int index) Get the code point before the specified index.
int	codePointCount(int start, int end) Return the number of code points between two indices in the `StringBuffer`.
StringBuffer	delete(int start, int end) Delete characters from this `StringBuffer`.
StringBuffer	deleteCharAt(int index) Delete a character from this `StringBuffer`.
void	ensureCapacity(int minimumCapacity) Increase the capacity of this `StringBuffer`.
void	getChars(int srcOffset, int srcEnd, char[] dst, int dstOffset) Get the specified array of characters.
int	indexOf(String str) Finds the first instance of a substring in this StringBuffer.
int	indexOf(String str, int fromIndex) Finds the first instance of a String in this StringBuffer, starting at a given index.
StringBuffer	insert(int offset, char[] str, int str_offset, int len) Insert a subarray of the `char[]` argument into this `StringBuffer`.
StringBuffer	insert(int offset, Object obj) Insert the `String` value of the argument into this `StringBuffer`.
StringBuffer	insert(int offset, String str) Insert the `String` argument into this `StringBuffer`.
StringBuffer	insert(int offset, CharSequence sequence) Insert the `CharSequence` argument into this `StringBuffer`.
StringBuffer	insert(int offset, CharSequence sequence, int start, int end) Insert a subsequence of the `CharSequence` argument into this `StringBuffer`.
StringBuffer	insert(int offset, char[] data) Insert the `char[]` argument into this `StringBuffer`.
StringBuffer	insert(int offset, boolean bool) Insert the `String` value of the argument into this `StringBuffer`.
StringBuffer	insert(int offset, char ch) Insert the `char` argument into this `StringBuffer`.
StringBuffer	insert(int offset, int inum) Insert the `String` value of the argument into this `StringBuffer`.
StringBuffer	insert(int offset, long lnum) Insert the `String` value of the argument into this `StringBuffer`.
StringBuffer	insert(int offset, float fnum) Insert the `String` value of the argument into this `StringBuffer`.
StringBuffer	insert(int offset, double dnum) Insert the `String` value of the argument into this `StringBuffer`.
int	lastIndexOf(String str) Finds the last instance of a substring in this StringBuffer.
int	lastIndexOf(String str, int fromIndex) Finds the last instance of a String in this StringBuffer, starting at a given index.
int	length() Get the length of the `String` this `StringBuffer` would create.
int	offsetByCodePoints(int start, int codePoints) Starting at the given index, this counts forward by the indicated number of code points, and then returns the resulting index.
StringBuffer	replace(int start, int end, String str) Replace characters between index `start` (inclusive) and `end` (exclusive) with `str`.
StringBuffer	reverse() Reverse the characters in this StringBuffer.
void	setCharAt(int index, char ch) Set the character at the specified index.
void	setLength(int newLength) Set the length of this StringBuffer.
String	substring(int beginIndex) Creates a substring of this StringBuffer, starting at a specified index and ending at the end of this StringBuffer.
String	substring(int beginIndex, int endIndex) Creates a substring of this StringBuffer, starting at a specified index and ending at one character before a specified index.
CharSequence	subSequence(int beginIndex, int endIndex) Creates a substring of this StringBuffer, starting at a specified index and ending at one character before a specified index.
String	toString() Convert this `StringBuffer` to a `String`.
void	trimToSize() This may reduce the amount of memory used by the StringBuffer, by resizing the internal array to remove unused space.

Constructor Detail

StringBuffer

public StringBuffer()

Create a new StringBuffer with default capacity 16.

StringBuffer

public StringBuffer(int capacity)

Create an empty StringBuffer with the specified initial capacity.

Parameters: capacity the initial capacity

Throws: NegativeArraySizeException if capacity is negative

StringBuffer

public StringBuffer(String str)

Create a new StringBuffer with the characters in the specified String. Initial capacity will be the size of the String plus 16.

Parameters: str the String to convert

Throws: NullPointerException if str is null

StringBuffer

public StringBuffer(CharSequence seq)

Create a new StringBuffer with the characters in the specified CharSequence. Initial capacity will be the length of the sequence plus 16; if the sequence reports a length less than or equal to 0, then the initial capacity will be 16.

Parameters: seq the initializing CharSequence

Throws: NullPointerException if str is null

Since: 1.5

Method Detail

append

public StringBuffer append(Object obj)

Append the String value of the argument to this StringBuffer. Uses String.valueOf() to convert to String.

Parameters: obj the Object to convert and append

Returns: this StringBuffer

append

public StringBuffer append(String str)

Append the String to this StringBuffer. If str is null, the String "null" is appended.

Parameters: str the String to append

Returns: this StringBuffer

append

public StringBuffer append(StringBuffer stringBuffer)

Append the StringBuffer value of the argument to this StringBuffer. This behaves the same as append((Object) stringBuffer), except it is more efficient.

Parameters: stringBuffer the StringBuffer to convert and append

Returns: this StringBuffer

Since: 1.4

append

public StringBuffer append(char[] data)

Append the char array to this StringBuffer. This is similar (but more efficient) than append(new String(data)), except in the case of null.

Parameters: data the char[] to append

Returns: this StringBuffer

Throws: NullPointerException if str is null

append

public StringBuffer append(char[] data, int offset, int count)

Append part of the char array to this StringBuffer. This is similar (but more efficient) than append(new String(data, offset, count)), except in the case of null.

Parameters: data the char[] to append offset the start location in str count the number of characters to get from str

Returns: this StringBuffer

Throws: NullPointerException if str is null IndexOutOfBoundsException if offset or count is out of range (while unspecified, this is a StringIndexOutOfBoundsException)

append

public StringBuffer append(boolean bool)

Append the String value of the argument to this StringBuffer. Uses String.valueOf() to convert to String.

Parameters: bool the boolean to convert and append

Returns: this StringBuffer

See Also: String

append

public StringBuffer append(char ch)

Append the char to this StringBuffer.

Parameters: ch the char to append

Returns: this StringBuffer

append

public StringBuffer append(CharSequence seq)

Append the characters in the CharSequence to this buffer.

Parameters: seq the CharSequence providing the characters

Returns: this StringBuffer

Since: 1.5

append

public StringBuffer append(CharSequence seq, int start, int end)

Append some characters from the CharSequence to this buffer. If the argument is null, the four characters "null" are appended.

Parameters: seq the CharSequence providing the characters start the starting index end one past the final index

Returns: this StringBuffer

Since: 1.5

append

public StringBuffer append(int inum)

Append the String value of the argument to this StringBuffer. Uses String.valueOf() to convert to String.

Parameters: inum the int to convert and append

Returns: this StringBuffer

See Also: String

append

public StringBuffer append(long lnum)

Append the String value of the argument to this StringBuffer. Uses String.valueOf() to convert to String.

Parameters: lnum the long to convert and append

Returns: this StringBuffer

See Also: String

append

public StringBuffer append(float fnum)

Append the String value of the argument to this StringBuffer. Uses String.valueOf() to convert to String.

Parameters: fnum the float to convert and append

Returns: this StringBuffer

See Also: String

append

public StringBuffer append(double dnum)

Append the String value of the argument to this StringBuffer. Uses String.valueOf() to convert to String.

Parameters: dnum the double to convert and append

Returns: this StringBuffer

See Also: String

appendCodePoint

public StringBuffer appendCodePoint(int code)

Append the code point to this StringBuffer. This is like #append(char), but will append two characters if a supplementary code point is given.

Parameters: code the code point to append

Returns: this StringBuffer

Since: 1.5

capacity

public int capacity()

Get the total number of characters this StringBuffer can support before it must be grown. Not to be confused with length.

Returns: the capacity of this StringBuffer

charAt

public char charAt(int index)

Get the character at the specified index.

Parameters: index the index of the character to get, starting at 0

Returns: the character at the specified index

Throws: IndexOutOfBoundsException if index is negative or >= length()

codePointAt

public int codePointAt(int index)

Get the code point at the specified index. This is like #charAt(int), but if the character is the start of a surrogate pair, and the following character completes the pair, then the corresponding supplementary code point is returned.

Parameters: index the index of the codepoint to get, starting at 0

Returns: the codepoint at the specified index

Throws: IndexOutOfBoundsException if index is negative or >= length()

Since: 1.5

codePointBefore

public int codePointBefore(int index)

Get the code point before the specified index. This is like #codePointAt(int), but checks the characters at index-1 and index-2 to see if they form a supplementary code point.

Parameters: index the index just past the codepoint to get, starting at 0

Returns: the codepoint at the specified index

Throws: IndexOutOfBoundsException if index is negative or >= length()

Since: 1.5

codePointCount

public int codePointCount(int start, int end)

Return the number of code points between two indices in the StringBuffer. An unpaired surrogate counts as a code point for this purpose. Characters outside the indicated range are not examined, even if the range ends in the middle of a surrogate pair.

Parameters: start the starting index end one past the ending index

Returns: the number of code points

Since: 1.5

delete

public StringBuffer delete(int start, int end)

Delete characters from this StringBuffer. delete(10, 12) will delete 10 and 11, but not 12. It is harmless for end to be larger than length().

Parameters: start the first character to delete end the index after the last character to delete

Returns: this StringBuffer

Throws: StringIndexOutOfBoundsException if start or end are out of bounds

Since: 1.2

deleteCharAt

public StringBuffer deleteCharAt(int index)

Delete a character from this StringBuffer.

Parameters: index the index of the character to delete

Returns: this StringBuffer

Throws: StringIndexOutOfBoundsException if index is out of bounds

Since: 1.2

ensureCapacity

public void ensureCapacity(int minimumCapacity)

Increase the capacity of this StringBuffer. This will ensure that an expensive growing operation will not occur until minimumCapacity is reached. The buffer is grown to the larger of minimumCapacity and capacity() * 2 + 2, if it is not already large enough.

Parameters: minimumCapacity the new capacity

getChars

public void getChars(int srcOffset, int srcEnd, char[] dst, int dstOffset)

Get the specified array of characters. srcOffset - srcEnd characters will be copied into the array you pass in.

Parameters: srcOffset the index to start copying from (inclusive) srcEnd the index to stop copying from (exclusive) dst the array to copy into dstOffset the index to start copying into

Throws: NullPointerException if dst is null IndexOutOfBoundsException if any source or target indices are out of range (while unspecified, source problems cause a StringIndexOutOfBoundsException, and dest problems cause an ArrayIndexOutOfBoundsException)

indexOf

public int indexOf(String str)

Finds the first instance of a substring in this StringBuffer.

Parameters: str String to find

Returns: location (base 0) of the String, or -1 if not found

Throws: NullPointerException if str is null

Since: 1.4

See Also: StringBuffer

indexOf

public int indexOf(String str, int fromIndex)

Finds the first instance of a String in this StringBuffer, starting at a given index. If starting index is less than 0, the search starts at the beginning of this String. If the starting index is greater than the length of this String, or the substring is not found, -1 is returned.

Parameters: str String to find fromIndex index to start the search

Returns: location (base 0) of the String, or -1 if not found

Throws: NullPointerException if str is null

Since: 1.4

insert

public StringBuffer insert(int offset, char[] str, int str_offset, int len)

Insert a subarray of the char[] argument into this StringBuffer.

Parameters: offset the place to insert in this buffer str the char[] to insert str_offset the index in str to start inserting from len the number of characters to insert

Returns: this StringBuffer

Throws: NullPointerException if str is null StringIndexOutOfBoundsException if any index is out of bounds

Since: 1.2

insert

public StringBuffer insert(int offset, Object obj)

Insert the String value of the argument into this StringBuffer. Uses String.valueOf() to convert to String.

Parameters: offset the place to insert in this buffer obj the Object to convert and insert

Returns: this StringBuffer

Throws: StringIndexOutOfBoundsException if offset is out of bounds

insert

public StringBuffer insert(int offset, String str)

Insert the String argument into this StringBuffer. If str is null, the String "null" is used instead.

Parameters: offset the place to insert in this buffer str the String to insert

Returns: this StringBuffer

Throws: StringIndexOutOfBoundsException if offset is out of bounds

insert

public StringBuffer insert(int offset, CharSequence sequence)

Insert the CharSequence argument into this StringBuffer. If the sequence is null, the String "null" is used instead.

Parameters: offset the place to insert in this buffer sequence the CharSequence to insert

Returns: this StringBuffer

Throws: IndexOutOfBoundsException if offset is out of bounds

Since: 1.5

insert

public StringBuffer insert(int offset, CharSequence sequence, int start, int end)

Insert a subsequence of the CharSequence argument into this StringBuffer. If the sequence is null, the String "null" is used instead.

Parameters: offset the place to insert in this buffer sequence the CharSequence to insert start the starting index of the subsequence end one past the ending index of the subsequence

Returns: this StringBuffer

Throws: IndexOutOfBoundsException if offset, start, or end are out of bounds

Since: 1.5

insert

public StringBuffer insert(int offset, char[] data)

Insert the char[] argument into this StringBuffer.

Parameters: offset the place to insert in this buffer data the char[] to insert

Returns: this StringBuffer

Throws: NullPointerException if data is null StringIndexOutOfBoundsException if offset is out of bounds

insert

public StringBuffer insert(int offset, boolean bool)

Insert the String value of the argument into this StringBuffer. Uses String.valueOf() to convert to String.

Parameters: offset the place to insert in this buffer bool the boolean to convert and insert

Returns: this StringBuffer

Throws: StringIndexOutOfBoundsException if offset is out of bounds

See Also: String

insert

public StringBuffer insert(int offset, char ch)

Insert the char argument into this StringBuffer.

Parameters: offset the place to insert in this buffer ch the char to insert

Returns: this StringBuffer

Throws: StringIndexOutOfBoundsException if offset is out of bounds

insert

public StringBuffer insert(int offset, int inum)

Insert the String value of the argument into this StringBuffer. Uses String.valueOf() to convert to String.

Parameters: offset the place to insert in this buffer inum the int to convert and insert

Returns: this StringBuffer

Throws: StringIndexOutOfBoundsException if offset is out of bounds

See Also: String

insert

public StringBuffer insert(int offset, long lnum)

Insert the String value of the argument into this StringBuffer. Uses String.valueOf() to convert to String.

Parameters: offset the place to insert in this buffer lnum the long to convert and insert

Returns: this StringBuffer

Throws: StringIndexOutOfBoundsException if offset is out of bounds

See Also: String

insert

public StringBuffer insert(int offset, float fnum)

Insert the String value of the argument into this StringBuffer. Uses String.valueOf() to convert to String.

Parameters: offset the place to insert in this buffer fnum the float to convert and insert

Returns: this StringBuffer

Throws: StringIndexOutOfBoundsException if offset is out of bounds

See Also: String

insert

public StringBuffer insert(int offset, double dnum)

Insert the String value of the argument into this StringBuffer. Uses String.valueOf() to convert to String.

Parameters: offset the place to insert in this buffer dnum the double to convert and insert

Returns: this StringBuffer

Throws: StringIndexOutOfBoundsException if offset is out of bounds

See Also: String

lastIndexOf

public int lastIndexOf(String str)

Finds the last instance of a substring in this StringBuffer.

Parameters: str String to find

Returns: location (base 0) of the String, or -1 if not found

Throws: NullPointerException if str is null

Since: 1.4

See Also: StringBuffer

lastIndexOf

public int lastIndexOf(String str, int fromIndex)

Finds the last instance of a String in this StringBuffer, starting at a given index. If starting index is greater than the maximum valid index, then the search begins at the end of this String. If the starting index is less than zero, or the substring is not found, -1 is returned.

Parameters: str String to find fromIndex index to start the search

Returns: location (base 0) of the String, or -1 if not found

Throws: NullPointerException if str is null

Since: 1.4

length

public int length()

Get the length of the String this StringBuffer would create. Not to be confused with the capacity of the StringBuffer.

Returns: the length of this StringBuffer

offsetByCodePoints

public int offsetByCodePoints(int start, int codePoints)

Starting at the given index, this counts forward by the indicated number of code points, and then returns the resulting index. An unpaired surrogate counts as a single code point for this purpose.

Parameters: start the starting index codePoints the number of code points

Returns: the resulting index

Since: 1.5

replace

public StringBuffer replace(int start, int end, String str)

Replace characters between index start (inclusive) and end (exclusive) with str. If end is larger than the size of this StringBuffer, all characters after start are replaced.

Parameters: start the beginning index of characters to delete (inclusive) end the ending index of characters to delete (exclusive) str the new String to insert

Returns: this StringBuffer

Throws: StringIndexOutOfBoundsException if start or end are out of bounds NullPointerException if str is null

Since: 1.2

reverse

public StringBuffer reverse()

Reverse the characters in this StringBuffer. The same sequence of characters exists, but in the reverse index ordering.

Returns: this StringBuffer

setCharAt

public void setCharAt(int index, char ch)

Set the character at the specified index.

Parameters: index the index of the character to set starting at 0 ch the value to set that character to

Throws: IndexOutOfBoundsException if index is negative or >= length() (while unspecified, this is a StringIndexOutOfBoundsException)

setLength

public void setLength(int newLength)

Set the length of this StringBuffer. If the new length is greater than the current length, all the new characters are set to '\0'. If the new length is less than the current length, the first newLength characters of the old array will be preserved, and the remaining characters are truncated.

Parameters: newLength the new length

Throws: IndexOutOfBoundsException if the new length is negative (while unspecified, this is a StringIndexOutOfBoundsException)

substring

public String substring(int beginIndex)

Creates a substring of this StringBuffer, starting at a specified index and ending at the end of this StringBuffer.

Parameters: beginIndex index to start substring (base 0)

Returns: new String which is a substring of this StringBuffer

Throws: StringIndexOutOfBoundsException if beginIndex is out of bounds

Since: 1.2

See Also: StringBuffer

substring

public String substring(int beginIndex, int endIndex)

Creates a substring of this StringBuffer, starting at a specified index and ending at one character before a specified index.

Parameters: beginIndex index to start at (inclusive, base 0) endIndex index to end at (exclusive)

Returns: new String which is a substring of this StringBuffer

Throws: StringIndexOutOfBoundsException if beginIndex or endIndex is out of bounds

Since: 1.2

subSequence

public CharSequence subSequence(int beginIndex, int endIndex)

Creates a substring of this StringBuffer, starting at a specified index and ending at one character before a specified index. This is implemented the same as substring(beginIndex, endIndex), to satisfy the CharSequence interface.

Parameters: beginIndex index to start at (inclusive, base 0) endIndex index to end at (exclusive)

Returns: new String which is a substring of this StringBuffer

Throws: IndexOutOfBoundsException if beginIndex or endIndex is out of bounds

Since: 1.4

See Also: StringBuffer

toString

public String toString()

Convert this StringBuffer to a String. The String is composed of the characters currently in this StringBuffer. Note that the result is a copy, and that future modifications to this buffer do not affect the String.

Returns: the characters in this StringBuffer

trimToSize

public void trimToSize()

This may reduce the amount of memory used by the StringBuffer, by resizing the internal array to remove unused space. However, this method is not required to resize, so this behavior cannot be relied upon.

Since: 1.5