Package org.apache.commons.text

# Class TextStringBuilder

java.lang.Object
org.apache.commons.text.TextStringBuilder

All Implemented Interfaces:
  `Serializable`, `Appendable`, `CharSequence`, `Supplier<String>`, `Builder<String>`

public class TextStringBuilder extends Object implements CharSequence, Appendable, Serializable, Builder<String>
Builds a string from constituent parts providing a more flexible and powerful API than `StringBuffer` and `StringBuilder`.

The main differences from StringBuffer/StringBuilder are:

- Not synchronized
- Not final
- Subclasses have direct access to character array
- Additional methods
  - appendWithSeparators - adds an array of values, with a separator
  - appendPadding - adds a length padding characters
  - appendFixedLength - adds a fixed width field to the builder
  - toCharArray/getChars - simpler ways to get a range of the character array
  - delete - delete char or string
  - replace - search and replace for a char or string
  - leftString/rightString/midString - substring without exceptions
  - contains - whether the builder contains a char or string
  - size/clear/isEmpty - collections style API methods
- Views
  - asTokenizer - uses the internal buffer as the source of a StrTokenizer
  - asReader - uses the internal buffer as the source of a Reader
  - asWriter - allows a Writer to write directly to the internal buffer

The aim has been to provide an API that mimics very closely what StringBuffer provides, but with additional methods. It should be noted that some edge cases, with invalid indices or null input, have been altered - see individual methods. The biggest of these changes is that by default, null will not output the text 'null'. This can be controlled by a property, `setNullText(String)`.

This class is called `TextStringBuilder` instead of `StringBuilder` to avoid clashing with `StringBuilder`.

Since:
  1.3
