java.lang
Class StringBuilder

java.lang.Object
  java.lang.StringBuilder

public final class StringBuilder
extends Object

StringBuilder represents a changeable String. It provides the operations required to modify the StringBuilder, including insert, replace, delete, append, and reverse. It like StringBuffer, but is not synchronized. It is ideal for use when it is known that the object will only be used from a single thread.

StringBuilders 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 StringBuilder 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 StringBuilder operation:
a + b
is the same as
new StringBuilder().append(a).append(b).toString().

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

Since:

1.5

See Also:

String, StringBuffer

Constructor Summary

StringBuilder()
Create a new StringBuilder with default capacity 16.

StringBuilder(int capacity)
Create an empty StringBuilder with the specified initial capacity.

StringBuilder(String str)
Create a new StringBuilder with the characters in the specified String.

Method Summary

StringBuilder	append(boolean bool) Append the String value of the argument to this StringBuilder.
StringBuilder	append(char ch) Append the char to this StringBuilder.
StringBuilder	append(char[] data) Append the char array to this StringBuilder.
StringBuilder	append(char[] data, int offset, int count) Append part of the char array to this StringBuilder.
StringBuilder	append(double dnum) Append the String value of the argument to this StringBuilder.
StringBuilder	append(float fnum) Append the String value of the argument to this StringBuilder.
StringBuilder	append(int inum) Append the String value of the argument to this StringBuilder.
StringBuilder	append(long lnum) Append the String value of the argument to this StringBuilder.
StringBuilder	append(Object obj) Append the String value of the argument to this StringBuilder.
StringBuilder	append(String str) Append the String to this StringBuilder.
StringBuilder	append(StringBuffer stringBuffer) Append the StringBuilder value of the argument to this StringBuilder.
int	capacity() Get the total number of characters this StringBuilder can support before it must be grown.
char	charAt(int index) Get the character at the specified index.
StringBuilder	delete(int start, int end) Delete characters from this StringBuilder.
StringBuilder	deleteCharAt(int index) Delete a character from this StringBuilder.
void	ensureCapacity(int minimumCapacity) Increase the capacity of this StringBuilder.
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 StringBuilder.
int	indexOf(String str, int fromIndex) Finds the first instance of a String in this StringBuilder, starting at a given index.
StringBuilder	insert(int offset, boolean bool) Insert the String value of the argument into this StringBuilder.
StringBuilder	insert(int offset, char ch) Insert the char argument into this StringBuilder.
StringBuilder	insert(int offset, char[] data) Insert the char[] argument into this StringBuilder.
StringBuilder	insert(int offset, char[] str, int str_offset, int len) Insert a subarray of the char[] argument into this StringBuilder.
StringBuilder	insert(int offset, double dnum) Insert the String value of the argument into this StringBuilder.
StringBuilder	insert(int offset, float fnum) Insert the String value of the argument into this StringBuilder.
StringBuilder	insert(int offset, int inum) Insert the String value of the argument into this StringBuilder.
StringBuilder	insert(int offset, long lnum) Insert the String value of the argument into this StringBuilder.
StringBuilder	insert(int offset, Object obj) Insert the String value of the argument into this StringBuilder.
StringBuilder	insert(int offset, String str) Insert the String argument into this StringBuilder.
int	lastIndexOf(String str) Finds the last instance of a substring in this StringBuilder.
int	lastIndexOf(String str, int fromIndex) Finds the last instance of a String in this StringBuilder, starting at a given index.
int	length() Get the length of the String this StringBuilder would create.
StringBuilder	replace(int start, int end, String str) Replace characters between index start (inclusive) and end (exclusive) with str.
StringBuilder	reverse() Reverse the characters in this StringBuilder.
void	setCharAt(int index, char ch) Set the character at the specified index.
void	setLength(int newLength) Set the length of this StringBuilder.
String	substring(int beginIndex) Creates a substring of this StringBuilder, starting at a specified index and ending at the end of this StringBuilder.
String	substring(int beginIndex, int endIndex) Creates a substring of this StringBuilder, starting at a specified index and ending at one character before a specified index.
String	toString() Convert this StringBuilder to a String.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

StringBuilder

public StringBuilder()

Create a new StringBuilder with default capacity 16.

StringBuilder

public StringBuilder(int capacity)

Create an empty StringBuilder with the specified initial capacity.

Parameters:

capacity - the initial capacity

Throws:

NegativeArraySizeException - if capacity is negative

StringBuilder

public StringBuilder(String str)

Create a new StringBuilder 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 StringBuilder would create. Not to be confused with the capacity of the StringBuilder.

Returns:

the length of this StringBuilder

See Also:

capacity(), setLength(int)

capacity

public int capacity()

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

Returns:

the capacity of this StringBuilder

See Also:

length(), ensureCapacity(int)

ensureCapacity

public void ensureCapacity(int minimumCapacity)

Increase the capacity of this StringBuilder. 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 StringBuilder. 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() (while unspecified, this is a StringIndexOutOfBoundsException)

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 StringBuilder append(Object obj)

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

Parameters:

obj - the Object to convert and append

Returns:

this StringBuilder

See Also:

String.valueOf(Object), append(String)

append

public StringBuilder append(String str)

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

Parameters:

str - the String to append

Returns:

this StringBuilder

append

