java.lang
Class StringBuilder

java.lang.Object
  java.lang.StringBuilder

All Implemented Interfaces:

Serializable, Appendable, CharSequence

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

This class can be used to work with variable length strings of characters.

Since:

1.5

See Also:

Serialized Form

Constructor Summary

StringBuilder()
Create a new StringBuilder with an initial capacity of 16 characters.

StringBuilder(CharSequence cs)
Create a new string buffer that contains the characters of the given CharSequence.

StringBuilder(int theCapacity)
Create a new StringBuilder with the given initial capacity.

StringBuilder(String str)
Create a new StringBuilder that contains the given String.

Method Summary

StringBuilder	append(boolean b) Append a boolean.
StringBuilder	append(char c) Append a character to the buffer.
StringBuilder	append(char[] str) Append character-data from the given char-array.
StringBuilder	append(char[] str, int offset, int len) Append character-data from the given char-array.
StringBuilder	append(CharSequence cs) Append a character sequence to the buffer.
StringBuilder	append(CharSequence cs, int start, int end) Append a sub-sequence of a character sequence to the buffer.
StringBuilder	append(double d) Append the given double to the buffer.
StringBuilder	append(float f) Append the given float to the buffer.
StringBuilder	append(int integerToAppend) Append the given integer to the buffer.
StringBuilder	append(long longToAppend) Append the given long to the buffer.
StringBuilder	append(Object obj) Append the String representation of the given Object to this buffer.
StringBuilder	append(String str) Append the given String to this buffer.
StringBuilder	append(StringBuffer sb) Append the content of the given StringBuilder to this buffer.
StringBuilder	appendCodePoint(int a) appendCodePoint
int	capacity() The current capacity of the internal buffer.
char	charAt(int index) Reads the character at teh given index.
int	codePointAt(int a) codePointAt
int	codePointBefore(int a) codePointBefore
int	codePointCount(int a, int b) codePointCount
StringBuilder	delete(int start, int end) delete removes characters from start to end-1
StringBuilder	deleteCharAt(int index) deleteCharAt delete the character at the specified position.
void	ensureCapacity(int minimumCapacity) Ensure that (minimumCapacity - length()) characters can be appended to this buffer without allocating additional buffer.
void	getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin) Copy character-data from the internal buffer into the given buffer.
int	indexOf(String str) Looks for the first occurrence of the given string.
int	indexOf(String str, int fromIndex) Looks for the first occurrence of the given string on or after the givent start index.
StringBuilder	insert(int offset, boolean b) insert the string "true" or "false" at a given position.
StringBuilder	insert(int offset, char c) insert a character at a given position.
StringBuilder	insert(int offset, char[] str) insert an array of characters at given position.
StringBuilder	insert(int index, char[] str, int offset, int len) insert inserts characters str[offset..offset+len-1] into this at position index.
StringBuilder	insert(int offset, CharSequence cs) Insert all characters in given CharSequence at position offset into this StringBuilder.
StringBuilder	insert(int index, CharSequence cs, int start, int end) insert inserts characters cs.charAt(start)..cs.charAt(end-1) into this at position index.
StringBuilder	insert(int offset, double d) insert a double converted to a string at given position.
StringBuilder	insert(int offset, float f) insert a float converted to a string at given position.
StringBuilder	insert(int offset, int i) insert an integer converted to a decimal number at given position.
StringBuilder	insert(int offset, long l) insert a long integer converted to a decimal number at given position.
StringBuilder	insert(int offset, Object obj) insert the string representation of an object at a given position.
StringBuilder	insert(int offset, String str) insert a string at a given position.
int	lastIndexOf(String str) Looks for the index of the last occurrence of the given string in the buffer.
int	lastIndexOf(String str, int fromIndex) Looks for the index of the last occurrence on or before the given index.
int	length() The amount of character data in this buffer.
int	offsetByCodePoints(int a, int b) offsetByCodePoints
StringBuilder	replace(int start, int end, String str) replace replace the characters from start..end-1 with str
StringBuilder	reverse() Reverse the order of the character-data in the internal buffer.
void	setCharAt(int index, char ch) Set the character at the given index.For the index the following must be true: 0 <= index < length()<=capacity()
void	setLength(int newLength) Set the length of the current data in the buffer.
CharSequence	subSequence(int start, int end) Get the CharSequence begining at the start index and going up to but not including the end index.
String	substring(int start) substring returns the suffix of this starting a given character position.
String	substring(int start, int end) Gets the substring starting at the start index upto but not including the end index.
String	toString() Get the content of this StringBuilder as String.
void	trimToSize() Reduce the storage required for the characters in this buffer.

