# Class CStringBuilder

java.lang.Object
com.codename1.util.CStringBuilder

public final class CStringBuilder extends Object

This is generally the Apache String builder class refactored here so we can use it regardless of vm limitations/differences for increased performance. 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 `StringBuffer`s, they can be used in chaining method calls together. For example, `new StringBuilder("One should ").append("always strive ").append("to achieve Harmony")`.

##### Deprecated

we will be moving to the proper string builder very soon

##### See also

- CharSequence

- Appendable

- StringBuffer

- String

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CStringBuilder()`
  Constructs an instance with an initial capacity of `16`.
  `CStringBuilder(int capacity)`
  Constructs an instance with the specified capacity.
  `CStringBuilder(String str)`
  Constructs an instance that's initialized with the contents of the specified `String`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `CStringBuilder`
  `append(boolean b)`
  Appends the string representation of the specified `boolean` value.
  `CStringBuilder`
  `append(char c)`
  Appends the string representation of the specified `char` value.
  `CStringBuilder`
  `append(char[] ch)`
  Appends the string representation of the specified `char[]`.
  `CStringBuilder`
  `append(char[] str, int offset, int len)`
  Appends the string representation of the specified subset of the `char[]`.
  `CStringBuilder`
  `append(double d)`
  Appends the string representation of the specified `double` value.
  `CStringBuilder`
  `append(float f)`
  Appends the string representation of the specified `float` value.
  `CStringBuilder`
  `append(int i)`
  Appends the string representation of the specified `int` value.
  `CStringBuilder`
  `append(long lng)`
  Appends the string representation of the specified `long` value.
  `CStringBuilder`
  `append(Object obj)`
  Appends the string representation of the specified `Object`.
  `CStringBuilder`
  `append(String str)`
  Appends the contents of the specified string.
  `CStringBuilder`
  `appendCodePoint(int codePoint)`
  Appends the encoded Unicode code point.
  `int`
  `capacity()`
  Returns the number of characters that can be held without growing.
  `char`
  `charAt(int index)`
  Retrieves the character at the `index`.
  `int`
  `codePointAt(int index)`
  Retrieves the Unicode code point value at the `index`.
  `int`
  `codePointBefore(int index)`
  Retrieves the Unicode code point value that precedes the `index`.
  `int`
  `codePointCount(int beginIndex, int endIndex)`
  Calculates the number of Unicode code points between `beginIndex` and `endIndex`.
  `CStringBuilder`
  `delete(int start, int end)`
  Deletes a sequence of characters specified by `start` and `end`.
  `CStringBuilder`
  `deleteCharAt(int index)`
  Deletes the character at the specified index.
  `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 the `char[]` passed starting at `destStart`.
  `int`
  `indexOf(String string)`
  Searches for the first index of the specified character.
  `int`
  `indexOf(String subString, int start)`
  Searches for the index of the specified character.
  `CStringBuilder`
  `insert(int offset, boolean b)`
  Inserts the string representation of the specified `boolean` value at the specified `offset`.
  `CStringBuilder`
  `insert(int offset, char c)`
  Inserts the string representation of the specified `char` value at the specified `offset`.
  `CStringBuilder`
  `insert(int offset, char[] ch)`
  Inserts the string representation of the specified `char[]` at the specified `offset`.
  `CStringBuilder`
  `insert(int offset, char[] str, int strOffset, int strLen)`
  Inserts the string representation of the specified subsequence of the `char[]` at the specified `offset`.
  `CStringBuilder`
  `insert(int offset, double d)`
  Inserts the string representation of the specified `double` value at the specified `offset`.
  `CStringBuilder`
  `insert(int offset, float f)`
  Inserts the string representation of the specified `float` value at the specified `offset`.
  `CStringBuilder`
  `insert(int offset, int i)`
  Inserts the string representation of the specified `int` value at the specified `offset`.
  `CStringBuilder`
  `insert(int offset, long l)`
  Inserts the string representation of the specified `long` value at the specified `offset`.
  `CStringBuilder`
  `insert(int offset, Object obj)`
  Inserts the string representation of the specified `Object` at the specified `offset`.
  `CStringBuilder`
  `insert(int offset, String str)`
  Inserts the specified string at the specified `offset`.
  `int`
  `lastIndexOf(String string)`
  Searches for the last index of the specified character.
  `int`
  `lastIndexOf(String subString, int start)`
  Searches for the index of the specified character.
  `int`
  `length()`
  The current length.
  `int`
  `offsetByCodePoints(int index, int codePointOffset)`
  Returns the index that is offset `codePointOffset` code points from `index`.
  `CStringBuilder`
  `replace(int start, int end, String str)`
  Replaces the specified subsequence in this builder with the specified string.
  `CStringBuilder`
  `reverse()`
  Reverses the order of characters in this builder.
  `void`
  `setCharAt(int index, char ch)`
  Sets the character at the `index`.
  `void`
  `setLength(int length)`
  Sets the current length to a new value.
  `String`
  `substring(int start)`
  Returns the String value of the subsequence from the `start` index to the current end.
  `String`
  `substring(int start, int end)`
  Returns the String value of the subsequence from the `start` index to the `end` index.
  `String`
  `toString()`
  Returns the contents of this builder.
  `void`
  `trimToSize()`
  Trims off any extra capacity beyond the current length.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### CStringBuilder

    public CStringBuilder()

    Constructs an instance with an initial capacity of `16`.

    ###### See also

    - #capacity()

  - ### CStringBuilder

    public CStringBuilder(int capacity)

    Constructs an instance with the specified capacity.

    ###### Parameters

    - `capacity`: the initial capacity to use.

    ###### Throws

    - `NegativeArraySizeException`: if the specified `capacity` is negative.

    ###### See also

    - #capacity()

  - ### CStringBuilder

    public CStringBuilder(String str)

    Constructs an instance that's initialized with the contents of the specified `String`. The capacity of the new builder will be the length of the `String` plus 16.

    ###### Parameters

    - `str`: the `String` to copy into the builder.

    ###### Throws

    - `NullPointerException`: if `str` is `null`.

