Summary: Ctors | Methods | Inherited Methods | [Expand All]

public final class

StringBuilder

extends Object
implements Serializable Appendable CharSequence

java.lang.Object
↳	java.lang.StringBuilder

Class Overview

A modifiable sequence of characters for use in creating strings. This class is intended as a direct replacement of StringBuffer for non-concurrent use; unlike StringBuffer this class is not synchronized.

For particularly complex string-building needs, consider Formatter.

The majority of the modification methods on this class return this so that method calls can be chained together. For example: new StringBuilder("a").append("b").append("c").toString().

Summary

Public Constructors
	StringBuilder() Constructs an instance with an initial capacity of `16`.
	StringBuilder(int capacity) Constructs an instance with the specified capacity.
	StringBuilder(CharSequence seq) Constructs an instance that's initialized with the contents of the specified `CharSequence`.
	StringBuilder(String str) Constructs an instance that's initialized with the contents of the specified `String`.

Public Methods
StringBuilder	append(char[] str, int offset, int len) Appends the string representation of the specified subset of the `char[]`.
StringBuilder	append(double d) Appends the string representation of the specified `double` value.
StringBuilder	append(long l) Appends the string representation of the specified `long` value.
StringBuilder	append(boolean b) Appends the string representation of the specified `boolean` value.
StringBuilder	append(float f) Appends the string representation of the specified `float` value.
StringBuilder	append(char[] chars) Appends the string representation of the specified `char[]`.
StringBuilder	append(int i) Appends the string representation of the specified `int` value.
StringBuilder	append(StringBuffer sb) Appends the contents of the specified `StringBuffer`.
StringBuilder	append(CharSequence csq) Appends the string representation of the specified `CharSequence`.
StringBuilder	append(char c) Appends the string representation of the specified `char` value.
StringBuilder	append(String str) Appends the contents of the specified string.
StringBuilder	append(CharSequence csq, int start, int end) Appends the string representation of the specified subsequence of the `CharSequence`.
StringBuilder	append(Object obj) Appends the string representation of the specified `Object`.
StringBuilder	appendCodePoint(int codePoint) Appends the encoded Unicode code point.
int	capacity() Returns the number of characters that can be held without growing.
char	charAt(int index) Retrieves the character at the `index`.
int	codePointAt(int index) Retrieves the Unicode code point value at the `index`.
int	codePointBefore(int index) Retrieves the Unicode code point value that precedes the `index`.
int	codePointCount(int beginIndex, int endIndex) Calculates the number of Unicode code points between `beginIndex` and `endIndex`.
StringBuilder	delete(int start, int end) Deletes a sequence of characters specified by `start` and `end`.
StringBuilder	deleteCharAt(int index) Deletes the character at the specified index.
void	ensureCapacity(int min) Ensures that this object has a minimum capacity available before requiring the internal buffer to be enlarged.
void	getChars(int start, int end, char[] dst, int dstStart) Copies the requested sequence of characters into `dst` passed starting at `dst`.
int	indexOf(String subString, int start) Searches for the index of the specified character.
int	indexOf(String string) Searches for the first index of the specified character.
StringBuilder	insert(int offset, CharSequence s, int start, int end) Inserts the string representation of the specified subsequence of the `CharSequence` at the specified `offset`.
StringBuilder	insert(int offset, int i) Inserts the string representation of the specified `int` value at the specified `offset`.
StringBuilder	insert(int offset, double d) Inserts the string representation of the specified `double` value at the specified `offset`.
StringBuilder	insert(int offset, char[] str, int strOffset, int strLen) Inserts the string representation of the specified subsequence of the `char[]` at the specified `offset`.
StringBuilder	insert(int offset, String str) Inserts the specified string at the specified `offset`.
StringBuilder	insert(int offset, long l) Inserts the string representation of the specified `long` value at the specified `offset`.
StringBuilder	insert(int offset, Object obj) Inserts the string representation of the specified `Object` at the specified `offset`.
StringBuilder	insert(int offset, float f) Inserts the string representation of the specified `float` value at the specified `offset`.
StringBuilder	insert(int offset, char c) Inserts the string representation of the specified `char` value at the specified `offset`.
StringBuilder	insert(int offset, char[] ch) Inserts the string representation of the specified `char[]` at the specified `offset`.
StringBuilder	insert(int offset, CharSequence s) Inserts the string representation of the specified `CharSequence` at the specified `offset`.
StringBuilder	insert(int offset, boolean b) Inserts the string representation of the specified `boolean` value at the specified `offset`.
int	lastIndexOf(String string) Searches for the last index of the specified character.
int	lastIndexOf(String subString, int start) Searches for the index of the specified character.
int	length() The current length.
int	offsetByCodePoints(int index, int codePointOffset) Returns the index that is offset `codePointOffset` code points from `index`.
StringBuilder	replace(int start, int end, String str) Replaces the specified subsequence in this builder with the specified string.
StringBuilder	reverse() Reverses the order of characters in this builder.
void	setCharAt(int index, char ch) Sets the character at the `index`.
void	setLength(int length) Sets the current length to a new value.
CharSequence	subSequence(int start, int end) Returns a `CharSequence` of the subsequence from the `start` index to the `end` index.
String	substring(int start) Returns the String value of the subsequence from the `start` index to the current end.
String	substring(int start, int end) Returns the String value of the subsequence from the `start` index to the `end` index.
String	toString() Returns the contents of this builder.
void	trimToSize() Trims off any extra capacity beyond the current length.