Methods inherited from class java.lang.Object

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

Constructor Detail

StringBuilder

public StringBuilder()

Create a new StringBuilder with an initial capacity of 16 characters.

StringBuilder

public StringBuilder(int theCapacity)

Create a new StringBuilder with the given initial capacity.

Parameters:

theCapacity - initial capacity of the internal buffer.

Throws:

NegativeArraySizeException - if theCapacity < 0

StringBuilder

public StringBuilder(String str)

Create a new StringBuilder that contains the given String.

Parameters:

str - initial string.

Throws:

NullPointerException - if str is null

StringBuilder

public StringBuilder(CharSequence cs)

Create a new string buffer that contains the characters of the given CharSequence. The initialial capacity is 16 plus the length of the CharSequence.

Parameters:

cs - the character sequence

Throws:

NullPointerException - if cs is null.

Since:

1.5

Method Detail

subSequence

public CharSequence subSequence(int start,
                                int end)

Get the CharSequence begining at the start index and going up to but not including the end index.

Specified by:

subSequence in interface CharSequence

Parameters:

start - index of the first character to be included in the substring.

end - index of the first character after the substring.

Returns:

a CharSequence of length (end-start-1).

Throws:

StringIndexOutOfBoundsException - is start is negative, larger than length or larger than end.

Since:

1.2

length

public int length()

The amount of character data in this buffer. If toString() was called this would be the length of the returned String. This is different from the capacity of this buffer.

Specified by:

length in interface CharSequence

Returns:

number of characters in this buffer.

See Also:

capacity()

capacity

public int capacity()

The current capacity of the internal buffer. This is the amount of character data that this StringBuilder can hold without allocating more memory. This is different from the amount of actual data contained in the internal buffer.

Returns:

capacity of the internal buffer.

See Also:

capacity()

ensureCapacity

public void ensureCapacity(int minimumCapacity)

Ensure that (minimumCapacity - length()) characters can be appended to this buffer without allocating additional buffer. If the given minimumCapacity is lower that the current capacity no memory is allocated. The actual capacity after this method may be higher than minimumCapacity due to constraints in the memory layout.

Parameters:

minimumCapacity - that should be guaranteed.

setLength

public void setLength(int newLength)

Set the length of the current data in the buffer. If the length is larger than the current data-length the approriate number of null-characters \\u0000 are appendend. If the new lenght is smaler than the current length the data is truncated.

Parameters:

newLength - of data in the buffer.

Throws:

IndexOutOfBoundsException - if the new length is negative

charAt

public char charAt(int index)

Reads the character at teh given index.

Specified by:

charAt in interface CharSequence

Parameters:

index - of the character to read.

Returns:

the character at index

Throws:

IndexOutOfBoundsException - if index is negative or greater or equal than length.

getChars

public void getChars(int srcBegin,
                     int srcEnd,
                     char[] dst,
                     int dstBegin)

Copy character-data from the internal buffer into the given buffer.

Parameters:

srcBegin - start index in the internal buffer.

srcEnd - end index in the internal buffer (not included).

dst - destination buffer.

dstBegin - offset to start in the destination buffer.

Throws:

Nullpointerexception - if dst is null.

IndexOutOfBoundsException - if srcBegin<0, dstBegin<0, srcBegin>srcEnd, srcEnd>length or dstBeging+srcEnc-srcBegin>dst.length.

setCharAt

public void setCharAt(int index,
                      char ch)

Set the character at the given index.For the index the following must be true:

0 <= index < length()<=capacity()

Parameters:

index - which character to set.

ch - new value of the charater.

Throws:

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

append

public StringBuilder append(Object obj)

Append the String representation of the given Object to this buffer.

NOTE: this method must not be synchronized since the call to obj.toString performed by String.valueOf may cause a recursive call to append(Object), which may then be detected as a potential deadlock if the Analysis cannot proof that the two StringBuilder objects are different.

Parameters:

obj - the Object to append.

Returns:

reference to this StrignBuffer.

append

public StringBuilder append(StringBuffer sb)

Append the content of the given StringBuilder to this buffer.

Parameters:

sb - the StringBuilder to append.

Returns:

reference to this StringBuilder.

Since:

1.4

append

public StringBuilder append(String str)

Append the given String to this buffer.

Parameters:

str - the string to append.

Returns:

reference to this StringBuilder.

append

public StringBuilder append(char[] str)

Append character-data from the given char-array.

