java.lang
Class StringBuilder

java.lang.Object
  java.lang.StringBuilder

All Implemented Interfaces:

Serializable, Appendable, CharSequence

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

StringBuilder is not thread safe. For a synchronized implementation, use StringBuffer. StringBuilder is a variable size contiguous indexable array of characters. The length of the StringBuilder is the number of characters it contains. The capacity of the StringBuilder is the number of characters it can hold.

Characters may be inserted at any position up to the length of the StringBuilder, increasing the length of the StringBuilder. Characters at any position in the StringBuilder may be replaced, which does not affect the StringBuilder length.

The capacity of a StringBuilder may be specified when the StringBuilder is created. If the capacity of the StringBuilder is exceeded, the capacity is increased.

Since:

1.5

See Also:

StringBuffer, Serialized Form

Constructor Summary

StringBuilder()
Constructs a new StringBuffer using the default capacity.

StringBuilder(CharSequence sequence)
Constructs a new StringBuilder containing the characters in the specified CharSequence and the default capacity.

StringBuilder(int capacity)
Constructs a new StringBuilder using the specified capacity.

StringBuilder(String string)
Constructs a new StringBuilder containing the characters in the specified string and the default capacity.

Method Summary

StringBuilder	append(boolean value) Adds the string representation of the specified boolean to the end of this StringBuilder.
StringBuilder	append(char ch) Adds the specified character to the end of this StringBuilder.
StringBuilder	append(char[] chars) Adds the character array to the end of this StringBuilder.
StringBuilder	append(char[] chars, int start, int length) Adds the specified sequence of characters to the end of this StringBuilder.
StringBuilder	append(CharSequence sequence) Adds the specified CharSequence to the end of this StringBuilder.
StringBuilder	append(CharSequence sequence, int start, int end) Adds the specified CharSequence to the end of this StringBuilder.
StringBuilder	append(double value) Adds the string representation of the specified double to the end of this StringBuilder.
StringBuilder	append(float value) Adds the string representation of the specified float to the end of this StringBuilder.
StringBuilder	append(int value) Adds the string representation of the specified integer to the end of this StringBuilder.
StringBuilder	append(long value) Adds the string representation of the specified long to the end of this StringBuilder.
StringBuilder	append(Object value) Adds the string representation of the specified object to the end of this StringBuilder.
StringBuilder	append(String string) Adds the specified string to the end of this StringBuilder.
StringBuilder	append(StringBuffer buffer) Adds the specified StringBuffer to the end of this StringBuilder.
StringBuilder	appendCodePoint(int codePoint) Adds the specified code point to the end of this StringBuffer.
int	capacity() Answers the number of characters this StringBuilder can hold without growing.
char	charAt(int index) Answers the character at the specified offset in this StringBuilder.
int	codePointAt(int index) Returns the Unicode character at the given point.
int	codePointBefore(int index) Returns the Unicode character before the given point.
int	codePointCount(int start, int end) Returns the total Unicode values in the specified range.
StringBuilder	delete(int start, int end) Deletes a range of characters.
StringBuilder	deleteCharAt(int location) Deletes a single character
void	ensureCapacity(int min) Ensures that this StringBuilder can hold the specified number of characters without growing.
void	getChars(int start, int end, char[] buffer, int index) Copies the specified characters in this StringBuilder to the character array starting at the specified offset in the character array.
int	indexOf(String string) Searches in this StringBuilder for the first index of the specified character.
int	indexOf(String subString, int start) Searches in this StringBuilder for the index of the specified character.
StringBuilder	insert(int index, boolean value) Inserts the string representation of the specified boolean at the specified offset in this StringBuilder.
StringBuilder	insert(int index, char ch) Inserts the character at the specified offset in this StringBuilder.
StringBuilder	insert(int index, char[] chars) Inserts the character array at the specified offset in this StringBuilder.
StringBuilder	insert(int index, char[] chars, int start, int length) Inserts the specified sequence of characters at the specified offset in this StringBuilder.
StringBuilder	insert(int index, CharSequence sequence) Inserts the CharSequence at the specified offset in this StringBuilder.
StringBuilder	insert(int index, CharSequence sequence, int start, int end) Inserts the CharSequence at the specified offset in this StringBuilder.
StringBuilder	insert(int index, double value) Inserts the string representation of the specified double at the specified offset in this StringBuilder.
StringBuilder	insert(int index, float value) Inserts the string representation of the specified float at the specified offset in this StringBuilder.
StringBuilder	insert(int index, int value) Inserts the string representation of the specified integer at the specified offset in this StringBuilder.
StringBuilder	insert(int index, long value) Inserts the string representation of the specified long at the specified offset in this StringBuilder.
StringBuilder	insert(int index, Object value) Inserts the string representation of the specified object at the specified offset in this StringBuilder.
StringBuilder	insert(int index, String string) Inserts the string at the specified offset in this StringBuilder.
int	lastIndexOf(String string) Searches in this StringBuilder for the last index of the specified character.
int	lastIndexOf(String subString, int start) Searches in this StringBuilder for the index of the specified character.
int	length() Answers the size of this StringBuilder.
int	offsetByCodePoints(int start, int codePointCount) Returns the index of the code point that was offset by codePointCount.
StringBuilder	replace(int start, int end, String string) Replace a range of characters with the characters in the specified String.
StringBuilder	reverse() Reverses the order of characters in this StringBuilder.
void	setCharAt(int index, char ch) Sets the character at the specified offset in this StringBuilder.
void	setLength(int length) Sets the length of this StringBuilder to the specified length.
CharSequence	subSequence(int start, int end) Copies a range of characters into a new String.
String	substring(int start) Copies a range of characters into a new String.
String	substring(int start, int end) Copies a range of characters into a new String.
String	toString() Answers the contents of this StringBuilder.
void	trimToSize() Optionally modify the underlying char array to only be large enough to hold the characters in this StringBuffer.

