java.lang

Class StringBuilder

java.lang.Object
- java.lang.AbstractStringBuffer
- - java.lang.StringBuilder

Implemented Interfaces:: Appendable, CharSequence, Serializable

public final class StringBuilder

extends java.lang.AbstractStringBuffer

implements Serializable, CharSequence, Appendable

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, Serialized Form

Constructor Summary
`StringBuilder()` Create a new StringBuilder with default capacity 16.
`StringBuilder(int capacity)` Create an empty `StringBuilder` with the specified initial capacity.
`StringBuilder(CharSequence seq)` Create a new `StringBuilder` with the characters in the specified `CharSequence`.
`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(CharSequence seq)` Append the characters in the `CharSequence` to this buffer.
`StringBuilder`	`append(CharSequence seq, int start, int end)` Append some characters from the `CharSequence` to this buffer.
`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`.
`StringBuilder`	`append(long lnum)` Append the `String` value of the argument to this `StringBuilder`.
`StringBuilder`	`appendCodePoint(int code)` Append the code point to this `StringBuilder`.
`int`	`capacity()` Get the total number of characters this `StringBuilder` can support before it must be grown.
`StringBuilder`	`delete(int start, int end)` Delete characters from this `StringBuilder`.
`StringBuilder`	`deleteCharAt(int index)` Delete a character from this `StringBuilder`.
`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, CharSequence sequence)` Insert the `CharSequence` argument into this `StringBuilder`.
`StringBuilder`	`insert(int offset, CharSequence sequence, int start, int end)` Insert a subsequence of the `CharSequence` 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`.
`StringBuilder`	`insert(int offset, long lnum)` Insert the `String` value of the argument into this `StringBuilder`.
`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.
`CharSequence`	`subSequence(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`	`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`.

append, append, append, append, append, append, append, append, append, append, append, append, append, appendCodePoint, charAt, codePointAt, codePointBefore, codePointCount, delete, deleteCharAt, ensureCapacity, getChars, indexOf, indexOf, insert, insert, insert, insert, insert, insert, insert, insert, insert, insert, insert, insert, lastIndexOf, lastIndexOf, offsetByCodePoints, replace, reverse, setCharAt, setLength, trimToSize

Methods inherited from class java.lang.Object
`clone`, `equals`, `extends Object> getClass`, `finalize`, `hashCode`, `notify`, `notifyAll`, `toString`, `wait`, `wait`, `wait`

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

Create a new StringBuilder with the characters in the specified CharSequence. Initial capacity will be the length of the sequence plus 16; if the sequence reports a length less than or equal to 0, then the initial capacity will be 16.
Parameters:
seq - the initializing CharSequence
Throws:
NullPointerException - if str is null

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

append

public StringBuilder append(boolean bool)

Append the String value of the argument to this StringBuilder. Uses String.valueOf() to convert to String.
Overrides:
append in interface java.lang.AbstractStringBuffer
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.
Specified by:
append in interface Appendable
Overrides:
append in interface java.lang.AbstractStringBuffer
Parameters:
ch - the char to append
Returns:
this StringBuilder

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.
Overrides:
append in interface java.lang.AbstractStringBuffer
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.
Overrides:
append in interface java.lang.AbstractStringBuffer
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(double dnum)

Append the String value of the argument to this StringBuilder. Uses String.valueOf() to convert to String.
Overrides:
append in interface java.lang.AbstractStringBuffer
Parameters:
dnum - the double to convert and append
Returns:
this StringBuilder
See Also:
String.valueOf(double)

append

public StringBuilder append(float fnum)

Append the String value of the argument to this StringBuilder. Uses String.valueOf() to convert to String.
Overrides:
append in interface java.lang.AbstractStringBuffer
Parameters:
fnum - the float to convert and append
Returns:
this StringBuilder
See Also:
String.valueOf(float)

append

public StringBuilder append(int inum)

Append the String value of the argument to this StringBuilder. Uses String.valueOf() to convert to String.
Overrides:
append in interface java.lang.AbstractStringBuffer
Parameters:
inum - the int to convert and append
Returns:
this StringBuilder
See Also:
String.valueOf(int)

append

public StringBuilder append(CharSequence seq)

Append the characters in the CharSequence to this buffer.
Specified by:
append in interface Appendable
Overrides:
append in interface java.lang.AbstractStringBuffer
Parameters:
seq - the CharSequence providing the characters
Returns:
this StringBuilder

append

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

Append some characters from the CharSequence to this buffer. If the argument is null, the four characters "null" are appended.
Specified by:
append in interface Appendable
Overrides:
append in interface java.lang.AbstractStringBuffer
Parameters:
seq - the CharSequence providing the characters
start - the starting index
end - one past the final index
Returns:
this StringBuilder

append

public StringBuilder append(Object obj)

Append the String value of the argument to this StringBuilder. Uses String.valueOf() to convert to String.
Overrides:
append in interface java.lang.AbstractStringBuffer
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.
Overrides:
append in interface java.lang.AbstractStringBuffer
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.
Overrides:
append in interface java.lang.AbstractStringBuffer
Parameters:
stringBuffer - the StringBuilder to convert and append
Returns:
this StringBuilder
See Also:
append(Object)