See Also:
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TextStringBuilder()`
  Constructs an empty builder with an initial capacity of 32 characters.
  `TextStringBuilder(int initialCapacity)`
  Constructs an instance with the specified initial capacity.
  `TextStringBuilder(CharSequence seq)`
  Constructs an instance from a character sequence, allocating 32 extra characters for growth.
  `TextStringBuilder(String str)`
  Constructs an instance from a string, allocating 32 extra characters for growth.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TextStringBuilder`
  `append(boolean value)`
  Appends a boolean value to the string builder.
  `TextStringBuilder`
  `append(char ch)`
  Appends a char value to the string builder.
  `TextStringBuilder`
  `append(char[] chars)`
  Appends a char array to the string builder.
  `TextStringBuilder`
  `append(char[] chars, int startIndex, int length)`
  Appends a char array to the string builder.
  `TextStringBuilder`
  `append(double value)`
  Appends a double value to the string builder using `String.valueOf`.
  `TextStringBuilder`
  `append(float value)`
  Appends a float value to the string builder using `String.valueOf`.
  `TextStringBuilder`
  `append(int value)`
  Appends an int value to the string builder using `String.valueOf`.
  `TextStringBuilder`
  `append(long value)`
  Appends a long value to the string builder using `String.valueOf`.
  `TextStringBuilder`
  `append(CharSequence seq)`
  Appends a CharSequence to this string builder.
  `TextStringBuilder`
  `append(CharSequence seq, int startIndex, int endIndex)`
  Appends part of a CharSequence to this string builder.
  `TextStringBuilder`
  `append(Object obj)`
  Appends an object to this string builder.
  `TextStringBuilder`
  `append(String str)`
  Appends a string to this string builder.
  `TextStringBuilder`
  `append(StringBuffer str)`
  Appends a string buffer to this string builder.
  `TextStringBuilder`
  `append(StringBuffer str, int startIndex, int length)`
  Appends part of a string buffer to this string builder.
  `TextStringBuilder`
  `append(StringBuilder str)`
  Appends a StringBuilder to this string builder.
  `TextStringBuilder`
  `append(StringBuilder str, int startIndex, int length)`
  Appends part of a StringBuilder to this string builder.
  `TextStringBuilder`
  `append(String str, int startIndex, int length)`
  Appends part of a string to this string builder.
  `TextStringBuilder`
  `append(String format, Object... objs)`
  Calls `String.format(String, Object...)` and appends the result.
  `TextStringBuilder`
  `append(CharBuffer str)`
  Appends the contents of a char buffer to this string builder.
  `TextStringBuilder`
  `append(CharBuffer buf, int startIndex, int length)`
  Appends the contents of a char buffer to this string builder.
  `TextStringBuilder`
  `append(TextStringBuilder str)`
  Appends another string builder to this string builder.
  `TextStringBuilder`
  `append(TextStringBuilder str, int startIndex, int length)`
  Appends part of a string builder to this string builder.
  `TextStringBuilder`
  `appendAll(Iterable<?> iterable)`
  Appends each item in an iterable to the builder without any separators.
  `TextStringBuilder`
  `appendAll(Iterator<?> it)`
  Appends each item in an iterator to the builder without any separators.
  `<T> TextStringBuilder`
  `appendAll(T... array)`
  Appends each item in an array to the builder without any separators.
  `TextStringBuilder`
  `appendFixedWidthPadLeft(int value, int width, char padChar)`
  Appends an object to the builder padding on the left to a fixed width.
  `TextStringBuilder`
  `appendFixedWidthPadLeft(Object obj, int width, char padChar)`
  Appends an object to the builder padding on the left to a fixed width.
  `TextStringBuilder`
  `appendFixedWidthPadRight(int value, int width, char padChar)`
  Appends an object to the builder padding on the right to a fixed length.
  `TextStringBuilder`
  `appendFixedWidthPadRight(Object obj, int width, char padChar)`
  Appends an object to the builder padding on the right to a fixed length.
  `TextStringBuilder`
  `appendln(boolean value)`
  Appends a boolean value followed by a new line to the string builder.
  `TextStringBuilder`
  `appendln(char ch)`
  Appends a char value followed by a new line to the string builder.
  `TextStringBuilder`
  `appendln(char[] chars)`
  Appends a char array followed by a new line to the string builder.
  `TextStringBuilder`
  `appendln(char[] chars, int startIndex, int length)`
  Appends a char array followed by a new line to the string builder.
  `TextStringBuilder`
  `appendln(double value)`
  Appends a double value followed by a new line to the string builder using `String.valueOf`.
  `TextStringBuilder`
  `appendln(float value)`
  Appends a float value followed by a new line to the string builder using `String.valueOf`.
  `TextStringBuilder`
  `appendln(int value)`
  Appends an int value followed by a new line to the string builder using `String.valueOf`.
  `TextStringBuilder`
  `appendln(long value)`
  Appends a long value followed by a new line to the string builder using `String.valueOf`.
  `TextStringBuilder`
  `appendln(Object obj)`
  Appends an object followed by a new line to this string builder.
  `TextStringBuilder`
  `appendln(String str)`
  Appends a string followed by a new line to this string builder.
  `TextStringBuilder`
  `appendln(StringBuffer str)`
  Appends a string buffer followed by a new line to this string builder.
  `TextStringBuilder`
  `appendln(StringBuffer str, int startIndex, int length)`
  Appends part of a string buffer followed by a new line to this string builder.
  `TextStringBuilder`
  `appendln(StringBuilder str)`
  Appends a string builder followed by a new line to this string builder.
  `TextStringBuilder`
  `appendln(StringBuilder str, int startIndex, int length)`
  Appends part of a string builder followed by a new line to this string builder.
  `TextStringBuilder`
  `appendln(String str, int startIndex, int length)`
  Appends part of a string followed by a new line to this string builder.
  `TextStringBuilder`
  `appendln(String format, Object... objs)`
  Calls `String.format(String, Object...)` and appends the result.
  `TextStringBuilder`
  `appendln(TextStringBuilder str)`
  Appends another string builder followed by a new line to this string builder.
  `TextStringBuilder`
  `appendln(TextStringBuilder str, int startIndex, int length)`
  Appends part of a string builder followed by a new line to this string builder.
  `TextStringBuilder`
  `appendNewLine()`
  Appends this builder's new line string to this builder.
  `TextStringBuilder`
  `appendNull()`
  Appends the text representing `null` to this string builder.
  `TextStringBuilder`
  `appendPadding(int length, char padChar)`
  Appends the pad character to the builder the specified number of times.
  `TextStringBuilder`
  `appendSeparator(char separator)`
  Appends a separator if the builder is currently non-empty.
  `TextStringBuilder`
  `appendSeparator(char standard, char defaultIfEmpty)`
  Appends one of both separators to the builder If the builder is currently empty it will append the defaultIfEmpty-separator Otherwise it will append the standard-separator The separator is appended using `append(char)`.
  `TextStringBuilder`
  `appendSeparator(char separator, int loopIndex)`
  Appends a separator to the builder if the loop index is greater than zero.
  `TextStringBuilder`
  `appendSeparator(String separator)`
  Appends a separator if the builder is currently non-empty.
  `TextStringBuilder`
  `appendSeparator(String separator, int loopIndex)`
  Appends a separator to the builder if the loop index is greater than zero.
  `TextStringBuilder`
  `appendSeparator(String standard, String defaultIfEmpty)`
  Appends one of both separators to the StrBuilder.
  `void`
  `appendTo(Appendable appendable)`
  Appends current contents of this `StrBuilder` to the provided `Appendable`.
  `TextStringBuilder`
  `appendWithSeparators(Iterable<?> iterable, String separator)`
  Appends an iterable placing separators between each value, but not before the first or after the last.
  `TextStringBuilder`
  `appendWithSeparators(Object[] array, String separator)`
  Appends an array placing separators between each value, but not before the first or after the last.
  `TextStringBuilder`
  `appendWithSeparators(Iterator<?> it, String separator)`
  Appends an iterator placing separators between each value, but not before the first or after the last.
  `Reader`
  `asReader()`
  Gets the contents of this builder as a Reader.
  `StringTokenizer`
  `asTokenizer()`
  Creates a tokenizer that can tokenize the contents of this builder.
  `Writer`
  `asWriter()`
  Gets this builder as a Writer that can be written to.
  `String`
  `build()`
  Deprecated.
  Use `get()`.
  `int`
  `capacity()`
  Gets the current size of the internal character array buffer.
  `char`
  `charAt(int index)`
  Gets the character at the specified index.
  `TextStringBuilder`
  `clear()`
  Clears the string builder (convenience Collections API style method).
  `boolean`
  `contains(char ch)`
  Tests if the string builder contains the specified char.
  `boolean`
  `contains(String str)`
  Tests if the string builder contains the specified string.
  `boolean`
  `contains(StringMatcher matcher)`
  Tests if the string builder contains a string matched using the specified matcher.
  `TextStringBuilder`
  `delete(int startIndex, int endIndex)`
  Deletes the characters between the two specified indices.
  `TextStringBuilder`
  `deleteAll(char ch)`
  Deletes the character wherever it occurs in the builder.
  `TextStringBuilder`
  `deleteAll(String str)`
  Deletes the string wherever it occurs in the builder.
  `TextStringBuilder`
  `deleteAll(StringMatcher matcher)`
  Deletes all parts of the builder that the matcher matches.
  `TextStringBuilder`
  `deleteCharAt(int index)`
  Deletes the character at the specified index.
  `TextStringBuilder`
  `deleteFirst(char ch)`
  Deletes the character wherever it occurs in the builder.
  `TextStringBuilder`
  `deleteFirst(String str)`
  Deletes the string wherever it occurs in the builder.
  `TextStringBuilder`
  `deleteFirst(StringMatcher matcher)`
  Deletes the first match within the builder using the specified matcher.
  `char`
  `drainChar(int index)`
  Gets the character at the specified index before deleting it.
  `int`
  `drainChars(int startIndex, int endIndex, char[] target, int targetIndex)`
  Drains (copies, then deletes) this character sequence into the specified array.
  `boolean`
  `endsWith(String str)`
  Checks whether this builder ends with the specified string.
  `TextStringBuilder`
  `ensureCapacity(int capacity)`
  Tests the capacity and ensures that it is at least the size specified.
  `boolean`
  `equals(Object obj)`
  Tests the contents of this builder against another to see if they contain the same character content.
  `boolean`
  `equals(TextStringBuilder other)`
  Tests the contents of this builder against another to see if they contain the same character content.
  `boolean`
  `equalsIgnoreCase(TextStringBuilder other)`
  Tests the contents of this builder against another to see if they contain the same character content ignoring case.
  `String`
  `get()`
  Converts this instance to a String.
  `char[]`
  `getChars(char[] target)`
  Copies this character array into the specified array.
  `void`
  `getChars(int startIndex, int endIndex, char[] target, int targetIndex)`
  Copies this character array into the specified array.
  `String`
  `getNewLineText()`
  Gets the text to be appended when a `new line` is added.
  `String`
  `getNullText()`
  Gets the text to be appended when null is added.
  `int`
  `hashCode()`
  Gets a suitable hash code for this builder.
  `int`
  `indexOf(char ch)`
  Searches the string builder to find the first reference to the specified char.
  `int`
  `indexOf(char ch, int startIndex)`
  Searches the string builder to find the first reference to the specified char.
  `int`
  `indexOf(String str)`
  Searches the string builder to find the first reference to the specified string.
  `int`
  `indexOf(String str, int startIndex)`
  Searches the string builder to find the first reference to the specified string starting searching from the given index.
  `int`
  `indexOf(StringMatcher matcher)`
  Searches the string builder using the matcher to find the first match.
  `int`
  `indexOf(StringMatcher matcher, int startIndex)`
  Searches the string builder using the matcher to find the first match searching from the given index.
  `TextStringBuilder`
  `insert(int index, boolean value)`
  Inserts the value into this builder.
  `TextStringBuilder`
  `insert(int index, char value)`
  Inserts the value into this builder.
  `TextStringBuilder`
  `insert(int index, char[] chars)`
  Inserts the character array into this builder.
  `TextStringBuilder`
  `insert(int index, char[] chars, int offset, int length)`
  Inserts part of the character array into this builder.
  `TextStringBuilder`
  `insert(int index, double value)`
  Inserts the value into this builder.
  `TextStringBuilder`
  `insert(int index, float value)`
  Inserts the value into this builder.
  `TextStringBuilder`
  `insert(int index, int value)`
  Inserts the value into this builder.
  `TextStringBuilder`
  `insert(int index, long value)`
  Inserts the value into this builder.
  `TextStringBuilder`
  `insert(int index, Object obj)`
  Inserts the string representation of an object into this builder.
  `TextStringBuilder`
  `insert(int index, String str)`
  Inserts the string into this builder.
  `boolean`
  `isEmpty()`
  Checks is the string builder is empty (convenience Collections API style method).
  `boolean`
  `isNotEmpty()`
  Checks is the string builder is not empty.
  `boolean`
  `isReallocated()`
  Gets whether the internal buffer has been reallocated.
  `int`
  `lastIndexOf(char ch)`
  Searches the string builder to find the last reference to the specified char.
  `int`
  `lastIndexOf(char ch, int startIndex)`
  Searches the string builder to find the last reference to the specified char.
  `int`
  `lastIndexOf(String str)`
  Searches the string builder to find the last reference to the specified string.
  `int`
  `lastIndexOf(String str, int startIndex)`
  Searches the string builder to find the last reference to the specified string starting searching from the given index.
  `int`
  `lastIndexOf(StringMatcher matcher)`
  Searches the string builder using the matcher to find the last match.
  `int`
  `lastIndexOf(StringMatcher matcher, int startIndex)`
  Searches the string builder using the matcher to find the last match searching from the given index.
  `String`
  `leftString(int length)`
  Extracts the leftmost characters from the string builder without throwing an exception.
  `int`
  `length()`
  Gets the length of the string builder.
  `String`
  `midString(int index, int length)`
  Extracts some characters from the middle of the string builder without throwing an exception.
  `TextStringBuilder`
  `minimizeCapacity()`
  Minimizes the capacity to the actual length of the string.
  `int`
  `readFrom(Reader reader)`
  If possible, reads all chars from the provided `Reader` directly into underlying character buffer without making extra copies.
  `int`
  `readFrom(Reader reader, int count)`
  If possible, reads `count` chars from the provided `Reader` directly into underlying character buffer without making extra copies.
  `int`
  `readFrom(Readable readable)`
  If possible, reads all chars from the provided `Readable` directly into underlying character buffer without making extra copies.
  `int`
  `readFrom(CharBuffer charBuffer)`
  If possible, reads chars from the provided `CharBuffer` directly into underlying character buffer without making extra copies.
  `TextStringBuilder`
  `replace(int startIndex, int endIndex, String replaceStr)`
  Replaces a portion of the string builder with another string.
  `TextStringBuilder`
  `replace(StringMatcher matcher, String replaceStr, int startIndex, int endIndex, int replaceCount)`
  Advanced search and replaces within the builder using a matcher.
  `TextStringBuilder`
  `replaceAll(char search, char replace)`
  Replaces the search character with the replace character throughout the builder.
  `TextStringBuilder`
  `replaceAll(String searchStr, String replaceStr)`
  Replaces the search string with the replace string throughout the builder.
  `TextStringBuilder`
  `replaceAll(StringMatcher matcher, String replaceStr)`
  Replaces all matches within the builder with the replace string.
  `TextStringBuilder`
  `replaceFirst(char search, char replace)`
  Replaces the first instance of the search character with the replace character in the builder.
  `TextStringBuilder`
  `replaceFirst(String searchStr, String replaceStr)`
  Replaces the first instance of the search string with the replace string.
  `TextStringBuilder`
  `replaceFirst(StringMatcher matcher, String replaceStr)`
  Replaces the first match within the builder with the replace string.
  `TextStringBuilder`
  `reverse()`
  Reverses the string builder placing each character in the opposite index.
  `String`
  `rightString(int length)`
  Extracts the rightmost characters from the string builder without throwing an exception.
  `TextStringBuilder`
  `set(CharSequence str)`
  Clears and sets this builder to the given value.
  `TextStringBuilder`
  `setCharAt(int index, char ch)`
  Sets the character at the specified index.
  `TextStringBuilder`
  `setLength(int length)`
  Updates the length of the builder by either dropping the last characters or adding filler of Unicode zero.
  `TextStringBuilder`
  `setNewLineText(String newLine)`
  Sets the text to be appended when `new line` is called.
  `TextStringBuilder`
  `setNullText(String nullText)`
  Sets the text to be appended when null is added.
  `int`
  `size()`
  Gets the length of the string builder.
  `boolean`
  `startsWith(String str)`
  Checks whether this builder starts with the specified string.
  `CharSequence`
  `subSequence(int startIndex, int endIndex)`
  `String`
  `substring(int start)`
  Extracts a portion of this string builder as a string.
  `String`
  `substring(int startIndex, int endIndex)`
  Extracts a portion of this string builder as a string.
  `char[]`
  `toCharArray()`
  Copies the builder's character array into a new character array.
  `char[]`
  `toCharArray(int startIndex, int endIndex)`
  Copies part of the builder's character array into a new character array.
  `String`
  `toString()`
  Gets a String version of the string builder, creating a new instance each time the method is called.
  `StringBuffer`
  `toStringBuffer()`
  Gets a StringBuffer version of the string builder, creating a new instance each time the method is called.
  `StringBuilder`
  `toStringBuilder()`
  Gets a StringBuilder version of the string builder, creating a new instance each time the method is called.
  `TextStringBuilder`
  `trim()`
  Trims the builder by removing characters less than or equal to a space from the beginning and end.
  `protected void`
  `validateIndex(int index)`
  Validates that an index is in the range `0 <= index <= size`.
  `protected int`
  `validateRange(int startIndex, int endIndex)`
  Validates parameters defining a range of the builder.
  `static TextStringBuilder`
  `wrap(char[] initialBuffer)`
  Constructs an instance from a reference to a character array.
  `static TextStringBuilder`
  `wrap(char[] initialBuffer, int length)`
  Constructs an instance from a reference to a character array.

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface java.lang.CharSequence

  `chars, codePoints`

