Skip to content

Most visited

Recently visited

navigation
Added in API level 1

StringBuilder

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

java.lang.Object
   ↳ java.lang.StringBuilder


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

See also:

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

Appends the string representation of the specified char value.

StringBuilder append(boolean b)

Appends the string representation of the specified boolean value.

StringBuilder append(long l)

Appends the string representation of the specified long 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(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(StringBuffer sb)

Appends the contents of the specified StringBuffer.

StringBuilder append(Object obj)

Appends the string representation of the specified Object.

StringBuilder append(CharSequence csq)

Appends the string representation of the specified CharSequence.

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)

Returns the character at 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 start, int end)

Calculates the number of Unicode code points between start and end.

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, 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, int i)

Inserts the string representation of the specified int 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, double d)

Inserts the string representation of the specified double value 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, 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, boolean b)

Inserts the string representation of the specified boolean value at the specified offset.

int lastIndexOf(String subString, int start)

Searches for the index of the specified character.

int lastIndexOf(String string)

Searches for the last 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 string)

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.

Inherited methods

From class java.lang.Object
From interface java.lang.Appendable
From interface java.lang.CharSequence

Public constructors

StringBuilder

Added in API level 1
StringBuilder ()

Constructs an instance with an initial capacity of 16.

See also:

StringBuilder

Added in API level 1
StringBuilder (int capacity)

Constructs an instance with the specified capacity.

Parameters
capacity int: the initial capacity to use.
Throws
NegativeArraySizeException if the specified capacity is negative.

See also:

StringBuilder

Added in API level 1
StringBuilder (CharSequence seq)

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 CharSequence: the CharSequence to copy into the builder.
Throws
NullPointerException if seq is null.

StringBuilder

Added in API level 1
StringBuilder (String str)

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 String: the String to copy into the builder.
Throws
NullPointerException if str is null.

Public methods

append

Added in API level 1
StringBuilder append (char[] str, 
                int offset, 
                int len)

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 char: the char[] to append.
offset int: the inclusive offset index.
len int: the number of characters.
Returns
StringBuilder this builder.
Throws
ArrayIndexOutOfBoundsException if offset and len do not specify a valid subsequence.

See also:

append

Added in API level 1
StringBuilder append (double d)

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 double: the double value to append.
Returns
StringBuilder this builder.

See also:

append

Added in API level 1
StringBuilder append (char c)

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 char: the char value to append.
Returns
StringBuilder this builder.

See also:

append

Added in API level 1
StringBuilder append (boolean b)

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 boolean: the boolean value to append.
Returns
StringBuilder this builder.

See also:

append

Added in API level 1
StringBuilder append (long l)

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 long: the long value.
Returns
StringBuilder this builder.

See also:

append

Added in API level 1
StringBuilder append (float f)

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 float: the float value to append.
Returns
StringBuilder this builder.

See also:

append

Added in API level 1
StringBuilder append (char[] chars)

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 char: the char[] to append..
Returns
StringBuilder this builder.

See also:

append

Added in API level 1
StringBuilder append (int i)

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 int: the int value to append.
Returns
StringBuilder this builder.

See also:

append

Added in API level 1
StringBuilder append (String str)

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

Parameters
str String: the string to append.
Returns
StringBuilder this builder.

append

Added in API level 1
StringBuilder append (CharSequence csq, 
                int start, 
                int end)

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 CharSequence: the CharSequence to append.
start int: the beginning index.
end int: the ending index.
Returns
StringBuilder this builder.
Throws
IndexOutOfBoundsException if start or end are negative, start is greater than end or end is greater than the length of csq.

append

Added in API level 1
StringBuilder append (StringBuffer sb)

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

Parameters
sb StringBuffer: the StringBuffer to append.
Returns
StringBuilder this builder.

append

Added in API level 1
StringBuilder append (Object obj)

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 Object: the Object to append.
Returns
StringBuilder this builder.

See also:

append

Added in API level 1
StringBuilder append (CharSequence csq)

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

Parameters
csq CharSequence: the CharSequence to append.
Returns
StringBuilder this builder.

appendCodePoint

Added in API level 1
StringBuilder appendCodePoint (int codePoint)

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

Parameters
codePoint int: the Unicode code point to encode and append.
Returns
StringBuilder this builder.

See also:

capacity

Added in API level 1
int capacity ()

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

Returns
int the capacity

See also:

charAt

Added in API level 1
char charAt (int index)