append

public StringBuilder append(long lnum)

Append the String value of the argument to this StringBuilder. Uses String.valueOf() to convert to String.
Overrides:
append in interface java.lang.AbstractStringBuffer
Parameters:
lnum - the long to convert and append
Returns:
this StringBuilder
See Also:
String.valueOf(long)

appendCodePoint

public StringBuilder appendCodePoint(int code)

Append the code point to this StringBuilder. This is like #append(char), but will append two characters if a supplementary code point is given.
Overrides:
appendCodePoint in interface java.lang.AbstractStringBuffer
Parameters:
code - the code point to append
Returns:
this StringBuilder
Since:
1.5
See Also:
Character.toChars(int,char[],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)

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().
Overrides:
delete in interface java.lang.AbstractStringBuffer
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.
Overrides:
deleteCharAt in interface java.lang.AbstractStringBuffer
Parameters:
index - the index of the character to delete
Returns:
this StringBuilder
Throws:
StringIndexOutOfBoundsException - if index is out of bounds

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.
Overrides:
insert in interface java.lang.AbstractStringBuffer
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.
Overrides:
insert in interface java.lang.AbstractStringBuffer
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,
                            char[] data)

Insert the char[] argument into this StringBuilder.
Overrides:
insert in interface java.lang.AbstractStringBuffer
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,
                            char[] str,
                            int str_offset,
                            int len)

Insert a subarray of the char[] argument into this StringBuilder.
Overrides:
insert in interface java.lang.AbstractStringBuffer
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,
                            double dnum)

Insert the String value of the argument into this StringBuilder. Uses String.valueOf() to convert to String.
Overrides:
insert in interface java.lang.AbstractStringBuffer
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)

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.
Overrides:
insert in interface java.lang.AbstractStringBuffer
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,
                            int inum)

Insert the String value of the argument into this StringBuilder. Uses String.valueOf() to convert to String.
Overrides:
insert in interface java.lang.AbstractStringBuffer
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,
                            CharSequence sequence)

Insert the CharSequence argument into this StringBuilder. If the sequence is null, the String "null" is used instead.
Overrides:
insert in interface java.lang.AbstractStringBuffer
Parameters:
offset - the place to insert in this buffer
sequence - the CharSequence to insert
Returns:
this StringBuilder
Throws:
IndexOutOfBoundsException - if offset is out of bounds

insert

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

Insert a subsequence of the CharSequence argument into this StringBuilder. If the sequence is null, the String "null" is used instead.
Overrides:
insert in interface java.lang.AbstractStringBuffer
Parameters:
offset - the place to insert in this buffer
sequence - the CharSequence to insert
start - the starting index of the subsequence
end - one past the ending index of the subsequence
Returns:
this StringBuilder
Throws:
IndexOutOfBoundsException - if offset, start, or end are 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.
Overrides:
insert in interface java.lang.AbstractStringBuffer
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.
Overrides:
insert in interface java.lang.AbstractStringBuffer
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,
                            long lnum)

Insert the String value of the argument into this StringBuilder. Uses String.valueOf() to convert to String.
Overrides:
insert in interface java.lang.AbstractStringBuffer
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)

length

public int length()

Get the length of the String this StringBuilder would create. Not to be confused with the capacity of the StringBuilder.
Specified by:
length in interface CharSequence
Returns:
the length of this StringBuilder
See Also:
capacity(), setLength(int)

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.
Overrides:
replace in interface java.lang.AbstractStringBuffer
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

reverse

public StringBuilder reverse()

Reverse the characters in this StringBuilder. The same sequence of characters exists, but in the reverse index ordering.
Overrides:
reverse in interface java.lang.AbstractStringBuffer
Returns:
this StringBuilder

subSequence

public CharSequence subSequence(int beginIndex,
                                int endIndex)

Creates a substring of this StringBuilder, starting at a specified index and ending at one character before a specified index. This is implemented the same as substring(beginIndex, endIndex), to satisfy the CharSequence interface.
Specified by:
subSequence in interface CharSequence
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:
IndexOutOfBoundsException - if beginIndex or endIndex is out of bounds
See Also:
substring(int,int)

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

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.
Specified by:
toString in interface CharSequence
Overrides:
toString in interface Object
Returns:
the characters in this StringBuilder

StringBuilder.java -- Unsynchronized growable strings Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2008 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

Overview Package Class Use Source Tree Index Deprecated About
Prev Class \| Next Class		Frames \| No Frames
Summary: Nested \| Field \| Method \| Constr	Detail: Nested \| Field \| Method \| Constr

java.lang

Class StringBuilder

Constructor Summary

Method Summary

Methods inherited from class java.lang.AbstractStringBuffer

Methods inherited from class java.lang.Object

Constructor Details

StringBuilder

StringBuilder

StringBuilder

StringBuilder

Method Details

append

append

append

append

append

append

append

append

append

append

append

append

append

appendCodePoint

capacity

delete

deleteCharAt

insert

insert

insert

insert

insert

insert

insert

insert

insert

insert

insert

insert

length

replace

reverse

subSequence

substring

substring

toString