- ## Method Details

  - ### append

    public CStringBuilder append(boolean b)

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

    ###### Parameters

    - `b`: the `boolean` value to append.

    ###### Returns

    this builder.

    ###### See also

    - String#valueOf(boolean)

  - ### append

    public CStringBuilder append(char c)

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

    ###### Parameters

    - `c`: the `char` value to append.

    ###### Returns

    this builder.

    ###### See also

    - String#valueOf(char)

  - ### append

    public CStringBuilder append(int i)

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

    ###### Parameters

    - `i`: the `int` value to append.

    ###### Returns

    this builder.

    ###### See also

    - String#valueOf(int)

  - ### append

    public CStringBuilder append(long lng)

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

    ###### Parameters

    - `lng`: the `long` value.

    ###### Returns

    this builder.

    ###### See also

    - String#valueOf(long)

  - ### append

    public CStringBuilder append(float f)

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

    ###### Parameters

    - `f`: the `float` value to append.

    ###### Returns

    this builder.

    ###### See also

    - String#valueOf(float)

  - ### append

    public CStringBuilder append(double d)

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

    ###### Parameters

    - `d`: the `double` value to append.

    ###### Returns

    this builder.

    ###### See also

    - String#valueOf(double)

  - ### append

    public CStringBuilder append(Object obj)

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

    ###### Parameters

    - `obj`: the `Object` to append.

    ###### Returns

    this builder.

    ###### See also

    - String#valueOf(Object)

  - ### append

    public CStringBuilder append(String str)

    Appends the contents of the specified string. If the string is `null`, then the string `"null"` is appended.

    ###### Parameters

    - `str`: the string to append.

    ###### Returns

    this builder.

  - ### append

    public CStringBuilder append(char[] ch)

    Appends the string representation of the specified `char[]`. The `char[]` is converted to a string according to the rule defined by `String#valueOf(char[])`.

    ###### Parameters

    - `ch`: the `char[]` to append..

    ###### Returns

    this builder.

    ###### See also

    - String#valueOf(char[])

  - ### append

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

    Appends the string representation of the specified subset of the `char[]`. The `char[]` value is converted to a String according to the rule defined by `int, int)`.

    ###### Parameters

    - `str`: the `char[]` to append.

    - `offset`: the inclusive offset index.

    - `len`: the number of characters.

    ###### Returns

    this builder.

    ###### Throws

    - `ArrayIndexOutOfBoundsException`: @throws ArrayIndexOutOfBoundsException if `offset` and `len` do not specify a valid subsequence.

    ###### See also

    - String#valueOf(char[], int, int)

  - ### appendCodePoint

    public CStringBuilder appendCodePoint(int codePoint)

    Appends the encoded Unicode code point. The code point is converted to a `char[]` as defined by `Character#toChars(int)`.

    ###### Parameters

    - `codePoint`: the Unicode code point to encode and append.

    ###### Returns

    this builder.

    ###### See also

    - Character#toChars(int)

  - ### delete

    public CStringBuilder delete(int start, int end)

    Deletes a sequence of characters specified by `start` and `end`. Shifts any remaining characters to the left.

    ###### Parameters

    - `start`: the inclusive start index.

    - `end`: the exclusive end index.

    ###### Returns

    this builder.

    ###### Throws

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `start` is less than zero, greater than the current length or greater than `end`.

  - ### deleteCharAt

    public CStringBuilder deleteCharAt(int index)

    Deletes the character at the specified index. shifts any remaining characters to the left.

    ###### Parameters

    - `index`: the index of the character to delete.

    ###### Returns

    this builder.

    ###### Throws

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `index` is less than zero or is greater than or equal to the current length.

  - ### insert

    public CStringBuilder insert(int offset, boolean b)

    Inserts the string representation of the specified `boolean` value at the specified `offset`. The `boolean` value is converted to a string according to the rule defined by `String#valueOf(boolean)`.

    ###### Parameters

    - `offset`: the index to insert at.

    - `b`: the `boolean` value to insert.

    ###### Returns

    this builder.

    ###### Throws

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `offset` is negative or greater than the current `length`.

    ###### See also

    - String#valueOf(boolean)

  - ### insert

    public CStringBuilder insert(int offset, char c)

    Inserts the string representation of the specified `char` value at the specified `offset`. The `char` value is converted to a string according to the rule defined by `String#valueOf(char)`.

    ###### Parameters

    - `offset`: the index to insert at.

    - `c`: the `char` value to insert.

    ###### Returns

    this builder.

    ###### Throws

    - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `offset` is negative or greater than the current `length()`.

    ###### See also

    - String#valueOf(char)

  - ### insert

    public CStringBuilder insert(int offset, int i)

    Inserts the string representation of the specified `int` value at the specified `offset`. The `int` value is converted to a String according to the rule defined by `String#valueOf(int)`.

    ###### Parameters

    - `offset`: the index to insert at.

    - `i`: the `int` value to insert.

    ###### Returns

    this builder.

    ###### Throws

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `offset` is negative or greater than the current `length()`.

    ###### See also

    - String#valueOf(int)

  - ### insert

    public CStringBuilder insert(int offset, long l)

    Inserts the string representation of the specified `long` value at the specified `offset`. The `long` value is converted to a String according to the rule defined by `String#valueOf(long)`.

    ###### Parameters

    - `offset`: the index to insert at.

    - `l`: the `long` value to insert.

    ###### Returns

    this builder.

    ###### Throws

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `offset` is negative or greater than the current {code length()}.

    ###### See also

    - String#valueOf(long)

  - ### insert

    public CStringBuilder insert(int offset, float f)

    Inserts the string representation of the specified `float` value at the specified `offset`. The `float` value is converted to a string according to the rule defined by `String#valueOf(float)`.

    ###### Parameters

    - `offset`: the index to insert at.

    - `f`: the `float` value to insert.

    ###### Returns

    this builder.

    ###### Throws

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `offset` is negative or greater than the current `length()`.

    ###### See also

    - String#valueOf(float)

  - ### insert

    public CStringBuilder insert(int offset, double d)

    Inserts the string representation of the specified `double` value at the specified `offset`. The `double` value is converted to a String according to the rule defined by `String#valueOf(double)`.

    ###### Parameters

    - `offset`: the index to insert at.

    - `d`: the `double` value to insert.

    ###### Returns

    this builder.

    ###### Throws

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `offset` is negative or greater than the current `length()`.

    ###### See also

    - String#valueOf(double)

  - ### insert

    public CStringBuilder insert(int offset, Object obj)

    Inserts the string representation of the specified `Object` at the specified `offset`. The `Object` value is converted to a String according to the rule defined by `String#valueOf(Object)`.

    ###### Parameters

    - `offset`: the index to insert at.

    - `obj`: the `Object` to insert.

    ###### Returns

    this builder.

    ###### Throws

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `offset` is negative or greater than the current `length()`.

    ###### See also

    - String#valueOf(Object)

  - ### insert

    public CStringBuilder insert(int offset, String str)

    Inserts the specified string at the specified `offset`. If the specified string is null, then the String `"null"` is inserted.

    ###### Parameters

    - `offset`: the index to insert at.

    - `str`: the `String` to insert.

    ###### Returns

    this builder.

    ###### Throws

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `offset` is negative or greater than the current `length()`.

  - ### insert

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

    Inserts the string representation of the specified `char[]` at the specified `offset`. The `char[]` value is converted to a String according to the rule defined by `String#valueOf(char[])`.

    ###### Parameters

    - `offset`: the index to insert at.

    - `ch`: the `char[]` to insert.

    ###### Returns

    this builder.

    ###### Throws

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `offset` is negative or greater than the current `length()`.

    ###### See also

    - String#valueOf(char[])

  - ### insert

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

    Inserts the string representation of the specified subsequence of the `char[]` at the specified `offset`. The `char[]` value is converted to a String according to the rule defined by `int, int)`.

    ###### Parameters

    - `offset`: the index to insert at.

    - `str`: the `char[]` to insert.

    - `strOffset`: the inclusive index.

    - `strLen`: the number of characters.

    ###### Returns

    this builder.

    ###### Throws

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `offset` is negative or greater than the current `length()`, or `strOffset` and `strLen` do not specify a valid subsequence.

    ###### See also

    - String#valueOf(char[], int, int)

  - ### replace

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

    Replaces the specified subsequence in this builder with the specified string.

    ###### Parameters

    - `start`: the inclusive begin index.

    - `end`: the exclusive end index.

    - `str`: the replacement string.

    ###### Returns

    this builder.

    ###### Throws

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `start` is negative, greater than the current `length()` or greater than `end`.

    - `NullPointerException`: if `str` is `null`.

  - ### reverse

    public CStringBuilder reverse()

    Reverses the order of characters in this builder.

    ###### Returns

    this buffer.

  - ### toString

    public String toString()

    Returns the contents of this builder.

    ###### Returns

    the string representation of the data in this builder.

  - ### capacity

    public int capacity()

    Returns the number of characters that can be held without growing.

    ###### Returns

    the capacity

    ###### See also

    - #ensureCapacity

    - #length

  - ### charAt

    public char charAt(int index)

    Retrieves the character at the `index`.

    ###### Parameters

    - `index`: the index of the character to retrieve.

    ###### Returns

    the char value.

    ###### Throws

    - `IndexOutOfBoundsException`: @throws 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 the `char[]` passed starting at `destStart`.

    ###### Parameters

    - `start`: the inclusive start index of the characters to copy.

    - `end`: the exclusive end index of the characters to copy.

    - `dest`: the `char[]` to copy the characters to.

    - `destStart`: the inclusive start index of `dest` to begin copying to.

    ###### Throws

    - `IndexOutOfBoundsException`: @throws 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.

    ###### Returns

    the number of characters contained in this instance.

  - ### setCharAt

    public void setCharAt(int index, char ch)

    Sets the character at the `index`.

    ###### Parameters

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

    - `ch`: the character to set.

    ###### Throws

    - `IndexOutOfBoundsException`: @throws 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 `�`.

    ###### Parameters

    - `length`: the new length of this StringBuffer.

    ###### Throws

    - `IndexOutOfBoundsException`: if `length < 0`.

    ###### See also

    - #length

  - ### substring

    public String substring(int start)

    Returns the String value of the subsequence 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

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `start` is negative or greater than the current `#length()`.

  - ### substring

    public String substring(int start, int end)

    Returns the String value of the subsequence from the `start` index to the `end` 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

    - `StringIndexOutOfBoundsException`: @throws StringIndexOutOfBoundsException if `start` is negative, greater than `end` or if `end` is greater than the current `#length()`.

  - ### indexOf

    public int indexOf(String string)

    Searches 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

    Returns:

      the index of the specified character, -1 if the character isn't found.

      ###### See also

      - #lastIndexOf(String)

  - ### indexOf

    public int indexOf(String subString, int start)

    Searches 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

    Returns:

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

      ###### See also

      - #lastIndexOf(String, int)

  - ### lastIndexOf

    public int lastIndexOf(String string)

    Searches 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

    Returns:

      the index of the specified character, -1 if the character isn't found.

      ###### Throws

      - `NullPointerException`: if `string` is `null`.

      ###### See also

      - String#lastIndexOf(java.lang.String)

  - ### lastIndexOf

    public int lastIndexOf(String subString, int start)

    Searches 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

    Returns:

      the index of the specified character, -1 if the character isn't found.

      ###### Throws

      - `NullPointerException`: if `subString` is `null`.

      ###### See also

      - String#lastIndexOf(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.

  - ### codePointAt

    public int codePointAt(int index)

    Retrieves the Unicode code point value at the `index`.

    ###### Parameters

    - `index`: the index to the `char` code unit.

    ###### Returns

    the Unicode code point value.

    ###### Throws

    - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `index` is negative or greater than or equal to `#length()`.

    ###### See also

    - Character

    - Character#codePointAt(char[], int, int)

  - ### codePointBefore

    public int codePointBefore(int index)

    Retrieves the Unicode code point value that precedes the `index`.

    ###### Parameters

    - `index`: the index to the `char` code unit within this object.

    ###### Returns

    the Unicode code point value.

    ###### Throws

    - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `index` is less than 1 or greater than `#length()`.

    ###### See also

    - Character

    - Character#codePointBefore(char[], int, int)

  - ### codePointCount

    public int codePointCount(int beginIndex, int endIndex)

    Calculates the number of Unicode code points between `beginIndex` and `endIndex`.

    ###### Parameters

    - `beginIndex`: the inclusive beginning index of the subsequence.

    - `endIndex`: the exclusive end index of the subsequence.

    ###### Returns

    the number of Unicode code points in the subsequence.

    ###### Throws

    - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `beginIndex` is negative or greater than `endIndex` or `endIndex` is greater than `#length()`.

    ###### See also

    - Character

    - Character#codePointCount(char[], int, int)

  - ### offsetByCodePoints

    public int offsetByCodePoints(int index, int codePointOffset)

    Returns the index that is offset `codePointOffset` code points from `index`.

    ###### Parameters

    - `index`: the index to calculate the offset from.

    - `codePointOffset`: the number of code points to count.

    ###### Returns

    Returns:

      the index that is `codePointOffset` code points away from index.

      ###### Throws

      - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `index` is negative or greater than `#length()` or if there aren't enough code points before or after `index` to match `codePointOffset`.

      ###### See also

      - Character

      - Character#offsetByCodePoints(char[], int, int, int, int)