oracle.adfnmc.java.lang
Class StringBuilder

java.lang.Object
  oracle.adfnmc.java.lang.StringBuilder

All Implemented Interfaces:

Serializable, CharSequence

public final class StringBuilder
extends java.lang.Object
implements CharSequence, Serializable

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

The majority of the modification methods on this class return StringBuilder, so that, like StringBuffers, they can be used in chaining method calls together. For example, new StringBuilder("One should ").append("always strive ").append("to achieve Harmony").

Since:

1.5

See Also:

java.lang.CharSequence, java.lang.Appendable, StringBuffer, String

Constructor Summary

StringBuilder()
Constructs an instance with an initial capacity of 16.

StringBuilder(CharSequence seq)
Constructs an instance that's populated by a CharSequence.

StringBuilder(int capacity)
Constructs an instance with a specified capacity.

StringBuilder(java.lang.String str)
Constructs an instance that's populated by a String.

Method Summary

StringBuilder	append(boolean b) Appends the String representation of the boolean value passed.
StringBuilder	append(char c) Appends the String representation of the char value passed.
StringBuilder	append(char[] ch) Appends the String representation of the char[] value passed.
StringBuilder	append(char[] str, int offset, int len) Appends the String representation of the subset of the char[] value passed.
StringBuilder	append(CharSequence csq) Appends the String representation of the CharSequence value passed.
StringBuilder	append(double d) Appends the String representation of the double value passed.
StringBuilder	append(float f) Appends the String representation of the float value passed.
StringBuilder	append(int i) Appends the String representation of the int value passed.
StringBuilder	append(long lng) Appends the String representation of the long value passed.
StringBuilder	append(java.lang.Object obj) Appends the String representation of the Object value passed.
StringBuilder	append(java.lang.String str) Appends the contents of the String.
StringBuilder	append(java.lang.StringBuffer sb) Appends the contents of the StringBuffer.
StringBuilder	append(java.lang.String csq, int start, int end) Appends the String representation of the subsequence of the CharSequence value passed.
int	capacity() Answers the number of characters this StringBuffer can hold without growing.
char	charAt(int index) Retrieves the character at the index.
StringBuilder	delete(int start, int end) Deletes a sequence of characters within this object, shifts any remaining characters to the left and adjusts the AbstractStringBuilder.length() of this object.
StringBuilder	deleteCharAt(int index) Deletes a single character within this object, shifts any remaining characters to the left and adjusts the AbstractStringBuilder.length() of this object.
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[] dest, int destStart) Copies the requested sequence of characters to be copied to the char[] passed.
int	indexOf(java.lang.String string) Searches in this StringBuffer for the first index of the specified character.
int	indexOf(java.lang.String subString, int start) Searches in this StringBuffer for the index of the specified character.
StringBuilder	insert(int offset, boolean b) Inserts the String representation of the boolean value passed into this object at the offset passed.
StringBuilder	insert(int offset, char c) Inserts the String representation of the char value passed into this object at the offset passed.
StringBuilder	insert(int offset, char[] ch) Inserts the String representation of the char[] value passed into this object at the offset passed.
StringBuilder	insert(int offset, char[] str, int strOffset, int strLen) Inserts the String representation of the subsequence of the char[] value passed into this object at the offset passed.
StringBuilder	insert(int offset, CharSequence s) Inserts the String representation of the CharSequence value passed into this object at the offset passed.
StringBuilder	insert(int offset, CharSequence s, int start, int end) Inserts the String representation of the subsequence of the CharSequence value passed into this object at the offset passed.
StringBuilder	insert(int offset, double d) Inserts the String representation of the double value passed into this object at the offset passed.
StringBuilder	insert(int offset, float f) Inserts the String representation of the float value passed into this object at the offset passed.
StringBuilder	insert(int offset, int i) Inserts the String representation of the int value passed into this object at the offset passed.
StringBuilder	insert(int offset, long l) Inserts the String representation of the long value passed into this object at the offset passed.
StringBuilder	insert(int offset, java.lang.Object obj) Inserts the String representation of the Object value passed into this object at the offset passed.
StringBuilder	insert(int offset, java.lang.String str) Inserts the String value passed into this object at the offset passed.
int	lastIndexOf(java.lang.String string) Searches in this StringBuffer for the last index of the specified character.
int	lastIndexOf(java.lang.String subString, int start) Searches in this StringBuffer for the index of the specified character.
int	length() The current length of this object.
StringBuilder	replace(int start, int end, java.lang.String str) Replaces the indicated subsequence of this object with the String passed.
StringBuilder	reverse() Reverses the contents of this object.
void	setCharAt(int index, char ch) Sets the character at the index in this object.
void	setLength(int length) Sets the current length to a new value.
CharSequence	subSequence(int start, int end) Returns a CharSequence of the subsequence of this object from the start index to the start index.
java.lang.String	substring(int start) Returns the String value of the subsequence of this object from the start index to the current end.
java.lang.String	substring(int start, int end) Returns the String value of the subsequence of this object from the start index to the start index.
java.lang.String	toString() Answers the contents of this StringBuilder.
void	trimToSize() Trims off any extra capacity beyond the current length.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface oracle.adfnmc.java.lang.CharSequence

