Class CPStringBuilder

public CPStringBuilder()

Create a new CPStringBuilder with the default capacity.

public CPStringBuilder(int capacity)

Create an empty CPStringBuilder with the specified initial capacity.

Parameters:

capacity - the initial capacity

Throws:

NegativeArraySizeException - if capacity is negative

public CPStringBuilder(CharSequence seq)

Create a new CPStringBuilder with the characters in the specified CharSequence. Initial capacity will be the length of the sequence plus the default capacity; if the sequence reports a length less than or equal to 0, then the initial capacity will be the default.

Parameters:

seq - the initializing CharSequence

Throws:

NullPointerException - if str is null

Since:

1.5

public CPStringBuilder(String str)

Create a new CPStringBuilder with the characters in the specified String. Initial capacity will be the size of the String plus the default capacity.

Parameters:

str - the String to convert

Throws:

NullPointerException - if str is null

public CPStringBuilder(StringBuffer str)

Create a new CPStringBuilder with the characters in the specified StringBuffer. Initial capacity will be the size of the String plus the default capacity.

Parameters:

str - the String to convert

Throws:

NullPointerException - if str is null

public CPStringBuilder(StringBuilder str)

Create a new CPStringBuilder with the characters in the specified StringBuilder. Initial capacity will be the size of the String plus the default capacity.

Parameters:

str - the String to convert

Throws:

NullPointerException - if str is null

public CPStringBuilder append(boolean bool)

Append the String value of the argument to this StringBuffer. Uses String.valueOf() to convert to String.

Parameters:

bool - the boolean to convert and append

Returns:

this StringBuffer

See Also:

String.valueOf(boolean)

public CPStringBuilder append(char ch)

Append the char to this StringBuffer.

Specified by:

append in interface Appendable

Parameters:

ch - the char to append

Returns:

this StringBuffer

public CPStringBuilder append(char[] data)

Append the char array to this StringBuffer. This is similar (but more efficient) than append(new String(data)), except in the case of null.

Parameters:

data - the char[] to append

Returns:

this StringBuffer

Throws:

NullPointerException - if str is null

See Also:

append(char[],int,int)

public CPStringBuilder append(char[] data,
                              int offset,
                              int count)

Append part of the char array to this StringBuffer. This is similar (but more efficient) than append(new String(data, offset, count)), except in the case of null.

Parameters:

data - the char[] to append

offset - the start location in str

count - the number of characters to get from str

Returns:

this StringBuffer

Throws:

NullPointerException - if str is null

IndexOutOfBoundsException - if offset or count is out of range (while unspecified, this is a StringIndexOutOfBoundsException)

public CPStringBuilder append(double dnum)

Append the String value of the argument to this StringBuffer. Uses String.valueOf() to convert to String.

Parameters:

dnum - the double to convert and append

Returns:

this StringBuffer

See Also:

String.valueOf(double)

public CPStringBuilder append(float fnum)

Append the String value of the argument to this StringBuffer. Uses String.valueOf() to convert to String.

Parameters:

fnum - the float to convert and append

Returns:

this StringBuffer

See Also:

String.valueOf(float)

public CPStringBuilder append(int inum)

Append the String value of the argument to this StringBuffer. Uses String.valueOf() to convert to String.

Parameters:

inum - the int to convert and append

Returns:

this StringBuffer

See Also:

String.valueOf(int)

public CPStringBuilder append(CharSequence seq)

Append the characters in the CharSequence to this buffer.

Specified by:

append in interface Appendable

Parameters:

seq - the CharSequence providing the characters

Returns:

this StringBuffer

Since:

1.5

public CPStringBuilder 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

Parameters:

seq - the CharSequence providing the characters

start - the starting index

end - one past the final index

Returns:

this StringBuffer

Since:

1.5

public CPStringBuilder append(Object obj)

Append the String value of the argument to this StringBuffer. Uses String.valueOf() to convert to String.

Parameters:

obj - the Object to convert and append

Returns:

this StringBuffer

See Also:

String.valueOf(Object), append(String)

public CPStringBuilder append(String str)

Append the String to this StringBuffer. If str is null, the String "null" is appended.

Parameters:

str - the String to append

Returns:

this StringBuffer

public CPStringBuilder 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.

Parameters:

stringBuffer - the StringBuilder to convert and append

Returns:

this StringBuilder

See Also:

append(Object)

public CPStringBuilder append(long lnum)

Append the String value of the argument to this StringBuffer. Uses String.valueOf() to convert to String.

Parameters:

lnum - the long to convert and append

Returns:

this StringBuffer

See Also:

String.valueOf(long)

public CPStringBuilder appendCodePoint(int code)

Append the code point to this StringBuffer. This is like #append(char), but will append two characters if a supplementary code point is given.

Parameters:

code - the code point to append

Returns:

this StringBuffer

Since:

1.5

See Also:

Character.toChars(int,char[],int)

