java.lang
Class StringBuffer

java.lang.Object
  extended by java.lang.StringBuffer

public final class StringBuffer
extends Object

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

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.
 
Method Summary
 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(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(double dnum)
          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(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(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.
 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.
 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, 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, char[] data)
          Insert the char[] argument into this StringBuffer.
 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, double dnum)
          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, 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, 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.
 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.
 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.
 String toString()
          Convert this StringBuffer to a String.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

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
Method Detail

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
See Also:
capacity(), setLength(int)

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
See Also:
length(), ensureCapacity(int)

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
See Also:
capacity()

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)
See Also:
length()

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()

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)
See Also:
System.arraycopy(Object, int, Object, int, int)

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)

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
See Also:
String.valueOf(Object), append(String)

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
See Also:
append(Object)

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
See Also:
append(char[], int, int)

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.valueOf(boolean)

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(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.valueOf(int)

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.valueOf(long)

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.valueOf(float)

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.valueOf(double)

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

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

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:
substring(int, int)

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

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
See Also:
String.valueOf(Object)

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,
                           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
See Also:
insert(int, char[], int, int)

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.valueOf(boolean)

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.valueOf(int)

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.valueOf(long)

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.valueOf(float)

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.valueOf(double)

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:
indexOf(String, int)

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

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:
lastIndexOf(String, int)

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

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

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.

Overrides:
toString in class Object
Returns:
the characters in this StringBuffer
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)