charAt, length, subSequence

Constructor Detail

StringBuilder

public StringBuilder()

Constructs an instance with an initial capacity of 16.

See Also:

capacity()

StringBuilder

public StringBuilder(int capacity)

Constructs an instance with a specified capacity.

Parameters:

capacity - The initial capacity to use.

Throws:

java.lang.NegativeArraySizeException - if the capacity parameter is null.

See Also:

capacity()

StringBuilder

public StringBuilder(CharSequence seq)

Constructs an instance that's populated by a CharSequence. The capacity of the new builder will bee the length of the CharSequence plus 16.

Parameters:

seq - The CharSequence to copy into the builder.

Throws:

java.lang.NullPointerException - if the seq parameter is null.

StringBuilder

public StringBuilder(java.lang.String str)

Constructs an instance that's populated by a String. The capacity of the new builder will bee the length of the String plus 16.

Parameters:

str - The String to copy into the builder.

Throws:

java.lang.NullPointerException - if the str parameter is null.

Method Detail

append

public StringBuilder append(boolean b)

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

Parameters:

b - The boolean value to append to this object.

Returns:

A reference to this object.

See Also:

String.valueOf(boolean)

append

public StringBuilder append(char c)

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

Parameters:

c - The char value to append to this object.

Returns:

A reference to this object.

See Also:

String.valueOf(char)

append

public StringBuilder append(int i)

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

Parameters:

i - The int value to append to this object.

Returns:

A reference to this object.

See Also:

String.valueOf(int)

append

public StringBuilder append(long lng)

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

Parameters:

lng - The long value to append to this object.

Returns:

A reference to this object.

See Also:

String.valueOf(long)

append

public StringBuilder append(float f)

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

Parameters:

f - The float value to append to this object.

Returns:

A reference to this object.

See Also:

String.valueOf(float)

append

public StringBuilder append(double d)

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

Parameters:

d - The double value to append to this object.

Returns:

A reference to this object.

See Also:

String.valueOf(double)

append

public StringBuilder append(java.lang.Object obj)

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

Parameters:

obj - The Object value to append to this object.

Returns:

A reference to this object.

See Also:

String.valueOf(Object)

append

public StringBuilder append(java.lang.String str)

Appends the contents of the String. If the String passed is null, then the String "null" is appended.

Parameters:

str - The String to append to this object.

Returns:

A reference to this object.

append

public StringBuilder append(java.lang.StringBuffer sb)

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

Parameters:

sb - The StringBuffer to append to this object.

Returns:

A reference to this object.

append

public StringBuilder append(char[] ch)

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

Parameters:

ch - The char[] value to append to this object.

Returns:

A reference to this object.

See Also:

String.valueOf(char[])

append

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

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