Methods inherited from class java.lang.Object

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

Constructor Detail

StringBuilder

public StringBuilder()

Constructs a new StringBuffer using the default capacity.

StringBuilder

public StringBuilder(int capacity)

Constructs a new StringBuilder using the specified capacity.

Parameters:

capacity - the initial capacity

StringBuilder

public StringBuilder(String string)

Constructs a new StringBuilder containing the characters in the specified string and the default capacity.

Parameters:

string - the initial contents of this StringBuilder

Throws:

NullPointerException - when string is null

StringBuilder

public StringBuilder(CharSequence sequence)

Constructs a new StringBuilder containing the characters in the specified CharSequence and the default capacity.

Parameters:

sequence - the initial contents of this StringBuilder

Throws:

NullPointerException - when squence is null

Method Detail

append

public StringBuilder append(char[] chars)

Adds the character array to the end of this StringBuilder.

Parameters:

chars - the character array

Returns:

this StringBuilder

Throws:

NullPointerException - when chars is null

append

public StringBuilder append(char[] chars,
                            int start,
                            int length)

Adds the specified sequence of characters to the end of this StringBuilder.

Parameters:

chars - a character array

start - the starting offset

length - the number of characters

Returns:

this StringBuilder

Throws:

IndexOutOfBoundsException - when length < 0, start < 0 or start + length > chars.length

NullPointerException - when chars is null

append

public StringBuilder append(char ch)

Adds the specified character to the end of this StringBuilder.

Specified by:

append in interface Appendable

Parameters:

ch - a character

Returns:

this StringBuilder

append

public StringBuilder append(double value)

Adds the string representation of the specified double to the end of this StringBuilder.

Parameters:

value - the double

Returns:

this StringBuilder

append

public StringBuilder append(float value)

Adds the string representation of the specified float to the end of this StringBuilder.

Parameters:

value - the float

Returns:

this StringBuilder

append

public StringBuilder append(int value)

Adds the string representation of the specified integer to the end of this StringBuilder.

Parameters:

value - the integer

Returns:

this StringBuilder

append

public StringBuilder append(long value)

Adds the string representation of the specified long to the end of this StringBuilder.

Parameters:

value - the long

Returns:

this StringBuilder

append

public StringBuilder append(Object value)

Adds the string representation of the specified object to the end of this StringBuilder.

Parameters:

value - the object

Returns:

this StringBuilder

append

public StringBuilder append(String string)

Adds the specified string to the end of this StringBuilder.

Parameters:

string - the string

Returns:

this StringBuilder

append

public StringBuilder append(boolean value)

Adds the string representation of the specified boolean to the end of this StringBuilder.

Parameters:

value - the boolean

Returns:

this StringBuilder

capacity

public int capacity()

Answers the number of characters this StringBuilder can hold without growing.

Returns:

the capacity of this StringBuilder

See Also:

ensureCapacity(int), length()

charAt

public char charAt(int index)

Answers the character at the specified offset in this StringBuilder.

Specified by:

charAt in interface CharSequence

Parameters:

index - the zero-based index in this StringBuilder

Returns:

the character at the index

Throws:

IndexOutOfBoundsException - when index < 0 or index >= length()

delete

public StringBuilder delete(int start,
                            int end)

Deletes a range of characters.

Parameters:

start - the offset of the first character

end - the offset one past the last character

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - when start < 0, start > end or end > length()

deleteCharAt

public StringBuilder deleteCharAt(int location)

Deletes a single character

Parameters:

location - the offset of the character to delete

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - when location < 0 or location >= length()