public StringBuilder append(StringBuffer stringBuffer)

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

Parameters:

stringBuffer - the StringBuilder to convert and append

Returns:

this StringBuilder

See Also:

append(Object)

append

public StringBuilder append(char[] data)

Append the char array to this StringBuilder. 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 StringBuilder

Throws:

NullPointerException - if str is null

See Also:

append(char[], int, int)

append

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

Append part of the char array to this StringBuilder. 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 StringBuilder

Throws:

NullPointerException - if str is null

IndexOutOfBoundsException - if offset or count is out of range (while unspecified, this is a StringIndexOutOfBoundsException)

append

public StringBuilder append(boolean bool)

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

Parameters:

bool - the boolean to convert and append

Returns:

this StringBuilder

See Also:

String.valueOf(boolean)

append

public StringBuilder append(char ch)

Append the char to this StringBuilder.

Parameters:

ch - the char to append

Returns:

this StringBuilder

append

public StringBuilder append(int inum)

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

Parameters:

inum - the int to convert and append

Returns:

this StringBuilder

See Also:

String.valueOf(int)

append

public StringBuilder append(long lnum)

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

Parameters:

lnum - the long to convert and append

Returns:

this StringBuilder

See Also:

String.valueOf(long)

append

public StringBuilder append(float fnum)

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

Parameters:

fnum - the float to convert and append

Returns:

this StringBuilder

See Also:

String.valueOf(float)

append

public StringBuilder append(double dnum)

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

Parameters:

dnum - the double to convert and append

Returns:

this StringBuilder

See Also:

String.valueOf(double)

delete

public StringBuilder delete(int start,
                            int end)

Delete characters from this StringBuilder. 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 StringBuilder

Throws:

StringIndexOutOfBoundsException - if start or end are out of bounds

deleteCharAt

public StringBuilder deleteCharAt(int index)

Delete a character from this StringBuilder.

Parameters:

index - the index of the character to delete

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - if index is out of bounds

replace

public StringBuilder 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 StringBuilder, 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 StringBuilder

Throws:

StringIndexOutOfBoundsException - if start or end are out of bounds

NullPointerException - if str is null

substring

public String substring(int beginIndex)

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

Parameters:

beginIndex - index to start substring (base 0)

Returns:

new String which is a substring of this StringBuilder

Throws:

StringIndexOutOfBoundsException - if beginIndex is out of bounds

See Also:

substring(int, int)

substring

public String substring(int beginIndex,
                        int endIndex)

Creates a substring of this StringBuilder, 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 StringBuilder

Throws:

StringIndexOutOfBoundsException - if beginIndex or endIndex is out of bounds

insert

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

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

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 StringBuilder

Throws:

NullPointerException - if str is null

StringIndexOutOfBoundsException - if any index is out of bounds

insert

public StringBuilder insert(int offset,
                            Object obj)

Insert the String value of the argument into this StringBuilder. 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 StringBuilder

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

See Also:

String.valueOf(Object)

insert

public StringBuilder insert(int offset,
                            String str)

Insert the String argument into this StringBuilder. 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 StringBuilder

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

insert

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

Insert the char[] argument into this StringBuilder.

Parameters:

offset - the place to insert in this buffer

data - the char[] to insert

Returns:

this StringBuilder

Throws:

NullPointerException - if data is null

StringIndexOutOfBoundsException - if offset is out of bounds

See Also:

insert(int, char[], int, int)

insert

public StringBuilder insert(int offset,
                            boolean bool)

Insert the String value of the argument into this StringBuilder. 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 StringBuilder

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

See Also:

String.valueOf(boolean)

insert

public StringBuilder insert(int offset,
                            char ch)

Insert the char argument into this StringBuilder.

Parameters:

offset - the place to insert in this buffer

ch - the char to insert

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

insert

public StringBuilder insert(int offset,
                            int inum)

Insert the String value of the argument into this StringBuilder. 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 StringBuilder

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

See Also:

String.valueOf(int)

insert

public StringBuilder insert(int offset,
                            long lnum)

Insert the String value of the argument into this StringBuilder. 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 StringBuilder

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

See Also:

String.valueOf(long)

insert

public StringBuilder insert(int offset,
                            float fnum)

Insert the String value of the argument into this StringBuilder. 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 StringBuilder

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

See Also:

String.valueOf(float)

insert

public StringBuilder insert(int offset,
                            double dnum)

Insert the String value of the argument into this StringBuilder. 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 StringBuilder

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 StringBuilder.

Parameters:

str - String to find

Returns:

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

Throws:

NullPointerException - if str is null

See Also:

indexOf(String, int)

indexOf

public int indexOf(String str,
                   int fromIndex)

Finds the first instance of a String in this StringBuilder, 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

lastIndexOf

public int lastIndexOf(String str)

Finds the last instance of a substring in this StringBuilder.

Parameters:

str - String to find

Returns:

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

Throws:

NullPointerException - if str is null

See Also:

lastIndexOf(String, int)

lastIndexOf

public int lastIndexOf(String str,
                       int fromIndex)

Finds the last instance of a String in this StringBuilder, 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

reverse

public StringBuilder reverse()

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

Returns:

this StringBuilder

toString

public String toString()

Convert this StringBuilder to a String. The String is composed of the characters currently in this StringBuilder. 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 StringBuilder

See Also:

Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)