Parameters:

str - The char[] value to append to this object.

offset - The inclusive offset index to begin copying from the str parameter.

len - The number of character to copy from the str parameter.

Returns:

A reference to this object.

See Also:

String.valueOf(char[],int,int)

append

public StringBuilder append(CharSequence csq)

Appends the String representation of the CharSequence value passed. If the CharSequence is null, then the String "null" is appended.

Parameters:

csq - The CharSequence value to append to this object.

Returns:

A reference to this object.

append

public StringBuilder append(java.lang.String csq,
                            int start,
                            int end)

Appends the String representation of the subsequence of the CharSequence value passed. If the CharSequence is null, then the String "null" is used to extract the subsequence from.

Parameters:

csq - The CharSequence value to append to this object.

start - The beginning index of the subsequence.

end - The ending index of the subsequence.

Returns:

A reference to this object.

delete

public StringBuilder delete(int start,
                            int end)

Deletes a sequence of characters within this object, shifts any remaining characters to the left and adjusts the AbstractStringBuilder.length() of this object.

Parameters:

start - The inclusive start index to begin deletion.

end - The exclusive end index to stop deletion.

Returns:

A reference to this object.

Throws:

java.lang.StringIndexOutOfBoundsException - if start is less than zero, greater than the current length or greater than end .

deleteCharAt

public StringBuilder deleteCharAt(int index)

Deletes a single character within this object, shifts any remaining characters to the left and adjusts the AbstractStringBuilder.length() of this object.

Parameters:

index - The index of the character to delete.

Returns:

A reference to this object.

Throws:

java.lang.StringIndexOutOfBoundsException - if index is less than zero or is greater than or equal to the current length.

insert

public StringBuilder insert(int offset,
                            boolean b)

Inserts the String representation of the boolean value passed into this object at the offset passed. The boolean value is converted to a String according to the rule defined by String.valueOf(boolean).

Parameters:

offset - The index of this object to insert the value.

b - The boolean value to insert into this object.

Returns:

A reference to this object.

Throws:

java.lang.StringIndexOutOfBoundsException - if offset is negative or greater than the current length().

See Also:

String.valueOf(boolean)

insert

public StringBuilder insert(int offset,
                            char c)

Inserts the String representation of the char value passed into this object at the offset passed. The char value is converted to a String according to the rule defined by String.valueOf(char).

Parameters:

offset - The index of this object to insert the value.

c - The char value to insert into this object.

Returns:

A reference to this object.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if offset is negative or greater than the current AbstractStringBuilder.length().

See Also:

String.valueOf(char)

insert

public StringBuilder insert(int offset,
                            int i)

Inserts the String representation of the int value passed into this object at the offset passed. The int value is converted to a String according to the rule defined by String.valueOf(int).

Parameters:

offset - The index of this object to insert the value.

i - The int value to insert into this object.

Returns:

A reference to this object.

Throws:

java.lang.StringIndexOutOfBoundsException - if offset is negative or greater than the current length().

See Also:

String.valueOf(int)

insert

public StringBuilder insert(int offset,
                            long l)

Inserts the String representation of the long value passed into this object at the offset passed. The long value is converted to a String according to the rule defined by String.valueOf(long).

Parameters:

offset - The index of this object to insert the value.

l - The long value to insert into this object.

Returns:

A reference to this object.

Throws:

java.lang.StringIndexOutOfBoundsException - if offset is negative or greater than the current AbstractStringBuilder.length().

See Also:

String.valueOf(long)

insert

public StringBuilder insert(int offset,
                            float f)

Inserts the String representation of the float value passed into this object at the offset passed. The float value is converted to a String according to the rule defined by String.valueOf(float).

Parameters:

offset - The index of this object to insert the value.

f - The float value to insert into this object.

Returns:

A reference to this object.

Throws:

java.lang.StringIndexOutOfBoundsException - if offset is negative or greater than the current AbstractStringBuilder.length().

See Also:

String.valueOf(float)

insert