Returns the character at index.

Parameters
index int
Returns
char
Throws
IndexOutOfBoundsException if index < 0 or index >= length().

codePointAt

Added in API level 1
int codePointAt (int index)

Retrieves the Unicode code point value at the index.

Parameters
index int: the index to the char code unit.
Returns
int the Unicode code point value.
Throws
IndexOutOfBoundsException if index is negative or greater than or equal to length().

See also:

codePointBefore

Added in API level 1
int codePointBefore (int index)

Retrieves the Unicode code point value that precedes the index.

Parameters
index int: the index to the char code unit within this object.
Returns
int the Unicode code point value.
Throws
IndexOutOfBoundsException if index is less than 1 or greater than length().

See also:

codePointCount

Added in API level 1
int codePointCount (int start, 
                int end)

Calculates the number of Unicode code points between start and end.

Parameters
start int: the inclusive beginning index of the subsequence.
end int: the exclusive end index of the subsequence.
Returns
int the number of Unicode code points in the subsequence.
Throws
IndexOutOfBoundsException if start is negative or greater than end or end is greater than length().

See also:

delete

Added in API level 1
StringBuilder delete (int start, 
                int end)

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

Parameters
start int: the inclusive start index.
end int: the exclusive end index.
Returns
StringBuilder this builder.
Throws
StringIndexOutOfBoundsException if start is less than zero, greater than the current length or greater than end.

deleteCharAt

Added in API level 1
StringBuilder deleteCharAt (int index)

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

Parameters
index int: the index of the character to delete.
Returns
StringBuilder this builder.
Throws
StringIndexOutOfBoundsException if index is less than zero or is greater than or equal to the current length.

ensureCapacity

Added in API level 1
void ensureCapacity (int min)

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 int: the new minimum capacity to set.

getChars

Added in API level 1
void getChars (int start, 
                int end, 
                char[] dst, 
                int dstStart)

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

Parameters
start int: the inclusive start index of the characters to copy.
end int: the exclusive end index of the characters to copy.
dst char: the char[] to copy the characters to.
dstStart int: 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.

indexOf

Added in API level 1
int indexOf (String subString, 
                int start)

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 String: the string to find.
start int: the starting offset.
Returns
int the index of the specified character, -1 if the character isn't found

See also:

indexOf

Added in API level 1
int indexOf (String string)

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 String: the string to find.
Returns
int the index of the specified character, -1 if the character isn't found.

See also:

insert

Added in API level 1
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. 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 int: the index to insert at.
s CharSequence: the CharSequence to insert.
start int: the start of the subsequence of the character sequence.
end int: the end of the subsequence of the character sequence.
Returns
StringBuilder this builder.
Throws
IndexOutOfBoundsException if offset is negative or greater than the current length(), or start and end do not specify a valid subsequence.

See also:

insert

Added in API level 1
StringBuilder insert (int offset, 
                Object obj)

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 int: the index to insert at.
obj Object: the Object to insert.
Returns
StringBuilder this builder.
Throws
StringIndexOutOfBoundsException if offset is negative or greater than the current length().

See also:

insert

Added in API level 1
StringBuilder insert (int offset, 
                float f)

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 int: the index to insert at.
f float: the float value to insert.
Returns
StringBuilder this builder.
Throws
StringIndexOutOfBoundsException if offset is negative or greater than the current length().

See also:

insert

Added in API level 1
StringBuilder insert (int offset, 
                char c)

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 int: the index to insert at.
c char: the char value to insert.
Returns
StringBuilder this builder.
Throws
IndexOutOfBoundsException if offset is negative or greater than the current length().

See also:

insert

Added in API level 1
StringBuilder insert (int offset, 
                int i)

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 int: the index to insert at.
i int: the int value to insert.
Returns
StringBuilder this builder.
Throws
StringIndexOutOfBoundsException if offset is negative or greater than the current length().

See also:

insert

Added in API level 1
StringBuilder insert (int offset, 
                char[] ch)

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 int: the index to insert at.
ch char: the char[] to insert.
Returns
StringBuilder this builder.
Throws
StringIndexOutOfBoundsException if offset is negative or greater than the current length().

See also:

insert

Added in API level 1
StringBuilder insert (int offset, 
                double d)

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 int: the index to insert at.
d double: the double value to insert.
Returns
StringBuilder this builder.
Throws
StringIndexOutOfBoundsException if offset is negative or greater than the current length().

See also:

insert

Added in API level 1
StringBuilder insert (int offset, 
                CharSequence s)

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 int: the index to insert at.
s CharSequence: the CharSequence to insert.
Returns
StringBuilder this builder.
Throws
IndexOutOfBoundsException if offset is negative or greater than the current length().

See also:

insert

Added in API level 1
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. The char[] value is converted to a String according to the rule defined by valueOf(char[], int, int).

Parameters
offset int: the index to insert at.
str char: the char[] to insert.
strOffset int: the inclusive index.
strLen int: the number of characters.
Returns
StringBuilder this builder.
Throws
StringIndexOutOfBoundsException if offset is negative or greater than the current length(), or strOffset and strLen do not specify a valid subsequence.

See also:

insert

Added in API level 1
StringBuilder insert (int offset, 
                String str)

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

Parameters
offset int: the index to insert at.
str String: the String to insert.
Returns
StringBuilder this builder.
Throws
StringIndexOutOfBoundsException if offset is negative or greater than the current length().

insert

Added in API level 1
StringBuilder insert (int offset, 
                long l)

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 int: the index to insert at.
l long: the long value to insert.
Returns
StringBuilder this builder.
Throws
StringIndexOutOfBoundsException if offset is negative or greater than the current {code length()}.

See also:

insert

Added in API level 1
StringBuilder insert (int offset, 
                boolean b)

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 int: the index to insert at.
b boolean: the boolean value to insert.
Returns
StringBuilder this builder.
Throws
StringIndexOutOfBoundsException if offset is negative or greater than the current length.

See also:

lastIndexOf

Added in API level 1
int lastIndexOf (String subString, 
                int start)

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 String: the string to find.
start int: the starting offset.
Returns
int the index of the specified character, -1 if the character isn't found.
Throws
NullPointerException if subString is null.

See also:

lastIndexOf

Added in API level 1
int lastIndexOf (String string)

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 String: the string to find.
Returns
int the index of the specified character, -1 if the character isn't found.
Throws
NullPointerException if string is null.

See also:

length

Added in API level 1
int length ()

The current length.

Returns
int the number of characters contained in this instance.

offsetByCodePoints

Added in API level 1
int offsetByCodePoints (int index, 
                int codePointOffset)

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

Parameters
index int: the index to calculate the offset from.
codePointOffset int: the number of code points to count.
Returns
int 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.

See also:

replace

Added in API level 1
StringBuilder replace (int start, 
                int end, 
                String string)

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

Parameters
start int: the inclusive begin index.
end int: the exclusive end index.
string String: the replacement string.
Returns
StringBuilder this builder.
Throws
StringIndexOutOfBoundsException if start is negative, greater than the current length() or greater than end.
NullPointerException if str is null.

reverse

Added in API level 1
StringBuilder reverse ()

Reverses the order of characters in this builder.

Returns
StringBuilder this buffer.

setCharAt

Added in API level 1
void setCharAt (int index, 
                char ch)

Sets the character at the index.

Parameters
index int: the zero-based index of the character to replace.
ch char: the character to set.
Throws
IndexOutOfBoundsException if index is negative or greater than or equal to the current length().

setLength

Added in API level 1
void setLength (int length)

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 .

Parameters
length int: the new length of this StringBuffer.
Throws
IndexOutOfBoundsException if length < 0.

See also:

subSequence

Added in API level 1
CharSequence subSequence (int start, 
                int end)

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

Parameters
start int: the inclusive start index to begin the subsequence.
end int: the exclusive end index to end the subsequence.
Returns
CharSequence a CharSequence containing the subsequence.
Throws
IndexOutOfBoundsException if start is negative, greater than end or if end is greater than the current length().

substring

Added in API level 1
String substring (int start)

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

Parameters
start int: the inclusive start index to begin the subsequence.
Returns
String a String containing the subsequence.
Throws
StringIndexOutOfBoundsException if start is negative or greater than the current length().

substring

Added in API level 1
String substring (int start, 
                int end)

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

Parameters
start int: the inclusive start index to begin the subsequence.
end int: the exclusive end index to end the subsequence.
Returns
String a String containing the subsequence.
Throws
StringIndexOutOfBoundsException if start is negative, greater than end or if end is greater than the current length().

toString

Added in API level 1
String toString ()

Returns the contents of this builder.

Returns
String the string representation of the data in this builder.

trimToSize

Added in API level 1
void trimToSize ()

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

This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.