Parameters:

str - value containing the chars.

Returns:

reference to this StringBuilder.

append

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

Append character-data from the given char-array.

Parameters:

str - buffer containing the chars.

offset - start index in the buffer.

len - number of characters to append to this buffer.

Returns:

reference to this StringBuilder.

append

public StringBuilder append(boolean b)

Append a boolean.

Parameters:

b - the boolean to append.

Returns:

reference to this StringBuilder.

append

public StringBuilder append(char c)

Append a character to the buffer.

Specified by:

append in interface Appendable

Parameters:

c - the character to append.

Returns:

reference to this StringBuilder.

append

public StringBuilder append(CharSequence cs)

Append a character sequence to the buffer.

Specified by:

append in interface Appendable

Parameters:

cs - the character sequence.

Returns:

a reference to this instance.

Since:

1.5

append

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

Append a sub-sequence of a character sequence to the buffer.

Specified by:

append in interface Appendable

Parameters:

cs - the character sequence.

start - the index of the first character in cs to be appended

end - the position in cs after the last character to be appended.

Returns:

this.

Throws:

StringIndexOutOfBoundsException - if start<0, start>end or end>cs.length().

Since:

1.5

append

public StringBuilder append(int integerToAppend)

Append the given integer to the buffer.

Parameters:

integerToAppend - the integer to append.

Returns:

reference to this StringBuilder.

append

public StringBuilder append(long longToAppend)

Append the given long to the buffer.

Parameters:

longToAppend - the long to append to the buffer.

Returns:

reference to this StringBuilder.

append

public StringBuilder append(float f)

Append the given float to the buffer.

Parameters:

f - the float to append.

Returns:

reference to this StringBuilder.

append

public StringBuilder append(double d)

Append the given double to the buffer.

Parameters:

d - the double to append.

Returns:

reference to this StringBuilder.

delete

public StringBuilder delete(int start,
                            int end)

delete removes characters from start to end-1

Parameters:

start - the first character to delete

end - the character position after the last character to be deleted.

Returns:

this

Throws:

StringIndexOutOfBoundsException - is start is negative, larger than length or larger than end.

Since:

1.2

deleteCharAt

public StringBuilder deleteCharAt(int index)

deleteCharAt delete the character at the specified position.

Parameters:

index - the character position

Returns:

this

Throws:

StringIndexOutOfBoundsException - is index is negative, or larger or equal to length

Since:

1.2

replace

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

replace replace the characters from start..end-1 with str

Parameters:

start - the first character to be replaced

end - the character position after the last character to be replaced.

str - the string to be inserted instead of the replaced characters

Returns:

this.

Throws:

StringIndexOutOfBoundsException - is start is negative, larger than length or larger than end.

Since:

1.2

substring

public String substring(int start)

substring returns the suffix of this starting a given character position.

Parameters:

start - the start position.

Returns:

a new string that is the suffix of this starting at position start.

Throws:

StringIndexOutOfBoundsException - if start is negative or larger than length.

Since:

1.2

substring

public String substring(int start,
                        int end)

Gets the substring starting at the start index upto but not including the end index.

Parameters:

start - index of the first character to be included in the substring.

end - index of the first character after the substring.

Returns:

substring with length (end-start-1)

Throws:

StringIndexOutOfBoundsException - is start is negative, larger than length or larger than end.

Since:

1.2

insert

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

insert inserts characters str[offset..offset+len-1] into this at position index.

Parameters:

index - the index where to insert the characters.

str - the characters to be inserted

offset - the index of the first character in str to be inserted.

len - the number of characters to be inserted.

Returns:

this.

Throws:

StringIndexOutOfBoundsException - is index is negative, or index is larger or equal to length or offset is negative or len is negative or or offset+len is larger than str.length.

Since:

1.2

insert

public StringBuilder insert(int offset,
                            Object obj)

insert the string representation of an object at a given position.

Parameters:

offset - the position where the string should be inserted.

obj - the objects whose string representation should be inserted.

Returns:

this.

Throws:

StringIndexOutOfBoundsException - is offset is negative, or larger than length

insert

public StringBuilder insert(int offset,
                            String str)

insert a string at a given position.

Parameters:

offset - the position where the string should be inserted.

str - the string to be inserted.

Returns:

this.

Throws:

StringIndexOutOfBoundsException - is offset is negative, or larger than length

insert

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

insert an array of characters at given position.

Parameters:

offset - the postion where the characters should be inserted.

str - the characters.

Returns:

this.

Throws:

StringIndexOutOfBoundsException - is offset is negative, or larger than length

insert

public StringBuilder insert(int offset,
                            boolean b)

insert the string "true" or "false" at a given position.

Parameters:

offset - the position where the string should be inserted.

b - true for "true", false for "false.

Returns:

this.

insert

public StringBuilder insert(int offset,
                            char c)

insert a character at a given position.

Parameters:

offset - the position where the character should be inserted.

c - the character.

Returns:

this.

Throws:

StringIndexOutOfBoundsException - is offset is negative, or larger than length

insert

public StringBuilder insert(int offset,
                            int i)

insert an integer converted to a decimal number at given position.

Parameters:

offset - the position where the number should be inserted.

i - the number.

Returns:

this.

insert

public StringBuilder insert(int offset,
                            long l)

insert a long integer converted to a decimal number at given position.

Parameters:

offset - the position where the number should be inserted.

l - the number.

Returns:

this

insert

public StringBuilder insert(int offset,
                            float f)

insert a float converted to a string at given position.

Parameters:

offset - the position where the number should be inserted.

f - the number.

Returns:

this

insert

public StringBuilder insert(int offset,
                            double d)

insert a double converted to a string at given position.

Parameters:

offset - the position where the number should be inserted.

d - the number.

Returns:

this

insert

public StringBuilder insert(int offset,
                            CharSequence cs)

Insert all characters in given CharSequence at position offset into this StringBuilder.

Parameters:

offset - the position the characters should be inserted at.

cs - the character sequence, my be null for "null".

Returns:

reference to this StringBuilder.

Throws:

StringIndexOutOfBoundsException - is offset is negative, or larger than length

Since:

1.5

insert

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

insert inserts characters cs.charAt(start)..cs.charAt(end-1) into this at position index.

Parameters:

index - the index where to insert the characters.

cs - the characters to be inserted

start - the index of the first character in cs to be inserted.

end - the index after the last character to be inserted.

Returns:

this.

Throws:

StringIndexOutOfBoundsException - is index is negative, or index is larger or equal to length or offset is negative or len is negative or or offset+len is larger than str.length.

Since:

1.5

indexOf

public int indexOf(String str)

Looks for the first occurrence of the given string.

Parameters:

str - the string to look for.

Returns:

index of the forst occurrences or -1

Throws:

NullPointerException - if str is null

Since:

1.4

indexOf

public int indexOf(String str,
                   int fromIndex)

Looks for the first occurrence of the given string on or after the givent start index.

Parameters:

str - the string to look for.

fromIndex - the index where the search starts.

Returns:

index of the first occurrence on or after the fromIndex or -1

Throws:

NullPointerException - if str is null

Since:

1.4

lastIndexOf

public int lastIndexOf(String str)

Looks for the index of the last occurrence of the given string in the buffer.

Parameters:

str - the string to look for.

Returns:

index of the last occurrence of str or -1

Throws:

NullPointerException - if str is null

Since:

1.4

lastIndexOf

public int lastIndexOf(String str,
                       int fromIndex)

Looks for the index of the last occurrence on or before the given index.

Parameters:

str - the string to look for.

fromIndex - the index from which the search starts.

Returns:

index of the last occurrence on or before the fromIndex or -1

Throws:

NullPointerException - if str is null

Since:

1.4

reverse

public StringBuilder reverse()

Reverse the order of the character-data in the internal buffer.

Returns:

reference to this StringBuilder.

Since:

JDK1.0.2

toString

public String toString()

Get the content of this StringBuilder as String.

Specified by:

toString in interface CharSequence

Overrides:

toString in class Object

Returns:

the buffer contents as String.

trimToSize

public void trimToSize()

Reduce the storage required for the characters in this buffer. This may change the value of this buffer's capacity(), but it is not required to do so.

Since:

1.5

appendCodePoint

public StringBuilder appendCodePoint(int a)

appendCodePoint

Parameters:

a -

Returns:

a reference to this object.

codePointAt

public int codePointAt(int a)

codePointAt

Parameters:

a -

Returns:

the code point value of the character at the index

codePointBefore

public int codePointBefore(int a)

codePointBefore

Parameters:

a -

Returns:

the Unicode code point value before the given index.

codePointCount

public int codePointCount(int a,
                          int b)

codePointCount

Parameters:

a -

b -

Returns:

the number of Unicode code points in the specified text range

offsetByCodePoints

public int offsetByCodePoints(int a,
                              int b)

offsetByCodePoints

Parameters:

a -

b -

Returns:

the index within this sequence