public StringBuilder insert(int offset,
                            double d)

Inserts the String representation of the double value passed into this object at the offset passed. The double value is converted to a String according to the rule defined by String.valueOf(double).

Parameters:

offset - The index of this object to insert the value.

d - The double value to insert into this object.

Returns:

A reference to this object.

Throws:

java.lang.StringIndexOutOfBoundsException - if offset is negative or greater than the current AbstractStringBuilder.length().

See Also:

String.valueOf(double)

insert

public StringBuilder insert(int offset,
                            java.lang.Object obj)

Inserts the String representation of the Object value passed into this object at the offset passed. The Object value is converted to a String according to the rule defined by String.valueOf(Object).

Parameters:

offset - The index of this object to insert the value.

obj - The Object value to insert into this object.

Returns:

A reference to this object.

Throws:

java.lang.StringIndexOutOfBoundsException - if offset is negative or greater than the current AbstractStringBuilder.length().

See Also:

String.valueOf(Object)

insert

public StringBuilder insert(int offset,
                            java.lang.String str)

Inserts the String value passed into this object at the offset passed. If the String parameter is null, then the String "null" is inserted.

Parameters:

offset - The index of this object to insert the value.

str - The String to insert into this object.

Returns:

A reference to this object.

Throws:

java.lang.StringIndexOutOfBoundsException - if offset is negative or greater than the current AbstractStringBuilder.length().

insert

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

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

Parameters:

offset - The index of this object to insert the value.

ch - The char[] value to insert into this object.

Returns:

A reference to this object.

Throws:

java.lang.StringIndexOutOfBoundsException - if offset is negative or greater than the current AbstractStringBuilder.length().

See Also:

String.valueOf(char[])

insert

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

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

Parameters:

offset - The index of this object to insert the value.

str - The char[] value to insert into this object.

strOffset - The inclusive index of the str parameter to start copying from.

strLen - The number of characters to copy from the str parameter.

Returns:

A reference to this object.

Throws:

java.lang.StringIndexOutOfBoundsException - if offset is negative or greater than the current AbstractStringBuilder.length().

See Also:

String.valueOf(char[],int,int)

insert

public StringBuilder insert(int offset,
                            CharSequence s)

Inserts the String representation of the CharSequence value passed into this object at the offset passed. The CharSequence value is converted to a String as defined by CharSequence.toString(). If the CharSequence is null, then the String "null" is inserted.

Parameters:

offset - The index of this object to insert the value.

s - The CharSequence value to insert into this object.

Returns:

A reference to this object.

Throws:

java.lang.IndexOutOfBoundsException - if offset is negative or greater than the current AbstractStringBuilder.length().

See Also:

CharSequence.toString()

insert

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

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

Parameters:

offset - The index of this object to insert the value.

s - The CharSequence value to insert into this object.

start - The start of the subsequence of the s parameter.

end - The end of the subsequence of the s parameter.

Returns:

A reference to this object.

Throws:

java.lang.IndexOutOfBoundsException - if offset is negative or greater than the current AbstractStringBuilder.length().

See Also:

CharSequence.subSequence(int, int)

replace

public StringBuilder replace(int start,
                             int end,
                             java.lang.String str)

Replaces the indicated subsequence of this object with the String passed. If the String passed is longer or shorter than the subsequence, then this object will be adjusted appropriately.

Parameters:

start - The inclusive start index of the sequence to replace in this object.

end - The exclusive end index of the sequence to replace in this object.

str - The String to replace the subsequence.

Returns:

A reference to this object.

Throws:

java.lang.StringIndexOutOfBoundsException - if start is negative, greater than the current AbstractStringBuilder.length() or greater than end.

java.lang.NullPointerException - if the str parameter is null.

reverse

public StringBuilder reverse()

Reverses the contents of this object.

Returns:

A reference to this object.

toString

public java.lang.String toString()

Answers the contents of this StringBuilder.

Specified by:

toString in interface CharSequence

Returns:

a String containing the characters in this StringBuilder