[Expand]

Inherited Methods

From class java.lang.Object

Object	clone() Creates and returns a copy of this `Object`.
boolean	equals(Object o) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Called before the object's memory is reclaimed by the VM.
final Class<? extends Object>	getClass() Returns the unique instance of `Class` that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.
final void	wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait(long millis) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.

From interface java.lang.Appendable

From interface java.lang.CharSequence

Public Constructors

public StringBuilder ()

Since: API Level 1

Constructs an instance with an initial capacity of 16.

public StringBuilder (int capacity)

Since: API Level 1

Constructs an instance with the specified capacity.

Parameters

capacity	the initial capacity to use.

Throws

NegativeArraySizeException	if the specified `capacity` is negative.

public StringBuilder (CharSequence seq)

Since: API Level 1

Constructs an instance that's initialized with the contents of the specified CharSequence. The capacity of the new builder will be the length of the CharSequence plus 16.

Parameters

seq	the `CharSequence` to copy into the builder.

Throws

NullPointerException	if `seq` is `null`.

public StringBuilder (String str)

Since: API Level 1

Constructs an instance that's initialized with the contents of the specified String. The capacity of the new builder will be the length of the String plus 16.

Parameters

str	the `String` to copy into the builder.

Throws

NullPointerException	if `str` is `null`.

Public Methods

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

Since: API Level 1

Appends the string representation of the specified subset of the char[]. The char[] value is converted to a String according to the rule defined by valueOf(char[], int, int).

Parameters

str	the `char[]` to append.
offset	the inclusive offset index.
len	the number of characters.

Returns

this builder.

Throws

ArrayIndexOutOfBoundsException	if `offset` and `len` do not specify a valid subsequence.

public StringBuilder append (double d)

Since: API Level 1

Appends the string representation of the specified double value. The double value is converted to a string according to the rule defined by valueOf(double).

Parameters

d	the `double` value to append.

Returns

this builder.

public StringBuilder append (long l)

Since: API Level 1

Appends the string representation of the specified long value. The long value is converted to a string according to the rule defined by valueOf(long).

Parameters

l	the `long` value.

Returns

this builder.

public StringBuilder append (boolean b)

Since: API Level 1

Appends the string representation of the specified boolean value. The boolean value is converted to a String according to the rule defined by valueOf(boolean).

Parameters

b	the `boolean` value to append.

Returns

this builder.

public StringBuilder append (float f)

Since: API Level 1

Appends the string representation of the specified float value. The float value is converted to a string according to the rule defined by valueOf(float).

Parameters

f	the `float` value to append.

Returns

this builder.

public StringBuilder append (char[] chars)

Since: API Level 1

Appends the string representation of the specified char[]. The char[] is converted to a string according to the rule defined by valueOf(char[]).

Parameters

chars	the `char[]` to append..

Returns

this builder.

public StringBuilder append (int i)

Since: API Level 1

Appends the string representation of the specified int value. The int value is converted to a string according to the rule defined by valueOf(int).

Parameters

i	the `int` value to append.

Returns

this builder.

public StringBuilder append (StringBuffer sb)

Since: API Level 1

Appends the contents of the specified StringBuffer. If the StringBuffer is null, then the string "null" is appended.

Parameters

sb	the `StringBuffer` to append.

Returns

this builder.

public StringBuilder append (CharSequence csq)

Since: API Level 1

Appends the string representation of the specified CharSequence. If the CharSequence is null, then the string "null" is appended.

Parameters

csq	the `CharSequence` to append.

Returns

this builder.

public StringBuilder append (char c)

Since: API Level 1

Appends the string representation of the specified char value. The char value is converted to a string according to the rule defined by valueOf(char).

Parameters

c	the `char` value to append.