ensureCapacity

public void ensureCapacity(int min)

Ensures that this StringBuilder can hold the specified number of characters without growing.

Parameters:

min - the minimum number of elements that this StringBuilder will hold before growing

getChars

public void getChars(int start,
                     int end,
                     char[] buffer,
                     int index)

Copies the specified characters in this StringBuilder to the character array starting at the specified offset in the character array.

Parameters:

start - the starting offset of characters to copy

end - the ending offset of characters to copy

buffer - the destination character array

index - the starting offset in the character array

Throws:

IndexOutOfBoundsException - when start < 0, end > length(), start > end, index < 0, end - start > buffer.length - index

NullPointerException - when buffer is null

insert

public StringBuilder insert(int index,
                            char[] chars)

Inserts the character array at the specified offset in this StringBuilder.

Parameters:

index - the index at which to insert

chars - the character array to insert

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - when index < 0 or index > length()

NullPointerException - when chars is null

insert

public StringBuilder insert(int index,
                            char[] chars,
                            int start,
                            int length)

Inserts the specified sequence of characters at the specified offset in this StringBuilder.

Parameters:

index - the index at which to insert

chars - a character array

start - the starting offset

length - the number of characters

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - when length < 0, start < 0, start + length > chars.length, index < 0 or index > length()

NullPointerException - when chars is null

insert

public StringBuilder insert(int index,
                            char ch)

Inserts the character at the specified offset in this StringBuilder.

Parameters:

index - the index at which to insert

ch - the character to insert

Returns:

this StringBuilder

Throws:

IndexOutOfBoundsException - when index < 0 or index > length()

insert

public StringBuilder insert(int index,
                            double value)

Inserts the string representation of the specified double at the specified offset in this StringBuilder.

Parameters:

index - the index at which to insert

value - the double to insert

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - when index < 0 or index > length()

insert

public StringBuilder insert(int index,
                            float value)

Inserts the string representation of the specified float at the specified offset in this StringBuilder.

Parameters:

index - the index at which to insert

value - the float to insert

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - when index < 0 or index > length()

insert

public StringBuilder insert(int index,
                            int value)

Inserts the string representation of the specified integer at the specified offset in this StringBuilder.

Parameters:

index - the index at which to insert

value - the integer to insert

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - when index < 0 or index > length()

insert

public StringBuilder insert(int index,
                            long value)

Inserts the string representation of the specified long at the specified offset in this StringBuilder.

Parameters:

index - the index at which to insert

value - the long to insert

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - when index < 0 or index > length()

insert

public StringBuilder insert(int index,
                            Object value)

Inserts the string representation of the specified object at the specified offset in this StringBuilder.

Parameters:

index - the index at which to insert

value - the object to insert

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - when index < 0 or index > length()

insert

public StringBuilder insert(int index,
                            String string)

Inserts the string at the specified offset in this StringBuilder.

Parameters:

index - the index at which to insert

string - the string to insert

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - when index < 0 or index > length()

insert

public StringBuilder insert(int index,
                            boolean value)

Inserts the string representation of the specified boolean at the specified offset in this StringBuilder.

Parameters:

index - the index at which to insert

value - the boolean to insert

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - when index < 0 or index > length()

length

public int length()

Answers the size of this StringBuilder.

Specified by:

length in interface CharSequence

Returns:

the number of characters in this StringBuilder

replace

public StringBuilder replace(int start,
                             int end,
                             String string)

Replace a range of characters with the characters in the specified String.

Parameters:

start - the offset of the first character

end - the offset one past the last character

string - a String

Returns:

this StringBuilder

Throws:

StringIndexOutOfBoundsException - when start < 0 or start > end

reverse

public StringBuilder reverse()

Reverses the order of characters in this StringBuilder.

Returns:

this StringBuilder

setCharAt

public void setCharAt(int index,
                      char ch)

Sets the character at the specified offset in this StringBuilder.

Parameters:

index - the zero-based index in this StringBuilder

ch - the character

Throws:

IndexOutOfBoundsException - when index < 0 or index >= length()

setLength

public void setLength(int length)

Sets the length of this StringBuilder to the specified length. If there are more than length characters in this StringBuilder, the characters at end are lost. If there are less than length characters in the StringBuilder, the additional characters are set to \\u0000.

Parameters:

length - the new length of this StringBuilder

Throws:

IndexOutOfBoundsException - when length < 0

See Also:

length()

substring

public String substring(int start)

Copies a range of characters into a new String.

Parameters:

start - the offset of the first character

Returns:

a new String containing the characters from start to the end of the string

Throws:

StringIndexOutOfBoundsException - when start < 0 or start > length()

substring

public String substring(int start,
                        int end)