capacity

public int capacity()

Answers the number of characters this StringBuffer can hold without growing.

Returns:

the capacity of this StringBuffer

See Also:

ensureCapacity(int), length()

charAt

public char charAt(int index)

Retrieves the character at the index.

Parameters:

index - The index of character in this object to retrieve.

Returns:

The char value.

Throws:

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

ensureCapacity

public 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 - The new minimum capacity to set.

getChars

public void getChars(int start,
                     int end,
                     char[] dest,
                     int destStart)

Copies the requested sequence of characters to be copied to the char[] passed.

Parameters:

start - The inclusive start index of the characters to copy from this object.

end - The exclusive end index of the characters to copy from this object.

dest - The char[] to copy the characters to.

destStart - The inclusive start index of the dest parameter to begin copying to.

Throws:

java.lang.IndexOutOfBoundsException - if the start is negative, the destStart is negative, the start is greater than end, the end is greater than the current length() or destStart + end - begin is greater than dest.length.

length

public int length()

The current length of this object.

Returns:

the number of characters in this StringBuffer

setCharAt

public void setCharAt(int index,
                      char ch)

Sets the character at the index in this object.

Parameters:

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

ch - the character to set.

Throws:

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

setLength

public 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 \u0000.

Parameters:

length - the new length of this StringBuffer

Throws:

java.lang.IndexOutOfBoundsException - when length < 0

See Also:

length()

substring

public java.lang.String substring(int start)

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

Parameters:

start - The inclusive start index to begin the subsequence.

Returns:

A String containing the subsequence.

Throws:

java.lang.StringIndexOutOfBoundsException - if start is negative or greater than the current length().

substring

public java.lang.String substring(int start,
                                  int end)

Returns the String value of the subsequence of this object from the start index to the start index.

Parameters:

start - The inclusive start index to begin the subsequence.

end - The exclusive end index to end the subsequence.

Returns:

A String containing the subsequence.

Throws:

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

subSequence

public CharSequence subSequence(int start,
                                int end)

Returns a CharSequence of the subsequence of this object from the start index to the start index.

Parameters:

start - The inclusive start index to begin the subsequence.

end - The exclusive end index to end the subsequence.

Returns:

A CharSequence containing the subsequence.

Throws:

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

Since:

1.4

indexOf

public int indexOf(java.lang.String string)

Searches in this StringBuffer for the first index of the specified character. The search for the character starts at the beginning and moves towards the end.

Parameters:

string - the string to find

Returns:

the index in this StringBuffer of the specified character, -1 if the character isn't found

Since:

1.4

See Also:

lastIndexOf(String)

indexOf

public int indexOf(java.lang.String subString,
                   int start)

Searches in this StringBuffer for the index of the specified character. The search for the character starts at the specified offset and moves towards the end.

Parameters:

subString - the string to find

start - the starting offset

Returns:

the index in this StringBuffer of the specified character, -1 if the character isn't found

Since:

1.4

See Also:

lastIndexOf(String,int)

lastIndexOf

public int lastIndexOf(java.lang.String string)

Searches in this StringBuffer for the last index of the specified character. The search for the character starts at the end and moves towards the beginning.

Parameters:

string - the string to find

Returns:

the index in this StringBuffer of the specified character, -1 if the character isn't found

Throws:

java.lang.NullPointerException - if the string parameter is null.

Since:

1.4

See Also:

String#lastIndexOf(java.lang.String)

lastIndexOf

public int lastIndexOf(java.lang.String subString,
                       int start)

Searches in this StringBuffer for the index of the specified character. The search for the character starts at the specified offset and moves towards the beginning.

Parameters:

subString - the string to find

start - the starting offset

Returns:

the index in this StringBuffer of the specified character, -1 if the character isn't found

Throws:

java.lang.NullPointerException - if the subString parameter is null.

Since:

1.4

See Also:

String#lastIndexOf(java.lang.String,int)

trimToSize

public void trimToSize()

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

Since:

1.5