java.lang
Class StringBuilder
- CharSequence, Serializable
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.
StringBuilder
s 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).
- 1.5
String
, StringBuffer
, Serialized Form
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 .
|
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 .
|
int | capacity() - Get the total number of characters this
StringBuilder can
support before it must be grown.
|
char | charAt(int index) - Get the character at the specified index.
|
StringBuilder | delete(int start, int end) - Delete characters from this
StringBuilder .
|
StringBuilder | deleteCharAt(int index) - Delete a character from this
StringBuilder .
|
void | ensureCapacity(int minimumCapacity) - Increase the capacity of this
StringBuilder .
|
void | getChars(int srcOffset, int srcEnd, char[] dst, int dstOffset) - Get the specified array of characters.
|
int | indexOf(String str) - Finds the first instance of a substring in this StringBuilder.
|
int | indexOf(String str, int fromIndex) - Finds the first instance of a String in this StringBuilder, starting at
a given index.
|
StringBuilder | insert(int offset, boolean bool) - Insert the
String value of the argument into this
StringBuilder .
|
StringBuilder | insert(int offset, char ch) - Insert the
char argument into this StringBuilder .
|
StringBuilder | insert(int offset, char[] data) - Insert the
char[] argument into this
StringBuilder .
|
StringBuilder | insert(int offset, char[] str, int str_offset, int len) - Insert a subarray of the
char[] argument into this
StringBuilder .
|
StringBuilder | insert(int offset, double dnum) - Insert the
String value of the argument into this
StringBuilder .
|
StringBuilder | insert(int offset, float fnum) - Insert the
String value of the argument into this
StringBuilder .
|
StringBuilder | insert(int offset, int inum) - Insert the
String value of the argument into this
StringBuilder .
|
StringBuilder | insert(int offset, 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 | lastIndexOf(String str) - Finds the last instance of a substring in this StringBuilder.
|
int | lastIndexOf(String str, int fromIndex) - Finds the last instance of a String in this StringBuilder, starting at a
given index.
|
int | length() - Get the length of the
String this StringBuilder
would create.
|
StringBuilder | replace(int start, int end, String str) - Replace characters between index
start (inclusive) and
end (exclusive) with str .
|
StringBuilder | reverse() - Reverse the characters in this StringBuilder.
|
void | setCharAt(int index, char ch) - Set the character at the specified index.
|
void | setLength(int newLength) - Set the length of this StringBuilder.
|
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 .
|
clone , equals , finalize , getClass , 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.
capacity
- the initial capacity
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.
seq
- the initializing CharSequence
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.
str
- the String
to convert
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
.
bool
- the boolean
to convert and append
- this
StringBuilder
String.valueOf(boolean)
append
public StringBuilder append(char ch)
Append the char
to this StringBuilder
.
ch
- the char
to append
- this
StringBuilder
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.
data
- the char[]
to appendoffset
- the start location in str
count
- the number of characters to get from str
- this
StringBuilder
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
.
dnum
- the double
to convert and append
- this
StringBuilder
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
.
fnum
- the float
to convert and append
- this
StringBuilder
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
.
inum
- the int
to convert and append
- this
StringBuilder
String.valueOf(int)
append
public StringBuilder append(CharSequence seq)
Append the characters in the CharSequence
to this
buffer.
seq
- the CharSequence
providing the characters
- 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.
seq
- the CharSequence
providing the charactersstart
- the starting indexend
- one past the final index
- this
StringBuilder
append
public StringBuilder append(String str)
Append the String
to this StringBuilder
. If
str is null, the String "null" is appended.
str
- the String
to append
- 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.
stringBuffer
- the StringBuilder
to convert and append
- this
StringBuilder
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
.
lnum
- the long
to convert and append
- this
StringBuilder
String.valueOf(long)
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.
- the capacity of this
StringBuilder
length()
, ensureCapacity(int)
charAt
public char charAt(int index)
Get the character at the specified index.
- charAt in interface CharSequence
index
- the index of the character to get, starting at 0
- the character at the specified index
IndexOutOfBoundsException
- if index is negative or >= length()
(while unspecified, this is a StringIndexOutOfBoundsException)
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().
start
- the first character to deleteend
- the index after the last character to delete
- this
StringBuilder
StringIndexOutOfBoundsException
- if start or end are out of bounds
ensureCapacity
public void ensureCapacity(int minimumCapacity)
Increase the capacity of this StringBuilder
. This will
ensure that an expensive growing operation will not occur until
minimumCapacity
is reached. The buffer is grown to the
larger of minimumCapacity
and
capacity() * 2 + 2
, if it is not already large enough.
minimumCapacity
- the new capacity
capacity()
getChars
public void getChars(int srcOffset,
int srcEnd,
char[] dst,
int dstOffset)
Get the specified array of characters. srcOffset - srcEnd
characters will be copied into the array you pass in.
srcOffset
- the index to start copying from (inclusive)srcEnd
- the index to stop copying from (exclusive)dst
- the array to copy intodstOffset
- the index to start copying into
NullPointerException
- if dst is nullIndexOutOfBoundsException
- if any source or target indices are
out of range (while unspecified, source problems cause a
StringIndexOutOfBoundsException, and dest problems cause an
ArrayIndexOutOfBoundsException)
System.arraycopy(Object,int,Object,int,int)
indexOf
public int indexOf(String str,
int fromIndex)
Finds the first instance of a String in this StringBuilder, starting at
a given index. If starting index is less than 0, the search starts at
the beginning of this String. If the starting index is greater than the
length of this String, or the substring is not found, -1 is returned.
str
- String to findfromIndex
- index to start the search
- location (base 0) of the String, or -1 if not found
NullPointerException
- if str is null
insert
public StringBuilder insert(int offset,
char[] str,
int str_offset,
int len)
Insert a subarray of the char[]
argument into this
StringBuilder
.
offset
- the place to insert in this bufferstr
- the char[]
to insertstr_offset
- the index in str
to start inserting fromlen
- the number of characters to insert
- this
StringBuilder
NullPointerException
- if str
is null
StringIndexOutOfBoundsException
- if any index is out of bounds
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.
offset
- the place to insert in this bufferstr
- the String
to insert
- this
StringBuilder
StringIndexOutOfBoundsException
- if offset is out of bounds
lastIndexOf
public int lastIndexOf(String str,
int fromIndex)
Finds the last instance of a String in this StringBuilder, starting at a
given index. If starting index is greater than the maximum valid index,
then the search begins at the end of this String. If the starting index
is less than zero, or the substring is not found, -1 is returned.
str
- String to findfromIndex
- index to start the search
- location (base 0) of the String, or -1 if not found
NullPointerException
- if str is null
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.
start
- the beginning index of characters to delete (inclusive)end
- the ending index of characters to delete (exclusive)str
- the new String
to insert
- this
StringBuilder
StringIndexOutOfBoundsException
- if start or end are out of boundsNullPointerException
- 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.
- this
StringBuilder
setCharAt
public void setCharAt(int index,
char ch)
Set the character at the specified index.
index
- the index of the character to set starting at 0ch
- the value to set that character to
IndexOutOfBoundsException
- if index is negative or >= length()
(while unspecified, this is a StringIndexOutOfBoundsException)
setLength
public void setLength(int newLength)
Set the length of this StringBuilder. If the new length is greater than
the current length, all the new characters are set to '\0'. If the new
length is less than the current length, the first newLength
characters of the old array will be preserved, and the remaining
characters are truncated.
newLength
- the new length
IndexOutOfBoundsException
- if the new length is negative
(while unspecified, this is a StringIndexOutOfBoundsException)
length()
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.
- subSequence in interface CharSequence
beginIndex
- index to start at (inclusive, base 0)endIndex
- index to end at (exclusive)
- new String which is a substring of this StringBuilder
IndexOutOfBoundsException
- if beginIndex or endIndex is out of
bounds
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.
beginIndex
- index to start substring (base 0)
- new String which is a substring of this StringBuilder
StringIndexOutOfBoundsException
- if beginIndex is out of bounds
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.
beginIndex
- index to start at (inclusive, base 0)endIndex
- index to end at (exclusive)
- new String which is a substring of this StringBuilder
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.
- toString in interface CharSequence
- toString in interface Object
- the characters in this StringBuilder
StringBuilder.java -- Unsynchronized growable strings
Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005
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.