public char charAt(int index)

Get the character at the specified index.

Specified by:

charAt in interface CharSequence

Parameters:

index - the index of the character to get, starting at 0

Returns:

the character at the specified index

Throws:

IndexOutOfBoundsException - if index is negative or >= length() (while unspecified, this is a StringIndexOutOfBoundsException)

public int codePointAt(int index)

Get the code point at the specified index. This is like #charAt(int), but if the character is the start of a surrogate pair, and the following character completes the pair, then the corresponding supplementary code point is returned.

Parameters:

index - the index of the codepoint to get, starting at 0

Returns:

the codepoint at the specified index

Throws:

IndexOutOfBoundsException - if index is negative or >= length()

Since:

1.5

public int codePointBefore(int index)

Get the code point before the specified index. This is like #codePointAt(int), but checks the characters at index-1 and index-2 to see if they form a supplementary code point.

Parameters:

index - the index just past the codepoint to get, starting at 0

Returns:

the codepoint at the specified index

Throws:

IndexOutOfBoundsException - if index is negative or >= length()

Since:

1.5

public int codePointCount(int start,
                          int end)

Return the number of code points between two indices in the StringBuffer. An unpaired surrogate counts as a code point for this purpose. Characters outside the indicated range are not examined, even if the range ends in the middle of a surrogate pair.

Parameters:

start - the starting index

end - one past the ending index

Returns:

the number of code points

Since:

1.5

public CPStringBuilder delete(int start,
                              int end)

Delete characters from this StringBuffer. delete(10, 12) will delete 10 and 11, but not 12. It is harmless for end to be larger than length().

Parameters:

start - the first character to delete

end - the index after the last character to delete

Returns:

this StringBuffer

Throws:

StringIndexOutOfBoundsException - if start or end are out of bounds

Since:

1.2

public CPStringBuilder deleteCharAt(int index)

Delete a character from this StringBuffer.

Parameters:

index - the index of the character to delete

Returns:

this StringBuffer

Throws:

StringIndexOutOfBoundsException - if index is out of bounds

Since:

1.2

public void ensureCapacity(int minimumCapacity)

Increase the capacity of this StringBuilder. This will ensure that an expensive growing operation will not occur until either minimumCapacity is reached or the array has been allocated. The buffer is grown to either minimumCapacity * 2, if the array has been allocated or the larger of minimumCapacity and capacity() * 2 + 2, if it is not already large enough.

Parameters:

minimumCapacity - the new capacity

See Also:

length()

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.

Parameters:

srcOffset - the index to start copying from (inclusive)

srcEnd - the index to stop copying from (exclusive)

dst - the array to copy into

dstOffset - the index to start copying into

Throws:

NullPointerException - if dst is null

IndexOutOfBoundsException - if any source or target indices are out of range (while unspecified, source problems cause a StringIndexOutOfBoundsException, and dest problems cause an ArrayIndexOutOfBoundsException)

See Also:

System.arraycopy(Object,int,Object,int,int)

public int indexOf(String str)

Finds the first instance of a substring in this StringBuilder.

Parameters:

str - String to find

Returns:

location (base 0) of the String, or -1 if not found

Throws:

NullPointerException - if str is null

See Also:

indexOf(String,int)

public int indexOf(String str,
                   int fromIndex)

Finds the first instance of a String in this StringBuffer, 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.

Parameters:

str - String to find

fromIndex - index to start the search

Returns:

location (base 0) of the String, or -1 if not found

Throws:

NullPointerException - if str is null

Since:

1.4

public CPStringBuilder insert(int offset,
                              boolean bool)

Insert the String value of the argument into this StringBuffer. Uses String.valueOf() to convert to String.

Parameters:

offset - the place to insert in this buffer

bool - the boolean to convert and insert

Returns:

this StringBuffer

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

See Also:

String.valueOf(boolean)

public CPStringBuilder insert(int offset,
                              char ch)

Insert the char argument into this StringBuffer.

Parameters:

offset - the place to insert in this buffer

ch - the char to insert

Returns:

this StringBuffer

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

public CPStringBuilder insert(int offset,
                              char[] data)

Insert the char[] argument into this StringBuffer.

Parameters:

offset - the place to insert in this buffer

data - the char[] to insert

Returns:

this StringBuffer

Throws:

NullPointerException - if data is null

StringIndexOutOfBoundsException - if offset is out of bounds

See Also:

insert(int,char[],int,int)

public CPStringBuilder insert(int offset,
                              char[] str,
                              int str_offset,
                              int len)

Insert a subarray of the char[] argument into this StringBuffer.

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 StringBuffer

Throws:

NullPointerException - if str is null

StringIndexOutOfBoundsException - if any index is out of bounds

Since:

1.2

public CPStringBuilder insert(int offset,
                              double dnum)

Insert the String value of the argument into this StringBuffer. Uses String.valueOf() to convert to String.

Parameters:

offset - the place to insert in this buffer

dnum - the double to convert and insert

Returns:

this StringBuffer

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

See Also:

String.valueOf(double)

public CPStringBuilder insert(int offset,
                              float fnum)

Insert the String value of the argument into this StringBuffer. Uses String.valueOf() to convert to String.

Parameters:

offset - the place to insert in this buffer

fnum - the float to convert and insert

Returns:

this StringBuffer

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

See Also:

String.valueOf(float)

public CPStringBuilder insert(int offset,
                              int inum)

Insert the String value of the argument into this StringBuffer. Uses String.valueOf() to convert to String.

Parameters:

offset - the place to insert in this buffer

inum - the int to convert and insert

Returns:

this StringBuffer

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

See Also:

String.valueOf(int)

public CPStringBuilder insert(int offset,
                              CharSequence sequence)

Insert the CharSequence argument into this StringBuffer. If the sequence is null, the String "null" is used instead.

Parameters:

offset - the place to insert in this buffer

sequence - the CharSequence to insert

Returns:

this StringBuffer

Throws:

IndexOutOfBoundsException - if offset is out of bounds

Since:

1.5

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

Insert a subsequence of the CharSequence argument into this StringBuffer. If the sequence is null, the String "null" is used instead.

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 StringBuffer

Throws:

IndexOutOfBoundsException - if offset, start, or end are out of bounds

Since:

1.5

public CPStringBuilder insert(int offset,
                              Object obj)

Insert the String value of the argument into this StringBuffer. Uses String.valueOf() to convert to String.

Parameters:

offset - the place to insert in this buffer

obj - the Object to convert and insert

Returns:

this StringBuffer

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

See Also:

String.valueOf(Object)

public CPStringBuilder insert(int offset,
                              String str)

Insert the String argument into this StringBuffer. If str is null, the String "null" is used instead.

Parameters:

offset - the place to insert in this buffer

str - the String to insert

Returns:

this StringBuffer

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

public CPStringBuilder insert(int offset,
                              long lnum)

Insert the String value of the argument into this StringBuffer. Uses String.valueOf() to convert to String.

Parameters:

offset - the place to insert in this buffer

lnum - the long to convert and insert

Returns:

this StringBuffer

Throws:

StringIndexOutOfBoundsException - if offset is out of bounds

See Also:

String.valueOf(long)

public int lastIndexOf(String str)

Finds the last instance of a substring in this StringBuffer.

Parameters:

str - String to find

Returns:

location (base 0) of the String, or -1 if not found

Throws:

NullPointerException - if str is null

Since:

1.4

See Also:

lastIndexOf(String,int)

public int lastIndexOf(String str,
                       int fromIndex)

Finds the last instance of a String in this StringBuffer, 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.

Parameters:

str - String to find

fromIndex - index to start the search

Returns:

location (base 0) of the String, or -1 if not found

Throws:

NullPointerException - if str is null

Since:

1.4

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)

public int offsetByCodePoints(int start,
                              int codePoints)

Starting at the given index, this counts forward by the indicated number of code points, and then returns the resulting index. An unpaired surrogate counts as a single code point for this purpose.

Parameters:

start - the starting index

codePoints - the number of code points

Returns:

the resulting index

Since:

1.5

public CPStringBuilder 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 StringBuffer, all characters after start are replaced.

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 StringBuffer

Throws:

StringIndexOutOfBoundsException - if start or end are out of bounds

NullPointerException - if str is null

Since:

1.2

public CPStringBuilder reverse()

Reverse the characters in this StringBuffer. The same sequence of characters exists, but in the reverse index ordering.

Returns:

this StringBuffer

public void setCharAt(int index,
                      char ch)

Set the character at the specified index.

Parameters:

index - the index of the character to set starting at 0

ch - the value to set that character to

Throws:

IndexOutOfBoundsException - if index is negative or >= length() (while unspecified, this is a StringIndexOutOfBoundsException)

public void setLength(int newLength)

Set the length of this StringBuffer. 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.

Parameters:

newLength - the new length

Throws:

IndexOutOfBoundsException - if the new length is negative (while unspecified, this is a StringIndexOutOfBoundsException)

See Also:

length()

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)

public String substring(int beginIndex)

Creates a substring of this CPStringBuilder, 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)

public String substring(int beginIndex,
                        int endIndex)

Creates a substring of this CPStringBuilder, 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

public String toString()

Convert this CPStringBuilder to a String. The String is composed of the characters currently in this StringBuilder. Note that the result is not a copy, so we flag this here and make sure to allocate a new array on the next write attempt (see ensureCapacity(int)).

Specified by:

toString in interface CharSequence

Overrides:

toString in interface Object

Returns:

the characters in this StringBuilder

public void trimToSize()

This may reduce the amount of memory used by the StringBuffer, by resizing the internal array to remove unused space. However, this method is not required to resize, so this behavior cannot be relied upon.

Since:

1.5