Returns

this builder.

public StringBuilder append (String str)

Since: API Level 1

Appends the contents of the specified string. If the string is null, then the string "null" is appended.

Parameters

str	the string to append.

Returns

this builder.

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

Since: API Level 1

Appends the string representation of the specified subsequence of the CharSequence. If the CharSequence is null, then the string "null" is used to extract the subsequence from.

Parameters

csq	the `CharSequence` to append.
start	the beginning index.
end	the ending index.

Returns

this builder.

Throws

IndexOutOfBoundsException	if `start` or `end` are negative, `start` is greater than `end` or `end` is greater than the length of `csq`.

public StringBuilder append (Object obj)

Since: API Level 1

Appends the string representation of the specified Object. The Object value is converted to a string according to the rule defined by valueOf(Object).

Parameters

obj	the `Object` to append.

Returns

this builder.

public StringBuilder appendCodePoint (int codePoint)

Since: API Level 1

Appends the encoded Unicode code point. The code point is converted to a char[] as defined by toChars(int).

Parameters

codePoint	the Unicode code point to encode and append.

Returns

this builder.

public int capacity ()

Since: API Level 1

Returns the number of characters that can be held without growing.

Returns

the capacity

public char charAt (int index)

Since: API Level 1

Retrieves the character at the index.

Parameters

index	the index of the character to retrieve.

Returns

the char value.

Throws

IndexOutOfBoundsException	if `index` is negative or greater than or equal to the current `length()`.

public int codePointAt (int index)

Since: API Level 1

Retrieves the Unicode code point value at the index.

Parameters

index	the index to the `char` code unit.

Returns

the Unicode code point value.

Throws

IndexOutOfBoundsException	if `index` is negative or greater than or equal to `length()`.

public int codePointBefore (int index)

Since: API Level 1

Retrieves the Unicode code point value that precedes the index.

Parameters

index	the index to the `char` code unit within this object.

Returns

the Unicode code point value.

Throws

IndexOutOfBoundsException	if `index` is less than 1 or greater than `length()`.

public int codePointCount (int beginIndex, int endIndex)

Since: API Level 1

Calculates the number of Unicode code points between beginIndex and endIndex.

Parameters

beginIndex	the inclusive beginning index of the subsequence.
endIndex	the exclusive end index of the subsequence.

Returns

the number of Unicode code points in the subsequence.

Throws

IndexOutOfBoundsException	if `beginIndex` is negative or greater than `endIndex` or `endIndex` is greater than `length()`.

public StringBuilder delete (int start, int end)

Since: API Level 1

Deletes a sequence of characters specified by start and end. Shifts any remaining characters to the left.

Parameters

start	the inclusive start index.
end	the exclusive end index.

Returns

this builder.

Throws

StringIndexOutOfBoundsException	if `start` is less than zero, greater than the current length or greater than `end`.

public StringBuilder deleteCharAt (int index)

Since: API Level 1

Deletes the character at the specified index. shifts any remaining characters to the left.

Parameters

index	the index of the character to delete.

Returns

this builder.

Throws

StringIndexOutOfBoundsException	if `index` is less than zero or is greater than or equal to the current length.

public void ensureCapacity (int min)

Since: API Level 1

Ensures that this object has a minimum capacity available before requiring the internal buffer to be enlarged. The general policy of this method is that if the minimumCapacity is larger than the current capacity(), then the capacity will be increased to the largest value of either the minimumCapacity or the current capacity multiplied by two plus two. Although this is the general policy, there is no guarantee that the capacity will change.

Parameters

min	the new minimum capacity to set.

public void getChars (int start, int end, char[] dst, int dstStart)

Since: API Level 1

Copies the requested sequence of characters into dst passed starting at dst.

Parameters

start	the inclusive start index of the characters to copy.
end	the exclusive end index of the characters to copy.
dst	the `char[]` to copy the characters to.
dstStart	the inclusive start index of `dst` to begin copying to.

Throws

IndexOutOfBoundsException	if the `start` is negative, the `dstStart` is negative, the `start` is greater than `end`, the `end` is greater than the current `length()` or `dstStart + end - begin` is greater than `dst.length`.

public int indexOf (String subString, int start)

Since: API Level 1

Searches 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 of the specified character, -1 if the character isn't found

public int indexOf (String string)

Since: API Level 1

Searches 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 of the specified character, -1 if the character isn't found.

public StringBuilder insert (int offset, CharSequence s, int start, int end)

Since: API Level 1

Inserts the string representation of the specified subsequence of the CharSequence at the specified offset. The CharSequence is converted to a String as defined by subSequence(int, int). If the CharSequence is null, then the string "null" is used to determine the subsequence.

