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

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, finalize, 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.

      Since

      1.4

      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

      Since

      1.4

      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.
      Since

      1.4

      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.
      Since

      1.4

      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.

      Since

      1.5

    • 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().
      Since

      1.5

      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().
      Since

      1.5

      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().
      Since

      1.5

      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.
      Since

      1.5

      See also

      • Character

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