Copies a range of characters into a new String.

Parameters:

start - the offset of the first character

end - the offset one past the last character

Returns:

a new String containing the characters from start to end - 1

Throws:

StringIndexOutOfBoundsException - when start < 0, start > end or end > length()

toString

public String toString()

Answers the contents of this StringBuilder.

Specified by:

toString in interface CharSequence

Overrides:

toString in class Object

Returns:

a String containing the characters in this StringBuilder

append

public StringBuilder append(StringBuffer buffer)

Adds the specified StringBuffer to the end of this StringBuilder.

Parameters:

buffer - the StringBuffer

Returns:

this StringBuilder

subSequence

public CharSequence subSequence(int start,
                                int end)

Copies a range of characters into a new String.

Specified by:

subSequence in interface CharSequence

Parameters:

start - the offset of the first character

end - the offset one past the last character

Returns:

a new String containing the characters from start to end - 1

Throws:

IndexOutOfBoundsException - when start < 0, start > end or end > length()

indexOf

public int indexOf(String string)

Searches in this StringBuilder for the first index of the specified character. The search for the character starts at the beginning and moves towards the end.

Parameters:

string - the string to find

Returns:

the index in this StringBuilder of the specified character, -1 if the character isn't found

See Also:

lastIndexOf(String)

indexOf

public int indexOf(String subString,
                   int start)

Searches in this StringBuilder for the index of the specified character. The search for the character starts at the specified offset and moves towards the end.

Parameters:

subString - the string to find

start - the starting offset

Returns:

the index in this StringBuilder of the specified character, -1 if the character isn't found

See Also:

lastIndexOf(String,int)

lastIndexOf

public int lastIndexOf(String string)

Searches in this StringBuilder for the last index of the specified character. The search for the character starts at the end and moves towards the beginning.

Parameters:

string - the string to find

Returns:

the index in this StringBuilder of the specified character, -1 if the character isn't found

See Also:

indexOf(String)

lastIndexOf

public int lastIndexOf(String subString,
                       int start)

Searches in this StringBuilder for the index of the specified character. The search for the character starts at the specified offset and moves towards the beginning.

Parameters:

subString - the string to find

start - the starting offset

Returns:

the index in this StringBuilder of the specified character, -1 if the character isn't found

See Also:

indexOf(String,int)

append

public StringBuilder append(CharSequence sequence)

Adds the specified CharSequence to the end of this StringBuilder.

Specified by:

append in interface Appendable

Parameters:

sequence - the CharSequence

Returns:

this StringBuilder

append

public StringBuilder append(CharSequence sequence,
                            int start,
                            int end)

Adds the specified CharSequence to the end of this StringBuilder.

Specified by:

append in interface Appendable

Parameters:

sequence - the CharSequence

start - the offset of the first character

end - the offset one past the last character

Returns:

this StringBuilder

Throws:

IndexOutOfBoundsException - when start < 0, start > end or end > length()

insert

public StringBuilder insert(int index,
                            CharSequence sequence)

Inserts the CharSequence at the specified offset in this StringBuilder.

Parameters:

index - the index at which to insert

sequence - the CharSequence to insert

Returns:

this StringBuilder

Throws:

IndexOutOfBoundsException - when index < 0 or index > length()

insert

public StringBuilder insert(int index,
                            CharSequence sequence,
                            int start,
                            int end)

Inserts the CharSequence at the specified offset in this StringBuilder.

Parameters:

index - the index at which to insert

sequence - the CharSequence to insert

start - the offset of the first character

end - the offset one past the last character

Returns:

this StringBuilder

Throws:

IndexOutOfBoundsException - when index < 0 or index > length(), or when start < 0, start > end or end > length()

trimToSize

public void trimToSize()

Optionally modify the underlying char array to only be large enough to hold the characters in this StringBuffer.

codePointAt

public int codePointAt(int index)

Returns the Unicode character at the given point.

Parameters:

index - the character index

Returns:

the Unicode character value at the index

codePointBefore

public int codePointBefore(int index)

Returns the Unicode character before the given point.

Parameters:

index - the character index

Returns:

the Unicode character value before the index

codePointCount

public int codePointCount(int start,
                          int end)

Returns the total Unicode values in the specified range.

Parameters:

start - first index

end - last index

Returns:

the total Unicode values

offsetByCodePoints

public int offsetByCodePoints(int start,
                              int codePointCount)

Returns the index of the code point that was offset by codePointCount.

Parameters:

start - the position to offset

codePointCount - the code point count

Returns:

the offset index

appendCodePoint

public StringBuilder appendCodePoint(int codePoint)

Adds the specified code point to the end of this StringBuffer.

Parameters:

codePoint - the code point

Returns:

this StringBuffer