Parameters

offset	the index to insert at.
s	the `CharSequence` to insert.
start	the start of the subsequence of the character sequence.
end	the end of the subsequence of the character sequence.

Returns

this builder.

Throws

IndexOutOfBoundsException	if `offset` is negative or greater than the current `length()`, or `start` and `end` do not specify a valid subsequence.

public StringBuilder insert (int offset, int i)

Since: API Level 1

Inserts the string representation of the specified int value at the specified offset. The int value is converted to a String according to the rule defined by valueOf(int).

Parameters

offset	the index to insert at.
i	the `int` value to insert.

Returns

this builder.

Throws

StringIndexOutOfBoundsException	if `offset` is negative or greater than the current `length()`.

public StringBuilder insert (int offset, double d)

Since: API Level 1

Inserts the string representation of the specified double value at the specified offset. The double value is converted to a String according to the rule defined by valueOf(double).

Parameters

offset	the index to insert at.
d	the `double` value to insert.

Returns

this builder.

Throws

StringIndexOutOfBoundsException	if `offset` is negative or greater than the current `length()`.

public StringBuilder insert (int offset, char[] str, int strOffset, int strLen)

Since: API Level 1

Inserts the string representation of the specified subsequence of the char[] at the specified offset. The char[] value is converted to a String according to the rule defined by valueOf(char[], int, int).

Parameters

offset	the index to insert at.
str	the `char[]` to insert.
strOffset	the inclusive index.
strLen	the number of characters.

Returns

this builder.

Throws

StringIndexOutOfBoundsException	if `offset` is negative or greater than the current `length()`, or `strOffset` and `strLen` do not specify a valid subsequence.

public StringBuilder insert (int offset, String str)

Since: API Level 1

Inserts the specified string at the specified offset. If the specified string is null, then the String "null" is inserted.

Parameters

offset	the index to insert at.
str	the `String` to insert.

Returns

this builder.

Throws

StringIndexOutOfBoundsException	if `offset` is negative or greater than the current `length()`.

public StringBuilder insert (int offset, long l)

Since: API Level 1

Inserts the string representation of the specified long value at the specified offset. The long value is converted to a String according to the rule defined by valueOf(long).

Parameters

offset	the index to insert at.
l	the `long` value to insert.

Returns

this builder.

Throws

StringIndexOutOfBoundsException	if `offset` is negative or greater than the current {code length()}.

public StringBuilder insert (int offset, Object obj)

Since: API Level 1

Inserts the string representation of the specified Object at the specified offset. The Object value is converted to a String according to the rule defined by valueOf(Object).

Parameters

offset	the index to insert at.
obj	the `Object` to insert.

Returns

this builder.

Throws

StringIndexOutOfBoundsException	if `offset` is negative or greater than the current `length()`.

public StringBuilder insert (int offset, float f)

Since: API Level 1

Inserts the string representation of the specified float value at the specified offset. The float value is converted to a string according to the rule defined by valueOf(float).

Parameters

offset	the index to insert at.
f	the `float` value to insert.

Returns

this builder.

Throws

StringIndexOutOfBoundsException	if `offset` is negative or greater than the current `length()`.

public StringBuilder insert (int offset, char c)

Since: API Level 1

Inserts the string representation of the specified char value at the specified offset. The char value is converted to a string according to the rule defined by valueOf(char).

Parameters

offset	the index to insert at.
c	the `char` value to insert.

Returns

this builder.

Throws

IndexOutOfBoundsException	if `offset` is negative or greater than the current `length()`.

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

Since: API Level 1

Inserts the string representation of the specified char[] at the specified offset. The char[] value is converted to a String according to the rule defined by valueOf(char[]).

Parameters

offset	the index to insert at.
ch	the `char[]` to insert.

Returns

this builder.

Throws

StringIndexOutOfBoundsException	if `offset` is negative or greater than the current `length()`.

public StringBuilder insert (int offset, CharSequence s)

Since: API Level 1

Inserts the string representation of the specified CharSequence at the specified offset. The CharSequence is converted to a String as defined by toString(). If s is null, then the String "null" is inserted.

Parameters

offset	the index to insert at.
s	the `CharSequence` to insert.

Returns

this builder.

Throws

IndexOutOfBoundsException	if `offset` is negative or greater than the current `length()`.

public StringBuilder insert (int offset, boolean b)

Since: API Level 1

Inserts the string representation of the specified boolean value at the specified offset. The boolean value is converted to a string according to the rule defined by valueOf(boolean).

Parameters

offset	the index to insert at.
b	the `boolean` value to insert.