- ## Constructor Details

  - ### TextStringBuilder

    public TextStringBuilder()
    Constructs an empty builder with an initial capacity of 32 characters.

  - ### TextStringBuilder

    public TextStringBuilder(CharSequence seq)
    Constructs an instance from a character sequence, allocating 32 extra characters for growth.
    Parameters:
      `seq` - the string to copy, null treated as blank string
    Since:
      1.9

  - ### TextStringBuilder

    public TextStringBuilder(int initialCapacity)
    Constructs an instance with the specified initial capacity.
    Parameters:
      `initialCapacity` - the initial capacity, zero or less will be converted to 32

  - ### TextStringBuilder

    public TextStringBuilder(String str)
    Constructs an instance from a string, allocating 32 extra characters for growth.
    Parameters:
      `str` - the string to copy, null treated as blank string

- ## Method Details

  - ### wrap

    public static TextStringBuilder wrap(char[] initialBuffer)
    Constructs an instance from a reference to a character array. Changes to the input chars are reflected in this instance until the internal buffer needs to be reallocated. Using a reference to an array allows the instance to be initialized without copying the input array.
    Parameters:
      `initialBuffer` - The initial array that will back the new builder.
    Returns:
      A new instance.
    Since:
      1.9

  - ### wrap

    public static TextStringBuilder wrap(char[] initialBuffer, int length)
    Constructs an instance from a reference to a character array. Changes to the input chars are reflected in this instance until the internal buffer needs to be reallocated. Using a reference to an array allows the instance to be initialized without copying the input array.
    Parameters:
      `initialBuffer` - The initial array that will back the new builder.
      `length` - The length of the subarray to be used; must be non-negative and no larger than `initialBuffer.length`. The new builder's size will be set to `length`.
    Returns:
      A new instance.
    Since:
      1.9

  - ### append

    public TextStringBuilder append(boolean value)
    Appends a boolean value to the string builder.
    Parameters:
      `value` - the value to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(char ch)
    Appends a char value to the string builder.
    Specified by:
      `append` in interface `Appendable`
    Parameters:
      `ch` - the value to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(char[] chars)
    Appends a char array to the string builder. Appending null will call `appendNull()`.
    Parameters:
      `chars` - the char array to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(char[] chars, int startIndex, int length)
    Appends a char array to the string builder. Appending null will call `appendNull()`.
    Parameters:
      `chars` - the char array to append
      `startIndex` - the start index, inclusive, must be valid
      `length` - the length to append, must be valid
    Returns:
      this, to enable chaining
    Throws:
      `StringIndexOutOfBoundsException` - if `startIndex` is not in the range `0 <= startIndex <= chars.length`
      `StringIndexOutOfBoundsException` - if `length < 0`
      `StringIndexOutOfBoundsException` - if `startIndex + length > chars.length`

  - ### append

    public TextStringBuilder append(CharBuffer str)
    Appends the contents of a char buffer to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the char buffer to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(CharBuffer buf, int startIndex, int length)
    Appends the contents of a char buffer to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `buf` - the char buffer to append
      `startIndex` - the start index, inclusive, must be valid
      `length` - the length to append, must be valid
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(CharSequence seq)
    Appends a CharSequence to this string builder. Appending null will call `appendNull()`.
    Specified by:
      `append` in interface `Appendable`
    Parameters:
      `seq` - the CharSequence to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(CharSequence seq, int startIndex, int endIndex)
    Appends part of a CharSequence to this string builder. Appending null will call `appendNull()`.
    Specified by:
      `append` in interface `Appendable`
    Parameters:
      `seq` - the CharSequence to append
      `startIndex` - the start index, inclusive, must be valid
      `endIndex` - the end index, exclusive, must be valid
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(double value)
    Appends a double value to the string builder using `String.valueOf`.
    Parameters:
      `value` - the value to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(float value)
    Appends a float value to the string builder using `String.valueOf`.
    Parameters:
      `value` - the value to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(int value)
    Appends an int value to the string builder using `String.valueOf`.
    Parameters:
      `value` - the value to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(long value)
    Appends a long value to the string builder using `String.valueOf`.
    Parameters:
      `value` - the value to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(Object obj)
    Appends an object to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `obj` - the object to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(String str)
    Appends a string to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(String str, int startIndex, int length)
    Appends part of a string to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string to append
      `startIndex` - the start index, inclusive, must be valid
      `length` - the length to append, must be valid
    Returns:
      this, to enable chaining
    Throws:
      `StringIndexOutOfBoundsException` - if `startIndex` is not in the range `0 <= startIndex <= str.length()`
      `StringIndexOutOfBoundsException` - if `length < 0`
      `StringIndexOutOfBoundsException` - if `startIndex + length > str.length()`

  - ### append

    public TextStringBuilder append(String format, Object... objs)
    Calls `String.format(String, Object...)` and appends the result.
    Parameters:
      `format` - the format string
      `objs` - the objects to use in the format string
    Returns:
      `this` to enable chaining
    See Also:
      - `String.format(String, Object...)`

  - ### append

    public TextStringBuilder append(StringBuffer str)
    Appends a string buffer to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string buffer to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(StringBuffer str, int startIndex, int length)
    Appends part of a string buffer to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string to append
      `startIndex` - the start index, inclusive, must be valid
      `length` - the length to append, must be valid
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(StringBuilder str)
    Appends a StringBuilder to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the StringBuilder to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(StringBuilder str, int startIndex, int length)
    Appends part of a StringBuilder to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the StringBuilder to append
      `startIndex` - the start index, inclusive, must be valid
      `length` - the length to append, must be valid
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(TextStringBuilder str)
    Appends another string builder to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string builder to append
    Returns:
      this, to enable chaining

  - ### append

    public TextStringBuilder append(TextStringBuilder str, int startIndex, int length)
    Appends part of a string builder to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string to append
      `startIndex` - the start index, inclusive, must be valid
      `length` - the length to append, must be valid
    Returns:
      this, to enable chaining

  - ### appendAll

    public TextStringBuilder appendAll(Iterable<?> iterable)
    Appends each item in an iterable to the builder without any separators. Appending a null iterable will have no effect. Each object is appended using `append(Object)`.
    Parameters:
      `iterable` - the iterable to append
    Returns:
      this, to enable chaining

  - ### appendAll

    public TextStringBuilder appendAll(Iterator<?> it)
    Appends each item in an iterator to the builder without any separators. Appending a null iterator will have no effect. Each object is appended using `append(Object)`.
    Parameters:
      `it` - the iterator to append
    Returns:
      this, to enable chaining

  - ### appendAll

    public <T> TextStringBuilder appendAll(T... array)
    Appends each item in an array to the builder without any separators. Appending a null array will have no effect. Each object is appended using `append(Object)`.
    Type Parameters:
      `T` - the element type
    Parameters:
      `array` - the array to append
    Returns:
      this, to enable chaining

  - ### appendFixedWidthPadLeft

    public TextStringBuilder appendFixedWidthPadLeft(int value, int width, char padChar)
    Appends an object to the builder padding on the left to a fixed width. The `String.valueOf` of the `int` value is used. If the formatted value is larger than the length, the left hand side is lost.
    Parameters:
      `value` - the value to append
      `width` - the fixed field width, zero or negative has no effect
      `padChar` - the pad character to use
    Returns:
      this, to enable chaining

  - ### appendFixedWidthPadLeft

    public TextStringBuilder appendFixedWidthPadLeft(Object obj, int width, char padChar)
    Appends an object to the builder padding on the left to a fixed width. The `toString` of the object is used. If the object is larger than the length, the left hand side is lost. If the object is null, the null text value is used.
    Parameters:
      `obj` - the object to append, null uses null text
      `width` - the fixed field width, zero or negative has no effect
      `padChar` - the pad character to use
    Returns:
      this, to enable chaining

  - ### appendFixedWidthPadRight

    public TextStringBuilder appendFixedWidthPadRight(int value, int width, char padChar)
    Appends an object to the builder padding on the right to a fixed length. The `String.valueOf` of the `int` value is used. If the object is larger than the length, the right hand side is lost.
    Parameters:
      `value` - the value to append
      `width` - the fixed field width, zero or negative has no effect
      `padChar` - the pad character to use
    Returns:
      this, to enable chaining

  - ### appendFixedWidthPadRight

    public TextStringBuilder appendFixedWidthPadRight(Object obj, int width, char padChar)
    Appends an object to the builder padding on the right to a fixed length. The `toString` of the object is used. If the object is larger than the length, the right hand side is lost. If the object is null, null text value is used.
    Parameters:
      `obj` - the object to append, null uses null text
      `width` - the fixed field width, zero or negative has no effect
      `padChar` - the pad character to use
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(boolean value)
    Appends a boolean value followed by a new line to the string builder.
    Parameters:
      `value` - the value to append
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(char ch)
    Appends a char value followed by a new line to the string builder.
    Parameters:
      `ch` - the value to append
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(char[] chars)
    Appends a char array followed by a new line to the string builder. Appending null will call `appendNull()`.
    Parameters:
      `chars` - the char array to append
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(char[] chars, int startIndex, int length)
    Appends a char array followed by a new line to the string builder. Appending null will call `appendNull()`.
    Parameters:
      `chars` - the char array to append
      `startIndex` - the start index, inclusive, must be valid
      `length` - the length to append, must be valid
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(double value)
    Appends a double value followed by a new line to the string builder using `String.valueOf`.
    Parameters:
      `value` - the value to append
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(float value)
    Appends a float value followed by a new line to the string builder using `String.valueOf`.
    Parameters:
      `value` - the value to append
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(int value)
    Appends an int value followed by a new line to the string builder using `String.valueOf`.
    Parameters:
      `value` - the value to append
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(long value)
    Appends a long value followed by a new line to the string builder using `String.valueOf`.
    Parameters:
      `value` - the value to append
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(Object obj)
    Appends an object followed by a new line to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `obj` - the object to append
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(String str)
    Appends a string followed by a new line to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string to append
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(String str, int startIndex, int length)
    Appends part of a string followed by a new line to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string to append
      `startIndex` - the start index, inclusive, must be valid
      `length` - the length to append, must be valid
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(String format, Object... objs)
    Calls `String.format(String, Object...)` and appends the result.
    Parameters:
      `format` - the format string
      `objs` - the objects to use in the format string
    Returns:
      `this` to enable chaining
    See Also:
      - `String.format(String, Object...)`

  - ### appendln

    public TextStringBuilder appendln(StringBuffer str)
    Appends a string buffer followed by a new line to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string buffer to append
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(StringBuffer str, int startIndex, int length)
    Appends part of a string buffer followed by a new line to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string to append
      `startIndex` - the start index, inclusive, must be valid
      `length` - the length to append, must be valid
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(StringBuilder str)
    Appends a string builder followed by a new line to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string builder to append
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(StringBuilder str, int startIndex, int length)
    Appends part of a string builder followed by a new line to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string builder to append
      `startIndex` - the start index, inclusive, must be valid
      `length` - the length to append, must be valid
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(TextStringBuilder str)
    Appends another string builder followed by a new line to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string builder to append
    Returns:
      this, to enable chaining

  - ### appendln

    public TextStringBuilder appendln(TextStringBuilder str, int startIndex, int length)
    Appends part of a string builder followed by a new line to this string builder. Appending null will call `appendNull()`.
    Parameters:
      `str` - the string to append
      `startIndex` - the start index, inclusive, must be valid
      `length` - the length to append, must be valid
    Returns:
      this, to enable chaining

  - ### appendNewLine

    public TextStringBuilder appendNewLine()
    Appends this builder's new line string to this builder.

    By default, the new line is the system default from `System.lineSeparator()`.

    The new line string can be changed using `setNewLineText(String)`. For example, you can use this to force the output to always use Unix line endings even when on Windows.

    Returns:
      this
    See Also:
      - `getNewLineText()`
      - `setNewLineText(String)`

  - ### appendNull

    public TextStringBuilder appendNull()
    Appends the text representing `null` to this string builder.
    Returns:
      this, to enable chaining

  - ### appendPadding

    public TextStringBuilder appendPadding(int length, char padChar)
    Appends the pad character to the builder the specified number of times.
    Parameters:
      `length` - the length to append, negative means no append
      `padChar` - the character to append
    Returns:
      this, to enable chaining

  - ### appendSeparator

    public TextStringBuilder appendSeparator(char separator)
    Appends a separator if the builder is currently non-empty. The separator is appended using `append(char)`.

    This method is useful for adding a separator each time around the loop except the first.

         for (Iterator it = list.iterator(); it.hasNext();) {
             appendSeparator(',');
             append(it.next());
         }

    Note that for this simple example, you should use `appendWithSeparators(Iterable, String)`.

    Parameters:
      `separator` - the separator to use
    Returns:
      this, to enable chaining

  - ### appendSeparator

    public TextStringBuilder appendSeparator(char standard, char defaultIfEmpty)
    Appends one of both separators to the builder If the builder is currently empty it will append the defaultIfEmpty-separator Otherwise it will append the standard-separator The separator is appended using `append(char)`.
    Parameters:
      `standard` - the separator if builder is not empty
      `defaultIfEmpty` - the separator if builder is empty
    Returns:
      this, to enable chaining

  - ### appendSeparator

    public TextStringBuilder appendSeparator(char separator, int loopIndex)
    Appends a separator to the builder if the loop index is greater than zero. The separator is appended using `append(char)`.

    This method is useful for adding a separator each time around the loop except the first.

         for (int i = 0; i < list.size(); i++) {
             appendSeparator(",", i);
             append(list.get(i));
         }

    Note that for this simple example, you should use `appendWithSeparators(Iterable, String)`.

    Parameters:
      `separator` - the separator to use
      `loopIndex` - the loop index
    Returns:
      this, to enable chaining

  - ### appendSeparator

    public TextStringBuilder appendSeparator(String separator)
    Appends a separator if the builder is currently non-empty. Appending a null separator will have no effect. The separator is appended using `append(String)`.

    This method is useful for adding a separator each time around the loop except the first.

         for (Iterator it = list.iterator(); it.hasNext();) {
             appendSeparator(",");
             append(it.next());
         }

    Note that for this simple example, you should use `appendWithSeparators(Iterable, String)`.

    Parameters:
      `separator` - the separator to use, null means no separator
    Returns:
      this, to enable chaining

  - ### appendSeparator

    public TextStringBuilder appendSeparator(String separator, int loopIndex)
    Appends a separator to the builder if the loop index is greater than zero. Appending a null separator will have no effect. The separator is appended using `append(String)`.

    This method is useful for adding a separator each time around the loop except the first.

         for (int i = 0; i < list.size(); i++) {
             appendSeparator(",", i);
             append(list.get(i));
         }

    Note that for this simple example, you should use `appendWithSeparators(Iterable, String)`.

    Parameters:
      `separator` - the separator to use, null means no separator
      `loopIndex` - the loop index
    Returns:
      this, to enable chaining

  - ### appendSeparator

    public TextStringBuilder appendSeparator(String standard, String defaultIfEmpty)
    Appends one of both separators to the StrBuilder. If the builder is currently empty, it will append the defaultIfEmpty-separator, otherwise it will append the standard-separator.

    Appending a null separator will have no effect. The separator is appended using `append(String)`.

    This method is for example useful for constructing queries

         StrBuilder whereClause = new StrBuilder();
         if (searchCommand.getPriority() != null) {
          whereClause.appendSeparator(" and", " where");
          whereClause.append(" priority = ?")
         }
         if (searchCommand.getComponent() != null) {
          whereClause.appendSeparator(" and", " where");
          whereClause.append(" component = ?")
         }
         selectClause.append(whereClause)

    Parameters:
      `standard` - the separator if builder is not empty, null means no separator
      `defaultIfEmpty` - the separator if builder is empty, null means no separator
    Returns:
      this, to enable chaining

  - ### appendTo

    public void appendTo(Appendable appendable) throws IOException
    Appends current contents of this `StrBuilder` to the provided `Appendable`.

    This method tries to avoid doing any extra copies of contents.

    Parameters:
      `appendable` - the appendable to append data to
    Throws:
      `IOException` - if an I/O error occurs.
    See Also:
      - `readFrom(Readable)`

  - ### appendWithSeparators

    public TextStringBuilder appendWithSeparators(Iterable<?> iterable, String separator)
    Appends an iterable placing separators between each value, but not before the first or after the last. Appending a null iterable will have no effect. Each object is appended using `append(Object)`.
    Parameters:
      `iterable` - the iterable to append
      `separator` - the separator to use, null means no separator
    Returns:
      this, to enable chaining

  - ### appendWithSeparators

    public TextStringBuilder appendWithSeparators(Iterator<?> it, String separator)
    Appends an iterator placing separators between each value, but not before the first or after the last. Appending a null iterator will have no effect. Each object is appended using `append(Object)`.
    Parameters:
      `it` - the iterator to append
      `separator` - the separator to use, null means no separator
    Returns:
      this, to enable chaining

  - ### appendWithSeparators

    public TextStringBuilder appendWithSeparators(Object[] array, String separator)
    Appends an array placing separators between each value, but not before the first or after the last. Appending a null array will have no effect. Each object is appended using `append(Object)`.
    Parameters:
      `array` - the array to append
      `separator` - the separator to use, null means no separator
    Returns:
      this, to enable chaining

  - ### asReader

    public Reader asReader()
    Gets the contents of this builder as a Reader.

    This method allows the contents of the builder to be read using any standard method that expects a Reader.

    To use, simply create a `StrBuilder`, populate it with data, call `asReader`, and then read away.

    The internal character array is shared between the builder and the reader. This allows you to append to the builder after creating the reader, and the changes will be picked up. Note however, that no synchronization occurs, so you must perform all operations with the builder and the reader in one thread.

    The returned reader supports marking, and ignores the flush method.

    Returns:
      a reader that reads from this builder

  - ### asTokenizer

    public StringTokenizer asTokenizer()
    Creates a tokenizer that can tokenize the contents of this builder.

    This method allows the contents of this builder to be tokenized. The tokenizer will be setup by default to tokenize on space, tab, newline and form feed (as per StringTokenizer). These values can be changed on the tokenizer class, before retrieving the tokens.

    The returned tokenizer is linked to this builder. You may intermix calls to the builder and tokenizer within certain limits, however there is no synchronization. Once the tokenizer has been used once, it must be `reset` to pickup the latest changes in the builder. For example:

         StrBuilder b = new StrBuilder();
         b.append("a b ");
         StrTokenizer t = b.asTokenizer();
         String[] tokens1 = t.getTokenArray(); // returns a,b
         b.append("c d ");
         String[] tokens2 = t.getTokenArray(); // returns a,b (c and d ignored)
         t.reset(); // reset causes builder changes to be picked up
         String[] tokens3 = t.getTokenArray(); // returns a,b,c,d

    In addition to simply intermixing appends and tokenization, you can also call the set methods on the tokenizer to alter how it tokenizes. Just remember to call reset when you want to pickup builder changes.

    Calling `StringTokenizer.reset(String)` or `StringTokenizer.reset(char[])` with a non-null value will break the link with the builder.

    Returns:
      a tokenizer that is linked to this builder

  - ### asWriter

    public Writer asWriter()
    Gets this builder as a Writer that can be written to.

    This method allows you to populate the contents of the builder using any standard method that takes a Writer.

    To use, simply create a `StrBuilder`, call `asWriter`, and populate away. The data is available at any time using the methods of the `StrBuilder`.

    The internal character array is shared between the builder and the writer. This allows you to intermix calls that append to the builder and write using the writer and the changes will be occur correctly. Note however, that no synchronization occurs, so you must perform all operations with the builder and the writer in one thread.

    The returned writer ignores the close and flush methods.

    Returns:
      a writer that populates this builder

  - ### build

    @Deprecated public String build()
    Deprecated.
    Use `get()`.
    Converts this instance to a String.
    Specified by:
      `build` in interface `Builder<String>`
    Returns:
      This instance as a String
    See Also:
      - `toString()`

  - ### capacity

    public int capacity()
    Gets the current size of the internal character array buffer.
    Returns:
      The capacity

  - ### charAt

    public char charAt(int index)
    Gets the character at the specified index.
    Specified by:
      `charAt` in interface `CharSequence`
    Parameters:
      `index` - the index to retrieve, must be valid
    Returns:
      The character at the index
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid
    See Also:
      - `setCharAt(int, char)`
      - `deleteCharAt(int)`

  - ### clear

    public TextStringBuilder clear()
    Clears the string builder (convenience Collections API style method).

    This method does not reduce the size of the internal character buffer. To do that, call `clear()` followed by `minimizeCapacity()`.

    This method is the same as `setLength(int)` called with zero and is provided to match the API of Collections.

    Returns:
      this, to enable chaining

  - ### contains

    public boolean contains(char ch)
    Tests if the string builder contains the specified char.
    Parameters:
      `ch` - the character to find
    Returns:
      true if the builder contains the character

  - ### contains

    public boolean contains(String str)
    Tests if the string builder contains the specified string.
    Parameters:
      `str` - the string to find
    Returns:
      true if the builder contains the string

  - ### contains

    public boolean contains(StringMatcher matcher)
    Tests if the string builder contains a string matched using the specified matcher.

    Matchers can be used to perform advanced searching behavior. For example you could write a matcher to search for the character 'a' followed by a number.

    Parameters:
      `matcher` - the matcher to use, null returns -1
    Returns:
      true if the matcher finds a match in the builder

  - ### delete

    public TextStringBuilder delete(int startIndex, int endIndex)
    Deletes the characters between the two specified indices.
    Parameters:
      `startIndex` - the start index, inclusive, must be valid
      `endIndex` - the end index, exclusive, must be valid except that if too large it is treated as end of string
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### deleteAll

    public TextStringBuilder deleteAll(char ch)
    Deletes the character wherever it occurs in the builder.
    Parameters:
      `ch` - the character to delete
    Returns:
      this, to enable chaining

  - ### deleteAll

    public TextStringBuilder deleteAll(String str)
    Deletes the string wherever it occurs in the builder.
    Parameters:
      `str` - the string to delete, null causes no action
    Returns:
      this, to enable chaining

  - ### deleteAll

    public TextStringBuilder deleteAll(StringMatcher matcher)
    Deletes all parts of the builder that the matcher matches.

    Matchers can be used to perform advanced deletion behavior. For example you could write a matcher to delete all occurrences where the character 'a' is followed by a number.

    Parameters:
      `matcher` - the matcher to use to find the deletion, null causes no action
    Returns:
      this, to enable chaining

  - ### deleteCharAt

    public TextStringBuilder deleteCharAt(int index)
    Deletes the character at the specified index.
    Parameters:
      `index` - the index to delete
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid
    See Also:
      - `charAt(int)`
      - `setCharAt(int, char)`

  - ### deleteFirst

    public TextStringBuilder deleteFirst(char ch)
    Deletes the character wherever it occurs in the builder.
    Parameters:
      `ch` - the character to delete
    Returns:
      this, to enable chaining

  - ### deleteFirst

    public TextStringBuilder deleteFirst(String str)
    Deletes the string wherever it occurs in the builder.
    Parameters:
      `str` - the string to delete, null causes no action
    Returns:
      this, to enable chaining

  - ### deleteFirst

    public TextStringBuilder deleteFirst(StringMatcher matcher)
    Deletes the first match within the builder using the specified matcher.

    Matchers can be used to perform advanced deletion behavior. For example you could write a matcher to delete where the character 'a' is followed by a number.

    Parameters:
      `matcher` - the matcher to use to find the deletion, null causes no action
    Returns:
      this, to enable chaining

  - ### drainChar

    public char drainChar(int index)
    Gets the character at the specified index before deleting it.
    Parameters:
      `index` - the index to retrieve, must be valid
    Returns:
      The character at the index
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid
    Since:
      1.9
    See Also:
      - `charAt(int)`
      - `deleteCharAt(int)`

  - ### drainChars

    public int drainChars(int startIndex, int endIndex, char[] target, int targetIndex)
    Drains (copies, then deletes) this character sequence into the specified array. This is equivalent to copying the characters from this sequence into the target and then deleting those character from this sequence.
    Parameters:
      `startIndex` - first index to copy, inclusive.
      `endIndex` - last index to copy, exclusive.
      `target` - the target array, must not be `null`.
      `targetIndex` - the index to start copying in the target.
    Returns:
      How many characters where copied (then deleted). If this builder is empty, return `0`.
    Since:
      1.9

  - ### endsWith

    public boolean endsWith(String str)
    Checks whether this builder ends with the specified string.

    Note that this method handles null input quietly, unlike String.

    Parameters:
      `str` - the string to search for, null returns false
    Returns:
      true if the builder ends with the string

  - ### ensureCapacity

    public TextStringBuilder ensureCapacity(int capacity)
    Tests the capacity and ensures that it is at least the size specified.

    Note: This method can be used to minimise memory reallocations during repeated addition of values by pre-allocating the character buffer. The method ignores a negative `capacity` argument.

    Parameters:
      `capacity` - the capacity to ensure
    Returns:
      this, to enable chaining
    Throws:
      `OutOfMemoryError` - if the capacity cannot be allocated

  - ### equals

    public boolean equals(Object obj)
    Tests the contents of this builder against another to see if they contain the same character content.
    Overrides:
      `equals` in class `Object`
    Parameters:
      `obj` - the object to check, null returns false
    Returns:
      true if the builders contain the same characters in the same order

  - ### equals

    public boolean equals(TextStringBuilder other)
    Tests the contents of this builder against another to see if they contain the same character content.
    Parameters:
      `other` - the object to check, null returns false
    Returns:
      true if the builders contain the same characters in the same order

  - ### equalsIgnoreCase

    public boolean equalsIgnoreCase(TextStringBuilder other)
    Tests the contents of this builder against another to see if they contain the same character content ignoring case.
    Parameters:
      `other` - the object to check, null returns false
    Returns:
      true if the builders contain the same characters in the same order

  - ### get

    public String get()
    Converts this instance to a String.
    Specified by:
      `get` in interface `Supplier<String>`
    Returns:
      This instance as a String
    Since:
      1.12.0
    See Also:
      - `toString()`

  - ### getChars

    public char[] getChars(char[] target)
    Copies this character array into the specified array.
    Parameters:
      `target` - the target array, null will cause an array to be created
    Returns:
      The input array, unless that was null or too small

  - ### getChars

    public void getChars(int startIndex, int endIndex, char[] target, int targetIndex)
    Copies this character array into the specified array.
    Parameters:
      `startIndex` - first index to copy, inclusive, must be valid.
      `endIndex` - last index to copy, exclusive, must be valid.
      `target` - the target array, must not be null or too small.
      `targetIndex` - the index to start copying in target.
    Throws:
      `NullPointerException` - if the array is null.
      `IndexOutOfBoundsException` - if any index is invalid.

  - ### getNewLineText

    public String getNewLineText()
    Gets the text to be appended when a `new line` is added.
    Returns:
      The new line text, `null` means use the system default from `System.lineSeparator()`.

  - ### getNullText

    public String getNullText()
    Gets the text to be appended when null is added.
    Returns:
      The null text, null means no append

  - ### hashCode

    public int hashCode()
    Gets a suitable hash code for this builder.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      a hash code

  - ### indexOf

    public int indexOf(char ch)
    Searches the string builder to find the first reference to the specified char.
    Parameters:
      `ch` - the character to find
    Returns:
      The first index of the character, or -1 if not found

  - ### indexOf

    public int indexOf(char ch, int startIndex)
    Searches the string builder to find the first reference to the specified char.
    Parameters:
      `ch` - the character to find
      `startIndex` - the index to start at, invalid index rounded to edge
    Returns:
      The first index of the character, or -1 if not found

  - ### indexOf

    public int indexOf(String str)
    Searches the string builder to find the first reference to the specified string.

    Note that a null input string will return -1, whereas the JDK throws an exception.

    Parameters:
      `str` - the string to find, null returns -1
    Returns:
      The first index of the string, or -1 if not found

  - ### indexOf

    public int indexOf(String str, int startIndex)
    Searches the string builder to find the first reference to the specified string starting searching from the given index.

    Note that a null input string will return -1, whereas the JDK throws an exception.

    Parameters:
      `str` - the string to find, null returns -1
      `startIndex` - the index to start at, invalid index rounded to edge
    Returns:
      The first index of the string, or -1 if not found

  - ### indexOf

    public int indexOf(StringMatcher matcher)
    Searches the string builder using the matcher to find the first match.

    Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the character 'a' followed by a number.

    Parameters:
      `matcher` - the matcher to use, null returns -1
    Returns:
      The first index matched, or -1 if not found

  - ### indexOf

    public int indexOf(StringMatcher matcher, int startIndex)
    Searches the string builder using the matcher to find the first match searching from the given index.

    Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the character 'a' followed by a number.

    Parameters:
      `matcher` - the matcher to use, null returns -1
      `startIndex` - the index to start at, invalid index rounded to edge
    Returns:
      The first index matched, or -1 if not found

  - ### insert

    public TextStringBuilder insert(int index, boolean value)
    Inserts the value into this builder.
    Parameters:
      `index` - the index to add at, must be valid
      `value` - the value to insert
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### insert

    public TextStringBuilder insert(int index, char value)
    Inserts the value into this builder.
    Parameters:
      `index` - the index to add at, must be valid
      `value` - the value to insert
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### insert

    public TextStringBuilder insert(int index, char[] chars)
    Inserts the character array into this builder. Inserting null will use the stored null text value.
    Parameters:
      `index` - the index to add at, must be valid
      `chars` - the char array to insert
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### insert

    public TextStringBuilder insert(int index, char[] chars, int offset, int length)
    Inserts part of the character array into this builder. Inserting null will use the stored null text value.
    Parameters:
      `index` - the index to add at, must be valid
      `chars` - the char array to insert
      `offset` - the offset into the character array to start at, must be valid
      `length` - the length of the character array part to copy, must be positive
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if any index is invalid

  - ### insert

    public TextStringBuilder insert(int index, double value)
    Inserts the value into this builder.
    Parameters:
      `index` - the index to add at, must be valid
      `value` - the value to insert
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### insert

    public TextStringBuilder insert(int index, float value)
    Inserts the value into this builder.
    Parameters:
      `index` - the index to add at, must be valid
      `value` - the value to insert
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### insert

    public TextStringBuilder insert(int index, int value)
    Inserts the value into this builder.
    Parameters:
      `index` - the index to add at, must be valid
      `value` - the value to insert
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### insert

    public TextStringBuilder insert(int index, long value)
    Inserts the value into this builder.
    Parameters:
      `index` - the index to add at, must be valid
      `value` - the value to insert
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### insert

    public TextStringBuilder insert(int index, Object obj)
    Inserts the string representation of an object into this builder. Inserting null will use the stored null text value.
    Parameters:
      `index` - the index to add at, must be valid
      `obj` - the object to insert
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### insert

    public TextStringBuilder insert(int index, String str)
    Inserts the string into this builder. Inserting null will use the stored null text value.
    Parameters:
      `index` - the index to add at, must be valid
      `str` - the string to insert
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### isEmpty

    public boolean isEmpty()
    Checks is the string builder is empty (convenience Collections API style method).

    This method is the same as checking `length()` and is provided to match the API of Collections.

    Returns:
      `true` if the size is `0`.

  - ### isNotEmpty

    public boolean isNotEmpty()
    Checks is the string builder is not empty.

    This method is the same as checking `length()`.

    Returns:
      `true` if the size is not `0`.
    Since:
      1.9

  - ### isReallocated

    public boolean isReallocated()
    Gets whether the internal buffer has been reallocated.
    Returns:
      Whether the internal buffer has been reallocated.
    Since:
      1.9

  - ### lastIndexOf

    public int lastIndexOf(char ch)
    Searches the string builder to find the last reference to the specified char.
    Parameters:
      `ch` - the character to find
    Returns:
      The last index of the character, or -1 if not found

  - ### lastIndexOf

    public int lastIndexOf(char ch, int startIndex)
    Searches the string builder to find the last reference to the specified char.
    Parameters:
      `ch` - the character to find
      `startIndex` - the index to start at, invalid index rounded to edge
    Returns:
      The last index of the character, or -1 if not found

  - ### lastIndexOf

    public int lastIndexOf(String str)
    Searches the string builder to find the last reference to the specified string.

    Note that a null input string will return -1, whereas the JDK throws an exception.

    Parameters:
      `str` - the string to find, null returns -1
    Returns:
      The last index of the string, or -1 if not found

  - ### lastIndexOf

    public int lastIndexOf(String str, int startIndex)
    Searches the string builder to find the last reference to the specified string starting searching from the given index.

    Note that a null input string will return -1, whereas the JDK throws an exception.

    Parameters:
      `str` - the string to find, null returns -1
      `startIndex` - the index to start at, invalid index rounded to edge
    Returns:
      The last index of the string, or -1 if not found

  - ### lastIndexOf

    public int lastIndexOf(StringMatcher matcher)
    Searches the string builder using the matcher to find the last match.

    Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the character 'a' followed by a number.

    Parameters:
      `matcher` - the matcher to use, null returns -1
    Returns:
      The last index matched, or -1 if not found

  - ### lastIndexOf

    public int lastIndexOf(StringMatcher matcher, int startIndex)
    Searches the string builder using the matcher to find the last match searching from the given index.

    Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the character 'a' followed by a number.

    Parameters:
      `matcher` - the matcher to use, null returns -1
      `startIndex` - the index to start at, invalid index rounded to edge
    Returns:
      The last index matched, or -1 if not found

  - ### leftString

    public String leftString(int length)
    Extracts the leftmost characters from the string builder without throwing an exception.

    This method extracts the left `length` characters from the builder. If this many characters are not available, the whole builder is returned. Thus the returned string may be shorter than the length requested.

    Parameters:
      `length` - the number of characters to extract, negative returns empty string
    Returns:
      The new string

  - ### length

    public int length()
    Gets the length of the string builder.
    Specified by:
      `length` in interface `CharSequence`
    Returns:
      The length

  - ### midString

    public String midString(int index, int length)
    Extracts some characters from the middle of the string builder without throwing an exception.

    This method extracts `length` characters from the builder at the specified index. If the index is negative it is treated as zero. If the index is greater than the builder size, it is treated as the builder size. If the length is negative, the empty string is returned. If insufficient characters are available in the builder, as much as possible is returned. Thus the returned string may be shorter than the length requested.

    Parameters:
      `index` - the index to start at, negative means zero
      `length` - the number of characters to extract, negative returns empty string
    Returns:
      The new string

  - ### minimizeCapacity

    public TextStringBuilder minimizeCapacity()
    Minimizes the capacity to the actual length of the string.
    Returns:
      this, to enable chaining

  - ### readFrom

    public int readFrom(CharBuffer charBuffer)
    If possible, reads chars from the provided `CharBuffer` directly into underlying character buffer without making extra copies.
    Parameters:
      `charBuffer` - CharBuffer to read.
    Returns:
      The number of characters read.
    Since:
      1.9
    See Also:
      - `appendTo(Appendable)`

  - ### readFrom

    public int readFrom(Readable readable) throws IOException
    If possible, reads all chars from the provided `Readable` directly into underlying character buffer without making extra copies.
    Parameters:
      `readable` - object to read from
    Returns:
      The number of characters read
    Throws:
      `IOException` - if an I/O error occurs.
    See Also:
      - `appendTo(Appendable)`

  - ### readFrom

    public int readFrom(Reader reader) throws IOException
    If possible, reads all chars from the provided `Reader` directly into underlying character buffer without making extra copies.
    Parameters:
      `reader` - Reader to read.
    Returns:
      The number of characters read or -1 if we reached the end of stream.
    Throws:
      `IOException` - if an I/O error occurs.
    Since:
      1.9
    See Also:
      - `appendTo(Appendable)`

  - ### readFrom

    public int readFrom(Reader reader, int count) throws IOException
    If possible, reads `count` chars from the provided `Reader` directly into underlying character buffer without making extra copies.
    Parameters:
      `reader` - Reader to read.
      `count` - The maximum characters to read, a value <= 0 returns 0.
    Returns:
      The number of characters read. If less than `count`, then we've reached the end-of-stream, or -1 if we reached the end of stream.
    Throws:
      `IOException` - if an I/O error occurs.
    Since:
      1.9
    See Also:
      - `appendTo(Appendable)`

  - ### replace

    public TextStringBuilder replace(int startIndex, int endIndex, String replaceStr)
    Replaces a portion of the string builder with another string. The length of the inserted string does not have to match the removed length.
    Parameters:
      `startIndex` - the start index, inclusive, must be valid
      `endIndex` - the end index, exclusive, must be valid except that if too large it is treated as end of string
      `replaceStr` - the string to replace with, null means delete range
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### replace

    public TextStringBuilder replace(StringMatcher matcher, String replaceStr, int startIndex, int endIndex, int replaceCount)
    Advanced search and replaces within the builder using a matcher.

    Matchers can be used to perform advanced behavior. For example you could write a matcher to delete all occurrences where the character 'a' is followed by a number.

    Parameters:
      `matcher` - the matcher to use to find the deletion, null causes no action
      `replaceStr` - the string to replace the match with, null is a delete
      `startIndex` - the start index, inclusive, must be valid
      `endIndex` - the end index, exclusive, must be valid except that if too large it is treated as end of string
      `replaceCount` - the number of times to replace, -1 for replace all
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if start index is invalid

  - ### replaceAll

    public TextStringBuilder replaceAll(char search, char replace)
    Replaces the search character with the replace character throughout the builder.
    Parameters:
      `search` - the search character
      `replace` - the replace character
    Returns:
      this, to enable chaining

  - ### replaceAll

    public TextStringBuilder replaceAll(String searchStr, String replaceStr)
    Replaces the search string with the replace string throughout the builder.
    Parameters:
      `searchStr` - the search string, null causes no action to occur
      `replaceStr` - the replace string, null is equivalent to an empty string
    Returns:
      this, to enable chaining

  - ### replaceAll

    public TextStringBuilder replaceAll(StringMatcher matcher, String replaceStr)
    Replaces all matches within the builder with the replace string.

    Matchers can be used to perform advanced replace behavior. For example you could write a matcher to replace all occurrences where the character 'a' is followed by a number.

    Parameters:
      `matcher` - the matcher to use to find the deletion, null causes no action
      `replaceStr` - the replace string, null is equivalent to an empty string
    Returns:
      this, to enable chaining

  - ### replaceFirst

    public TextStringBuilder replaceFirst(char search, char replace)
    Replaces the first instance of the search character with the replace character in the builder.
    Parameters:
      `search` - the search character
      `replace` - the replace character
    Returns:
      this, to enable chaining

  - ### replaceFirst

    public TextStringBuilder replaceFirst(String searchStr, String replaceStr)
    Replaces the first instance of the search string with the replace string.
    Parameters:
      `searchStr` - the search string, null causes no action to occur
      `replaceStr` - the replace string, null is equivalent to an empty string
    Returns:
      this, to enable chaining

  - ### replaceFirst

    public TextStringBuilder replaceFirst(StringMatcher matcher, String replaceStr)
    Replaces the first match within the builder with the replace string.

    Matchers can be used to perform advanced replace behavior. For example you could write a matcher to replace where the character 'a' is followed by a number.

    Parameters:
      `matcher` - the matcher to use to find the deletion, null causes no action
      `replaceStr` - the replace string, null is equivalent to an empty string
    Returns:
      this, to enable chaining

  - ### reverse

    public TextStringBuilder reverse()
    Reverses the string builder placing each character in the opposite index.
    Returns:
      this, to enable chaining

  - ### rightString

    public String rightString(int length)
    Extracts the rightmost characters from the string builder without throwing an exception.

    This method extracts the right `length` characters from the builder. If this many characters are not available, the whole builder is returned. Thus the returned string may be shorter than the length requested.

    Parameters:
      `length` - the number of characters to extract, negative returns empty string
    Returns:
      The new string

  - ### set

    public TextStringBuilder set(CharSequence str)
    Clears and sets this builder to the given value.
    Parameters:
      `str` - the new value.
    Returns:
      this, to enable chaining
    Since:
      1.9
    See Also:
      - `charAt(int)`
      - `deleteCharAt(int)`

  - ### setCharAt

    public TextStringBuilder setCharAt(int index, char ch)
    Sets the character at the specified index.
    Parameters:
      `index` - the index to set
      `ch` - the new character
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid
    See Also:
      - `charAt(int)`
      - `deleteCharAt(int)`

  - ### setLength

    public TextStringBuilder setLength(int length)
    Updates the length of the builder by either dropping the last characters or adding filler of Unicode zero.
    Parameters:
      `length` - the length to set to, must be zero or positive
    Returns:
      this, to enable chaining
    Throws:
      `IndexOutOfBoundsException` - if the length is negative

  - ### setNewLineText

    public TextStringBuilder setNewLineText(String newLine)
    Sets the text to be appended when `new line` is called.
    Parameters:
      `newLine` - the new line text, `null` means use the system default from `System.lineSeparator()`.
    Returns:
      this instance.

  - ### setNullText

    public TextStringBuilder setNullText(String nullText)
    Sets the text to be appended when null is added.
    Parameters:
      `nullText` - the null text, null means no append
    Returns:
      this, to enable chaining

  - ### size

    public int size()
    Gets the length of the string builder.

    This method is the same as `length()` and is provided to match the API of Collections.

    Returns:
      The length

  - ### startsWith

    public boolean startsWith(String str)
    Checks whether this builder starts with the specified string.

    Note that this method handles null input quietly, unlike String.

    Parameters:
      `str` - the string to search for, null returns false
    Returns:
      true if the builder starts with the string

  - ### subSequence

    public CharSequence subSequence(int startIndex, int endIndex)
    Specified by:
      `subSequence` in interface `CharSequence`

  - ### substring

    public String substring(int start)
    Extracts a portion of this string builder as a string.
    Parameters:
      `start` - the start index, inclusive, must be valid
    Returns:
      The new string
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### substring

    public String substring(int startIndex, int endIndex)
    Extracts a portion of this string builder as a string.

    Note: This method treats an endIndex greater than the length of the builder as equal to the length of the builder, and continues without error, unlike StringBuffer or String.

    Parameters:
      `startIndex` - the start index, inclusive, must be valid
      `endIndex` - the end index, exclusive, must be valid except that if too large it is treated as end of string
    Returns:
      The new string
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### toCharArray

    public char[] toCharArray()
    Copies the builder's character array into a new character array.
    Returns:
      a new array that represents the contents of the builder

  - ### toCharArray

    public char[] toCharArray(int startIndex, int endIndex)
    Copies part of the builder's character array into a new character array.
    Parameters:
      `startIndex` - the start index, inclusive, must be valid
      `endIndex` - the end index, exclusive, must be valid except that if too large it is treated as end of string
    Returns:
      a new array that holds part of the contents of the builder
    Throws:
      `IndexOutOfBoundsException` - if startIndex is invalid, or if endIndex is invalid (but endIndex greater than size is valid)

  - ### toString

    public String toString()
    Gets a String version of the string builder, creating a new instance each time the method is called.

    Note that unlike StringBuffer, the string version returned is independent of the string builder.

    Specified by:
      `toString` in interface `CharSequence`
    Overrides:
      `toString` in class `Object`
    Returns:
      The builder as a String

  - ### toStringBuffer

    public StringBuffer toStringBuffer()
    Gets a StringBuffer version of the string builder, creating a new instance each time the method is called.
    Returns:
      The builder as a StringBuffer

  - ### toStringBuilder

    public StringBuilder toStringBuilder()
    Gets a StringBuilder version of the string builder, creating a new instance each time the method is called.
    Returns:
      The builder as a StringBuilder

  - ### trim

    public TextStringBuilder trim()
    Trims the builder by removing characters less than or equal to a space from the beginning and end.
    Returns:
      this, to enable chaining

  - ### validateIndex

    protected void validateIndex(int index)
    Validates that an index is in the range `0 <= index <= size`.
    Parameters:
      `index` - the index to test.
    Throws:
      `IndexOutOfBoundsException` - Thrown when the index is not the range `0 <= index <= size`.

  - ### validateRange

    protected int validateRange(int startIndex, int endIndex)
    Validates parameters defining a range of the builder.
    Parameters:
      `startIndex` - the start index, inclusive, must be valid
      `endIndex` - the end index, exclusive, must be valid except that if too large it is treated as end of string
    Returns:
      A valid end index.
    Throws:
      `StringIndexOutOfBoundsException` - if the index is invalid