Returns

this builder.

Throws

StringIndexOutOfBoundsException	if `offset` is negative or greater than the current `length`.

public int lastIndexOf (String string)

Since: API Level 1

Searches 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 of the specified character, -1 if the character isn't found.

Throws

NullPointerException	if `string` is `null`.

public int lastIndexOf (String subString, int start)

Since: API Level 1

Searches 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 of the specified character, -1 if the character isn't found.

Throws

NullPointerException	if `subString` is `null`.

public int length ()

Since: API Level 1

The current length.

Returns

the number of characters contained in this instance.

public int offsetByCodePoints (int index, int codePointOffset)

Since: API Level 1

Returns the index that is offset codePointOffset code points from index.

Parameters

index	the index to calculate the offset from.
codePointOffset	the number of code points to count.

Returns

the index that is codePointOffset code points away from index.

Throws

IndexOutOfBoundsException	if `index` is negative or greater than `length()` or if there aren't enough code points before or after `index` to match `codePointOffset`.

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

Since: API Level 1

Replaces the specified subsequence in this builder with the specified string.

Parameters

start	the inclusive begin index.
end	the exclusive end index.
str	the replacement string.

Returns

this builder.

Throws

StringIndexOutOfBoundsException	if `start` is negative, greater than the current `length()` or greater than `end`.
NullPointerException	if `str` is `null`.

public StringBuilder reverse ()

Since: API Level 1

Reverses the order of characters in this builder.

Returns

this buffer.

public void setCharAt (int index, char ch)

Since: API Level 1

Sets the character at the index.

Parameters

index	the zero-based index of the character to replace.
ch	the character to set.

Throws

IndexOutOfBoundsException	if `index` is negative or greater than or equal to the current `length()`.

public void setLength (int length)

Since: API Level 1

Sets the current length to a new value. If the new length is larger than the current length, then the new characters at the end of this object will contain the char value of ence/java/lang/StringBuilder.html#length()">length()

public CharSequence subSequence (int start, int end)

Since: API Level 1

Returns a CharSequence of the subsequence from the start index to the end index.

Parameters

start	the inclusive start index to begin the subsequence.
end	the exclusive end index to end the subsequence.

Returns

a CharSequence containing the subsequence.

Throws

IndexOutOfBoundsException	if `start` is negative, greater than `end` or if `end` is greater than the current `length()`.

public String substring (int start)

Since: API Level 1

Returns the String value of the subsequence from the start index to the current end.

Parameters

start	the inclusive start index to begin the subsequence.

Returns

a String containing the subsequence.

Throws

StringIndexOutOfBoundsException	if `start` is negative or greater than the current `length()`.

public String substring (int start, int end)

Since: API Level 1

Returns the String value of the subsequence from the start index to the end index.

Parameters

start	the inclusive start index to begin the subsequence.
end	the exclusive end index to end the subsequence.

Returns

a String containing the subsequence.

Throws

StringIndexOutOfBoundsException	if `start` is negative, greater than `end` or if `end` is greater than the current `length()`.

public String toString ()

Since: API Level 1

Returns the contents of this builder.

Returns

the string representation of the data in this builder.

public void trimToSize ()

Since: API Level 1

Trims off any extra capacity beyond the current length. Note, this method is NOT guaranteed to change the capacity of this object.

Interfaces

Classes

Enums

Exceptions

Errors

StringBuilder

Class Overview

See Also

Summary

Public Constructors

public StringBuilder ()

See Also

public StringBuilder (int capacity)

Parameters

Throws

See Also

public StringBuilder (CharSequence seq)

Parameters

Throws

public StringBuilder (String str)

Parameters

Throws

Public Methods

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

Parameters

Returns

Throws

See Also

public StringBuilder append (double d)

Parameters

Returns

See Also

public StringBuilder append (long l)

Parameters

Returns

See Also

public StringBuilder append (boolean b)

Parameters

Returns

See Also

public StringBuilder append (float f)

Parameters

Returns

See Also

public StringBuilder append (char[] chars)

Parameters

Returns

See Also

public StringBuilder append (int i)

Parameters

Returns

See Also

public StringBuilder append (StringBuffer sb)

Parameters

Returns

public StringBuilder append (CharSequence csq)

Parameters

Returns

public StringBuilder append (char c)

Parameters

Returns

See Also

public StringBuilder append (String str)

Parameters

Returns

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

Parameters

Returns

Throws

public StringBuilder append (Object obj)

Parameters

Returns

See Also

public StringBuilder appendCodePoint (int codePoint)

Parameters

Returns

See Also

public int capacity ()

Returns

See Also