You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2018/02/12 18:13:53 UTC
[3/4] [text] [TEXT-115] Add a StrBuilder replacement based on the
StringMatcher interface: TextStringBuilder.
http://git-wip-us.apache.org/repos/asf/commons-text/blob/978e2896/src/main/java/org/apache/commons/text/TextStringBuilder.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/text/TextStringBuilder.java b/src/main/java/org/apache/commons/text/TextStringBuilder.java
new file mode 100644
index 0000000..8ab9322
--- /dev/null
+++ b/src/main/java/org/apache/commons/text/TextStringBuilder.java
@@ -0,0 +1,3216 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.text;
+
+import java.io.IOException;
+import java.io.Reader;
+import java.io.Serializable;
+import java.io.Writer;
+import java.nio.CharBuffer;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Objects;
+
+import org.apache.commons.text.matcher.StringMatcher;
+
+/**
+ * Builds a string from constituent parts providing a more flexible and powerful API than StringBuffer.
+ * <p>
+ * The main differences from StringBuffer/StringBuilder are:
+ * </p>
+ * <ul>
+ * <li>Not synchronized</li>
+ * <li>Not final</li>
+ * <li>Subclasses have direct access to character array</li>
+ * <li>Additional methods
+ * <ul>
+ * <li>appendWithSeparators - adds an array of values, with a separator</li>
+ * <li>appendPadding - adds a length padding characters</li>
+ * <li>appendFixedLength - adds a fixed width field to the builder</li>
+ * <li>toCharArray/getChars - simpler ways to get a range of the character array</li>
+ * <li>delete - delete char or string</li>
+ * <li>replace - search and replace for a char or string</li>
+ * <li>leftString/rightString/midString - substring without exceptions</li>
+ * <li>contains - whether the builder contains a char or string</li>
+ * <li>size/clear/isEmpty - collections style API methods</li>
+ * </ul>
+ * </li>
+ * <li>Views
+ * <ul>
+ * <li>asTokenizer - uses the internal buffer as the source of a StrTokenizer</li>
+ * <li>asReader - uses the internal buffer as the source of a Reader</li>
+ * <li>asWriter - allows a Writer to write directly to the internal buffer</li>
+ * </ul>
+ * </li>
+ * </ul>
+ * <p>
+ * 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, {@link #setNullText(String)}.
+ * </p>
+ * <p>
+ * This class is called {@code TextStringBuilder} instead of {@code StringBuilder} to avoid clashing with
+ * {@link java.lang.StringBuilder}.
+ * </p>
+ *
+ * @since 1.3
+ */
+public class TextStringBuilder implements CharSequence, Appendable, Serializable, Builder<String> {
+
+ /**
+ * The size of the string {@code "false"}.
+ */
+ private static final int FALSE_STRING_SIZE = "false".length();
+
+ /**
+ * The size of the string {@code "true"}.
+ */
+ private static final int TRUE_STRING_SIZE = "true".length();
+
+ /**
+ * The extra capacity for new builders.
+ */
+ static final int CAPACITY = 32;
+
+ /**
+ * Required for serialization support.
+ *
+ * @see java.io.Serializable
+ */
+ private static final long serialVersionUID = 1L;
+
+ /** Internal data storage. */
+ char[] buffer; // package-protected for test code use only
+ /** Current size of the buffer. */
+ private int size;
+ /** The new line. */
+ private String newLine;
+ /** The null text. */
+ private String nullText;
+
+ // -----------------------------------------------------------------------
+ /**
+ * Constructor that creates an empty builder initial capacity 32 characters.
+ */
+ public TextStringBuilder() {
+ this(CAPACITY);
+ }
+
+ /**
+ * Constructor that creates an empty builder the specified initial capacity.
+ *
+ * @param initialCapacity
+ * the initial capacity, zero or less will be converted to 32
+ */
+ public TextStringBuilder(int initialCapacity) {
+ super();
+ if (initialCapacity <= 0) {
+ initialCapacity = CAPACITY;
+ }
+ buffer = new char[initialCapacity];
+ }
+
+ /**
+ * Constructor that creates a builder from the string, allocating 32 extra characters for growth.
+ *
+ * @param str
+ * the string to copy, null treated as blank string
+ */
+ public TextStringBuilder(final String str) {
+ super();
+ if (str == null) {
+ buffer = new char[CAPACITY];
+ } else {
+ buffer = new char[str.length() + CAPACITY];
+ append(str);
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Gets the text to be appended when a new line is added.
+ *
+ * @return the new line text, null means use system default
+ */
+ public String getNewLineText() {
+ return newLine;
+ }
+
+ /**
+ * Sets the text to be appended when a new line is added.
+ *
+ * @param newLine
+ * the new line text, null means use system default
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder setNewLineText(final String newLine) {
+ this.newLine = newLine;
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Gets the text to be appended when null is added.
+ *
+ * @return the null text, null means no append
+ */
+ public String getNullText() {
+ return nullText;
+ }
+
+ /**
+ * Sets the text to be appended when null is added.
+ *
+ * @param nullText
+ * the null text, null means no append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder setNullText(String nullText) {
+ if (nullText != null && nullText.isEmpty()) {
+ nullText = null;
+ }
+ this.nullText = nullText;
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Gets the length of the string builder.
+ *
+ * @return the length
+ */
+ @Override
+ public int length() {
+ return size;
+ }
+
+ /**
+ * Updates the length of the builder by either dropping the last characters or adding filler of Unicode zero.
+ *
+ * @param length
+ * the length to set to, must be zero or positive
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the length is negative
+ */
+ public TextStringBuilder setLength(final int length) {
+ if (length < 0) {
+ throw new StringIndexOutOfBoundsException(length);
+ }
+ if (length < size) {
+ size = length;
+ } else if (length > size) {
+ ensureCapacity(length);
+ final int oldEnd = size;
+ final int newEnd = length;
+ size = length;
+ for (int i = oldEnd; i < newEnd; i++) {
+ buffer[i] = '\0';
+ }
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Gets the current size of the internal character array buffer.
+ *
+ * @return the capacity
+ */
+ public int capacity() {
+ return buffer.length;
+ }
+
+ /**
+ * Checks the capacity and ensures that it is at least the size specified.
+ *
+ * @param capacity
+ * the capacity to ensure
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder ensureCapacity(final int capacity) {
+ if (capacity > buffer.length) {
+ final char[] old = buffer;
+ buffer = new char[capacity * 2];
+ System.arraycopy(old, 0, buffer, 0, size);
+ }
+ return this;
+ }
+
+ /**
+ * Minimizes the capacity to the actual length of the string.
+ *
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder minimizeCapacity() {
+ if (buffer.length > length()) {
+ final char[] old = buffer;
+ buffer = new char[length()];
+ System.arraycopy(old, 0, buffer, 0, size);
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Gets the length of the string builder.
+ * <p>
+ * This method is the same as {@link #length()} and is provided to match the API of Collections.
+ *
+ * @return the length
+ */
+ public int size() {
+ return size;
+ }
+
+ /**
+ * Checks is the string builder is empty (convenience Collections API style method).
+ * <p>
+ * This method is the same as checking {@link #length()} and is provided to match the API of Collections.
+ *
+ * @return <code>true</code> if the size is <code>0</code>.
+ */
+ public boolean isEmpty() {
+ return size == 0;
+ }
+
+ /**
+ * Clears the string builder (convenience Collections API style method).
+ * <p>
+ * This method does not reduce the size of the internal character buffer. To do that, call <code>clear()</code>
+ * followed by {@link #minimizeCapacity()}.
+ * <p>
+ * This method is the same as {@link #setLength(int)} called with zero and is provided to match the API of
+ * Collections.
+ *
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder clear() {
+ size = 0;
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Gets the character at the specified index.
+ *
+ * @see #setCharAt(int, char)
+ * @see #deleteCharAt(int)
+ * @param index
+ * the index to retrieve, must be valid
+ * @return the character at the index
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ @Override
+ public char charAt(final int index) {
+ if (index < 0 || index >= length()) {
+ throw new StringIndexOutOfBoundsException(index);
+ }
+ return buffer[index];
+ }
+
+ /**
+ * Sets the character at the specified index.
+ *
+ * @see #charAt(int)
+ * @see #deleteCharAt(int)
+ * @param index
+ * the index to set
+ * @param ch
+ * the new character
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public TextStringBuilder setCharAt(final int index, final char ch) {
+ if (index < 0 || index >= length()) {
+ throw new StringIndexOutOfBoundsException(index);
+ }
+ buffer[index] = ch;
+ return this;
+ }
+
+ /**
+ * Deletes the character at the specified index.
+ *
+ * @see #charAt(int)
+ * @see #setCharAt(int, char)
+ * @param index
+ * the index to delete
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public TextStringBuilder deleteCharAt(final int index) {
+ if (index < 0 || index >= size) {
+ throw new StringIndexOutOfBoundsException(index);
+ }
+ deleteImpl(index, index + 1, 1);
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Copies the builder's character array into a new character array.
+ *
+ * @return a new array that represents the contents of the builder
+ */
+ public char[] toCharArray() {
+ if (size == 0) {
+ return new char[0];
+ }
+ final char[] chars = new char[size];
+ System.arraycopy(buffer, 0, chars, 0, size);
+ return chars;
+ }
+
+ /**
+ * Copies part of the builder's character array into a new character array.
+ *
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param endIndex
+ * the end index, exclusive, must be valid except that if too large it is treated as end of string
+ * @return 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)
+ */
+ public char[] toCharArray(final int startIndex, int endIndex) {
+ endIndex = validateRange(startIndex, endIndex);
+ final int len = endIndex - startIndex;
+ if (len == 0) {
+ return new char[0];
+ }
+ final char[] chars = new char[len];
+ System.arraycopy(buffer, startIndex, chars, 0, len);
+ return chars;
+ }
+
+ /**
+ * Copies the character array into the specified array.
+ *
+ * @param destination
+ * the destination array, null will cause an array to be created
+ * @return the input array, unless that was null or too small
+ */
+ public char[] getChars(char[] destination) {
+ final int len = length();
+ if (destination == null || destination.length < len) {
+ destination = new char[len];
+ }
+ System.arraycopy(buffer, 0, destination, 0, len);
+ return destination;
+ }
+
+ /**
+ * Copies the character array into the specified array.
+ *
+ * @param startIndex
+ * first index to copy, inclusive, must be valid
+ * @param endIndex
+ * last index, exclusive, must be valid
+ * @param destination
+ * the destination array, must not be null or too small
+ * @param destinationIndex
+ * the index to start copying in destination
+ * @throws NullPointerException
+ * if the array is null
+ * @throws IndexOutOfBoundsException
+ * if any index is invalid
+ */
+ public void getChars(final int startIndex, final int endIndex, final char[] destination,
+ final int destinationIndex) {
+ if (startIndex < 0) {
+ throw new StringIndexOutOfBoundsException(startIndex);
+ }
+ if (endIndex < 0 || endIndex > length()) {
+ throw new StringIndexOutOfBoundsException(endIndex);
+ }
+ if (startIndex > endIndex) {
+ throw new StringIndexOutOfBoundsException("end < start");
+ }
+ System.arraycopy(buffer, startIndex, destination, destinationIndex, endIndex - startIndex);
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * If possible, reads chars from the provided {@link Readable} directly into underlying character buffer without
+ * making extra copies.
+ *
+ * @param readable
+ * object to read from
+ * @return the number of characters read
+ * @throws IOException
+ * if an I/O error occurs
+ *
+ * @see #appendTo(Appendable)
+ */
+ public int readFrom(final Readable readable) throws IOException {
+ final int oldSize = size;
+ if (readable instanceof Reader) {
+ final Reader r = (Reader) readable;
+ ensureCapacity(size + 1);
+ int read;
+ while ((read = r.read(buffer, size, buffer.length - size)) != -1) {
+ size += read;
+ ensureCapacity(size + 1);
+ }
+ } else if (readable instanceof CharBuffer) {
+ final CharBuffer cb = (CharBuffer) readable;
+ final int remaining = cb.remaining();
+ ensureCapacity(size + remaining);
+ cb.get(buffer, size, remaining);
+ size += remaining;
+ } else {
+ while (true) {
+ ensureCapacity(size + 1);
+ final CharBuffer buf = CharBuffer.wrap(buffer, size, buffer.length - size);
+ final int read = readable.read(buf);
+ if (read == -1) {
+ break;
+ }
+ size += read;
+ }
+ }
+ return size - oldSize;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Appends the new line string to this string builder.
+ * <p>
+ * The new line string can be altered using {@link #setNewLineText(String)}. This might be used to force the output
+ * to always use Unix line endings even when on Windows.
+ *
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendNewLine() {
+ if (newLine == null) {
+ append(System.lineSeparator());
+ return this;
+ }
+ return append(newLine);
+ }
+
+ /**
+ * Appends the text representing <code>null</code> to this string builder.
+ *
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendNull() {
+ if (nullText == null) {
+ return this;
+ }
+ return append(nullText);
+ }
+
+ /**
+ * Appends an object to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param obj
+ * the object to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final Object obj) {
+ if (obj == null) {
+ return appendNull();
+ }
+ if (obj instanceof CharSequence) {
+ return append((CharSequence) obj);
+ }
+ return append(obj.toString());
+ }
+
+ /**
+ * Appends a CharSequence to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param seq
+ * the CharSequence to append
+ * @return this, to enable chaining
+ */
+ @Override
+ public TextStringBuilder append(final CharSequence seq) {
+ if (seq == null) {
+ return appendNull();
+ }
+ if (seq instanceof TextStringBuilder) {
+ return append((TextStringBuilder) seq);
+ }
+ if (seq instanceof StringBuilder) {
+ return append((StringBuilder) seq);
+ }
+ if (seq instanceof StringBuffer) {
+ return append((StringBuffer) seq);
+ }
+ if (seq instanceof CharBuffer) {
+ return append((CharBuffer) seq);
+ }
+ return append(seq.toString());
+ }
+
+ /**
+ * Appends part of a CharSequence to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param seq
+ * the CharSequence to append
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param length
+ * the length to append, must be valid
+ * @return this, to enable chaining
+ */
+ @Override
+ public TextStringBuilder append(final CharSequence seq, final int startIndex, final int length) {
+ if (seq == null) {
+ return appendNull();
+ }
+ return append(seq.toString(), startIndex, length);
+ }
+
+ /**
+ * Appends a string to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param str
+ * the string to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final String str) {
+ if (str == null) {
+ return appendNull();
+ }
+ final int strLen = str.length();
+ if (strLen > 0) {
+ final int len = length();
+ ensureCapacity(len + strLen);
+ str.getChars(0, strLen, buffer, len);
+ size += strLen;
+ }
+ return this;
+ }
+
+ /**
+ * Appends part of a string to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param str
+ * the string to append
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param length
+ * the length to append, must be valid
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final String str, final int startIndex, final int length) {
+ if (str == null) {
+ return appendNull();
+ }
+ if (startIndex < 0 || startIndex > str.length()) {
+ throw new StringIndexOutOfBoundsException("startIndex must be valid");
+ }
+ if (length < 0 || (startIndex + length) > str.length()) {
+ throw new StringIndexOutOfBoundsException("length must be valid");
+ }
+ if (length > 0) {
+ final int len = length();
+ ensureCapacity(len + length);
+ str.getChars(startIndex, startIndex + length, buffer, len);
+ size += length;
+ }
+ return this;
+ }
+
+ /**
+ * Calls {@link String#format(String, Object...)} and appends the result.
+ *
+ * @param format
+ * the format string
+ * @param objs
+ * the objects to use in the format string
+ * @return {@code this} to enable chaining
+ * @see String#format(String, Object...)
+ */
+ public TextStringBuilder append(final String format, final Object... objs) {
+ return append(String.format(format, objs));
+ }
+
+ /**
+ * Appends the contents of a char buffer to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param buf
+ * the char buffer to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final CharBuffer buf) {
+ if (buf == null) {
+ return appendNull();
+ }
+ if (buf.hasArray()) {
+ final int length = buf.remaining();
+ final int len = length();
+ ensureCapacity(len + length);
+ System.arraycopy(buf.array(), buf.arrayOffset() + buf.position(), buffer, len, length);
+ size += length;
+ } else {
+ append(buf.toString());
+ }
+ return this;
+ }
+
+ /**
+ * Appends the contents of a char buffer to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param buf
+ * the char buffer to append
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param length
+ * the length to append, must be valid
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final CharBuffer buf, final int startIndex, final int length) {
+ if (buf == null) {
+ return appendNull();
+ }
+ if (buf.hasArray()) {
+ final int totalLength = buf.remaining();
+ if (startIndex < 0 || startIndex > totalLength) {
+ throw new StringIndexOutOfBoundsException("startIndex must be valid");
+ }
+ if (length < 0 || (startIndex + length) > totalLength) {
+ throw new StringIndexOutOfBoundsException("length must be valid");
+ }
+ final int len = length();
+ ensureCapacity(len + length);
+ System.arraycopy(buf.array(), buf.arrayOffset() + buf.position() + startIndex, buffer, len, length);
+ size += length;
+ } else {
+ append(buf.toString(), startIndex, length);
+ }
+ return this;
+ }
+
+ /**
+ * Appends a string buffer to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param str
+ * the string buffer to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final StringBuffer str) {
+ if (str == null) {
+ return appendNull();
+ }
+ final int strLen = str.length();
+ if (strLen > 0) {
+ final int len = length();
+ ensureCapacity(len + strLen);
+ str.getChars(0, strLen, buffer, len);
+ size += strLen;
+ }
+ return this;
+ }
+
+ /**
+ * Appends part of a string buffer to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param str
+ * the string to append
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param length
+ * the length to append, must be valid
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final StringBuffer str, final int startIndex, final int length) {
+ if (str == null) {
+ return appendNull();
+ }
+ if (startIndex < 0 || startIndex > str.length()) {
+ throw new StringIndexOutOfBoundsException("startIndex must be valid");
+ }
+ if (length < 0 || (startIndex + length) > str.length()) {
+ throw new StringIndexOutOfBoundsException("length must be valid");
+ }
+ if (length > 0) {
+ final int len = length();
+ ensureCapacity(len + length);
+ str.getChars(startIndex, startIndex + length, buffer, len);
+ size += length;
+ }
+ return this;
+ }
+
+ /**
+ * Appends a StringBuilder to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param str
+ * the StringBuilder to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final StringBuilder str) {
+ if (str == null) {
+ return appendNull();
+ }
+ final int strLen = str.length();
+ if (strLen > 0) {
+ final int len = length();
+ ensureCapacity(len + strLen);
+ str.getChars(0, strLen, buffer, len);
+ size += strLen;
+ }
+ return this;
+ }
+
+ /**
+ * Appends part of a StringBuilder to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param str
+ * the StringBuilder to append
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param length
+ * the length to append, must be valid
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final StringBuilder str, final int startIndex, final int length) {
+ if (str == null) {
+ return appendNull();
+ }
+ if (startIndex < 0 || startIndex > str.length()) {
+ throw new StringIndexOutOfBoundsException("startIndex must be valid");
+ }
+ if (length < 0 || (startIndex + length) > str.length()) {
+ throw new StringIndexOutOfBoundsException("length must be valid");
+ }
+ if (length > 0) {
+ final int len = length();
+ ensureCapacity(len + length);
+ str.getChars(startIndex, startIndex + length, buffer, len);
+ size += length;
+ }
+ return this;
+ }
+
+ /**
+ * Appends another string builder to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param str
+ * the string builder to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final TextStringBuilder str) {
+ if (str == null) {
+ return appendNull();
+ }
+ final int strLen = str.length();
+ if (strLen > 0) {
+ final int len = length();
+ ensureCapacity(len + strLen);
+ System.arraycopy(str.buffer, 0, buffer, len, strLen);
+ size += strLen;
+ }
+ return this;
+ }
+
+ /**
+ * Appends part of a string builder to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param str
+ * the string to append
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param length
+ * the length to append, must be valid
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final TextStringBuilder str, final int startIndex, final int length) {
+ if (str == null) {
+ return appendNull();
+ }
+ if (startIndex < 0 || startIndex > str.length()) {
+ throw new StringIndexOutOfBoundsException("startIndex must be valid");
+ }
+ if (length < 0 || (startIndex + length) > str.length()) {
+ throw new StringIndexOutOfBoundsException("length must be valid");
+ }
+ if (length > 0) {
+ final int len = length();
+ ensureCapacity(len + length);
+ str.getChars(startIndex, startIndex + length, buffer, len);
+ size += length;
+ }
+ return this;
+ }
+
+ /**
+ * Appends a char array to the string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param chars
+ * the char array to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final char[] chars) {
+ if (chars == null) {
+ return appendNull();
+ }
+ final int strLen = chars.length;
+ if (strLen > 0) {
+ final int len = length();
+ ensureCapacity(len + strLen);
+ System.arraycopy(chars, 0, buffer, len, strLen);
+ size += strLen;
+ }
+ return this;
+ }
+
+ /**
+ * Appends a char array to the string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param chars
+ * the char array to append
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param length
+ * the length to append, must be valid
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final char[] chars, final int startIndex, final int length) {
+ if (chars == null) {
+ return appendNull();
+ }
+ if (startIndex < 0 || startIndex > chars.length) {
+ throw new StringIndexOutOfBoundsException("Invalid startIndex: " + length);
+ }
+ if (length < 0 || (startIndex + length) > chars.length) {
+ throw new StringIndexOutOfBoundsException("Invalid length: " + length);
+ }
+ if (length > 0) {
+ final int len = length();
+ ensureCapacity(len + length);
+ System.arraycopy(chars, startIndex, buffer, len, length);
+ size += length;
+ }
+ return this;
+ }
+
+ /**
+ * Appends a boolean value to the string builder.
+ *
+ * @param value
+ * the value to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final boolean value) {
+ if (value) {
+ ensureCapacity(size + TRUE_STRING_SIZE);
+ buffer[size++] = 't';
+ buffer[size++] = 'r';
+ buffer[size++] = 'u';
+ buffer[size++] = 'e';
+ } else {
+ ensureCapacity(size + FALSE_STRING_SIZE);
+ buffer[size++] = 'f';
+ buffer[size++] = 'a';
+ buffer[size++] = 'l';
+ buffer[size++] = 's';
+ buffer[size++] = 'e';
+ }
+ return this;
+ }
+
+ /**
+ * Appends a char value to the string builder.
+ *
+ * @param ch
+ * the value to append
+ * @return this, to enable chaining
+ */
+ @Override
+ public TextStringBuilder append(final char ch) {
+ final int len = length();
+ ensureCapacity(len + 1);
+ buffer[size++] = ch;
+ return this;
+ }
+
+ /**
+ * Appends an int value to the string builder using <code>String.valueOf</code>.
+ *
+ * @param value
+ * the value to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final int value) {
+ return append(String.valueOf(value));
+ }
+
+ /**
+ * Appends a long value to the string builder using <code>String.valueOf</code>.
+ *
+ * @param value
+ * the value to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final long value) {
+ return append(String.valueOf(value));
+ }
+
+ /**
+ * Appends a float value to the string builder using <code>String.valueOf</code>.
+ *
+ * @param value
+ * the value to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final float value) {
+ return append(String.valueOf(value));
+ }
+
+ /**
+ * Appends a double value to the string builder using <code>String.valueOf</code>.
+ *
+ * @param value
+ * the value to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder append(final double value) {
+ return append(String.valueOf(value));
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Appends an object followed by a new line to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param obj
+ * the object to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final Object obj) {
+ return append(obj).appendNewLine();
+ }
+
+ /**
+ * Appends a string followed by a new line to this string builder. Appending null will call {@link #appendNull()}.
+ *
+ * @param str
+ * the string to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final String str) {
+ return append(str).appendNewLine();
+ }
+
+ /**
+ * Appends part of a string followed by a new line to this string builder. Appending null will call
+ * {@link #appendNull()}.
+ *
+ * @param str
+ * the string to append
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param length
+ * the length to append, must be valid
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final String str, final int startIndex, final int length) {
+ return append(str, startIndex, length).appendNewLine();
+ }
+
+ /**
+ * Calls {@link String#format(String, Object...)} and appends the result.
+ *
+ * @param format
+ * the format string
+ * @param objs
+ * the objects to use in the format string
+ * @return {@code this} to enable chaining
+ * @see String#format(String, Object...)
+ */
+ public TextStringBuilder appendln(final String format, final Object... objs) {
+ return append(format, objs).appendNewLine();
+ }
+
+ /**
+ * Appends a string buffer followed by a new line to this string builder. Appending null will call
+ * {@link #appendNull()}.
+ *
+ * @param str
+ * the string buffer to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final StringBuffer str) {
+ return append(str).appendNewLine();
+ }
+
+ /**
+ * Appends a string builder followed by a new line to this string builder. Appending null will call
+ * {@link #appendNull()}.
+ *
+ * @param str
+ * the string builder to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final StringBuilder str) {
+ return append(str).appendNewLine();
+ }
+
+ /**
+ * Appends part of a string builder followed by a new line to this string builder. Appending null will call
+ * {@link #appendNull()}.
+ *
+ * @param str
+ * the string builder to append
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param length
+ * the length to append, must be valid
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final StringBuilder str, final int startIndex, final int length) {
+ return append(str, startIndex, length).appendNewLine();
+ }
+
+ /**
+ * Appends part of a string buffer followed by a new line to this string builder. Appending null will call
+ * {@link #appendNull()}.
+ *
+ * @param str
+ * the string to append
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param length
+ * the length to append, must be valid
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final StringBuffer str, final int startIndex, final int length) {
+ return append(str, startIndex, length).appendNewLine();
+ }
+
+ /**
+ * Appends another string builder followed by a new line to this string builder. Appending null will call
+ * {@link #appendNull()}.
+ *
+ * @param str
+ * the string builder to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final TextStringBuilder str) {
+ return append(str).appendNewLine();
+ }
+
+ /**
+ * Appends part of a string builder followed by a new line to this string builder. Appending null will call
+ * {@link #appendNull()}.
+ *
+ * @param str
+ * the string to append
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param length
+ * the length to append, must be valid
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final TextStringBuilder str, final int startIndex, final int length) {
+ return append(str, startIndex, length).appendNewLine();
+ }
+
+ /**
+ * Appends a char array followed by a new line to the string builder. Appending null will call
+ * {@link #appendNull()}.
+ *
+ * @param chars
+ * the char array to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final char[] chars) {
+ return append(chars).appendNewLine();
+ }
+
+ /**
+ * Appends a char array followed by a new line to the string builder. Appending null will call
+ * {@link #appendNull()}.
+ *
+ * @param chars
+ * the char array to append
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param length
+ * the length to append, must be valid
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final char[] chars, final int startIndex, final int length) {
+ return append(chars, startIndex, length).appendNewLine();
+ }
+
+ /**
+ * Appends a boolean value followed by a new line to the string builder.
+ *
+ * @param value
+ * the value to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final boolean value) {
+ return append(value).appendNewLine();
+ }
+
+ /**
+ * Appends a char value followed by a new line to the string builder.
+ *
+ * @param ch
+ * the value to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final char ch) {
+ return append(ch).appendNewLine();
+ }
+
+ /**
+ * Appends an int value followed by a new line to the string builder using <code>String.valueOf</code>.
+ *
+ * @param value
+ * the value to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final int value) {
+ return append(value).appendNewLine();
+ }
+
+ /**
+ * Appends a long value followed by a new line to the string builder using <code>String.valueOf</code>.
+ *
+ * @param value
+ * the value to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final long value) {
+ return append(value).appendNewLine();
+ }
+
+ /**
+ * Appends a float value followed by a new line to the string builder using <code>String.valueOf</code>.
+ *
+ * @param value
+ * the value to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final float value) {
+ return append(value).appendNewLine();
+ }
+
+ /**
+ * Appends a double value followed by a new line to the string builder using <code>String.valueOf</code>.
+ *
+ * @param value
+ * the value to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendln(final double value) {
+ return append(value).appendNewLine();
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * 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 {@link #append(Object)}.
+ *
+ * @param <T>
+ * the element type
+ * @param array
+ * the array to append
+ * @return this, to enable chaining
+ */
+ public <T> TextStringBuilder appendAll(@SuppressWarnings("unchecked") final T... array) {
+ /*
+ * @SuppressWarnings used to hide warning about vararg usage. We cannot use @SafeVarargs, since this method is
+ * not final. Using @SuppressWarnings is fine, because it isn't inherited by subclasses, so each subclass must
+ * vouch for itself whether its use of 'array' is safe.
+ */
+ if (array != null && array.length > 0) {
+ for (final Object element : array) {
+ append(element);
+ }
+ }
+ return this;
+ }
+
+ /**
+ * 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 {@link #append(Object)}.
+ *
+ * @param iterable
+ * the iterable to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendAll(final Iterable<?> iterable) {
+ if (iterable != null) {
+ for (final Object o : iterable) {
+ append(o);
+ }
+ }
+ return this;
+ }
+
+ /**
+ * 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 {@link #append(Object)}.
+ *
+ * @param it
+ * the iterator to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendAll(final Iterator<?> it) {
+ if (it != null) {
+ while (it.hasNext()) {
+ append(it.next());
+ }
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * 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 {@link #append(Object)}.
+ *
+ * @param array
+ * the array to append
+ * @param separator
+ * the separator to use, null means no separator
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendWithSeparators(final Object[] array, final String separator) {
+ if (array != null && array.length > 0) {
+ final String sep = Objects.toString(separator, "");
+ append(array[0]);
+ for (int i = 1; i < array.length; i++) {
+ append(sep);
+ append(array[i]);
+ }
+ }
+ return this;
+ }
+
+ /**
+ * 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 {@link #append(Object)}.
+ *
+ * @param iterable
+ * the iterable to append
+ * @param separator
+ * the separator to use, null means no separator
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendWithSeparators(final Iterable<?> iterable, final String separator) {
+ if (iterable != null) {
+ final String sep = Objects.toString(separator, "");
+ final Iterator<?> it = iterable.iterator();
+ while (it.hasNext()) {
+ append(it.next());
+ if (it.hasNext()) {
+ append(sep);
+ }
+ }
+ }
+ return this;
+ }
+
+ /**
+ * 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 {@link #append(Object)}.
+ *
+ * @param it
+ * the iterator to append
+ * @param separator
+ * the separator to use, null means no separator
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendWithSeparators(final Iterator<?> it, final String separator) {
+ if (it != null) {
+ final String sep = Objects.toString(separator, "");
+ while (it.hasNext()) {
+ append(it.next());
+ if (it.hasNext()) {
+ append(sep);
+ }
+ }
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Appends a separator if the builder is currently non-empty. Appending a null separator will have no effect. The
+ * separator is appended using {@link #append(String)}.
+ * <p>
+ * This method is useful for adding a separator each time around the loop except the first.
+ *
+ * <pre>
+ * for (Iterator it = list.iterator(); it.hasNext();) {
+ * appendSeparator(",");
+ * append(it.next());
+ * }
+ * </pre>
+ *
+ * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}.
+ *
+ * @param separator
+ * the separator to use, null means no separator
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendSeparator(final String separator) {
+ return appendSeparator(separator, null);
+ }
+
+ /**
+ * 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 {@link #append(String)}.
+ * <p>
+ * This method is for example useful for constructing queries
+ *
+ * <pre>
+ * 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)
+ * </pre>
+ *
+ * @param standard
+ * the separator if builder is not empty, null means no separator
+ * @param defaultIfEmpty
+ * the separator if builder is empty, null means no separator
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendSeparator(final String standard, final String defaultIfEmpty) {
+ final String str = isEmpty() ? defaultIfEmpty : standard;
+ if (str != null) {
+ append(str);
+ }
+ return this;
+ }
+
+ /**
+ * Appends a separator if the builder is currently non-empty. The separator is appended using {@link #append(char)}.
+ * <p>
+ * This method is useful for adding a separator each time around the loop except the first.
+ *
+ * <pre>
+ * for (Iterator it = list.iterator(); it.hasNext();) {
+ * appendSeparator(',');
+ * append(it.next());
+ * }
+ * </pre>
+ *
+ * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}.
+ *
+ * @param separator
+ * the separator to use
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendSeparator(final char separator) {
+ if (size() > 0) {
+ append(separator);
+ }
+ return this;
+ }
+
+ /**
+ * Append 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 {@link #append(char)}.
+ *
+ * @param standard
+ * the separator if builder is not empty
+ * @param defaultIfEmpty
+ * the separator if builder is empty
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendSeparator(final char standard, final char defaultIfEmpty) {
+ if (size() > 0) {
+ append(standard);
+ } else {
+ append(defaultIfEmpty);
+ }
+ return this;
+ }
+
+ /**
+ * 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 {@link #append(String)}.
+ * <p>
+ * This method is useful for adding a separator each time around the loop except the first.
+ * </p>
+ *
+ * <pre>
+ * for (int i = 0; i < list.size(); i++) {
+ * appendSeparator(",", i);
+ * append(list.get(i));
+ * }
+ * </pre>
+ *
+ * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}.
+ *
+ * @param separator
+ * the separator to use, null means no separator
+ * @param loopIndex
+ * the loop index
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendSeparator(final String separator, final int loopIndex) {
+ if (separator != null && loopIndex > 0) {
+ append(separator);
+ }
+ return this;
+ }
+
+ /**
+ * Appends a separator to the builder if the loop index is greater than zero. The separator is appended using
+ * {@link #append(char)}.
+ * <p>
+ * This method is useful for adding a separator each time around the loop except the first.
+ * </p>
+ *
+ * <pre>
+ * for (int i = 0; i < list.size(); i++) {
+ * appendSeparator(",", i);
+ * append(list.get(i));
+ * }
+ * </pre>
+ *
+ * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}.
+ *
+ * @param separator
+ * the separator to use
+ * @param loopIndex
+ * the loop index
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendSeparator(final char separator, final int loopIndex) {
+ if (loopIndex > 0) {
+ append(separator);
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Appends the pad character to the builder the specified number of times.
+ *
+ * @param length
+ * the length to append, negative means no append
+ * @param padChar
+ * the character to append
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendPadding(final int length, final char padChar) {
+ if (length >= 0) {
+ ensureCapacity(size + length);
+ for (int i = 0; i < length; i++) {
+ buffer[size++] = padChar;
+ }
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Appends an object to the builder padding on the left to a fixed width. The <code>toString</code> 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.
+ *
+ * @param obj
+ * the object to append, null uses null text
+ * @param width
+ * the fixed field width, zero or negative has no effect
+ * @param padChar
+ * the pad character to use
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendFixedWidthPadLeft(final Object obj, final int width, final char padChar) {
+ if (width > 0) {
+ ensureCapacity(size + width);
+ String str = (obj == null ? getNullText() : obj.toString());
+ if (str == null) {
+ str = "";
+ }
+ final int strLen = str.length();
+ if (strLen >= width) {
+ str.getChars(strLen - width, strLen, buffer, size);
+ } else {
+ final int padLen = width - strLen;
+ for (int i = 0; i < padLen; i++) {
+ buffer[size + i] = padChar;
+ }
+ str.getChars(0, strLen, buffer, size + padLen);
+ }
+ size += width;
+ }
+ return this;
+ }
+
+ /**
+ * Appends an object to the builder padding on the left to a fixed width. The <code>String.valueOf</code> of the
+ * <code>int</code> value is used. If the formatted value is larger than the length, the left hand side is lost.
+ *
+ * @param value
+ * the value to append
+ * @param width
+ * the fixed field width, zero or negative has no effect
+ * @param padChar
+ * the pad character to use
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendFixedWidthPadLeft(final int value, final int width, final char padChar) {
+ return appendFixedWidthPadLeft(String.valueOf(value), width, padChar);
+ }
+
+ /**
+ * Appends an object to the builder padding on the right to a fixed length. The <code>toString</code> 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.
+ *
+ * @param obj
+ * the object to append, null uses null text
+ * @param width
+ * the fixed field width, zero or negative has no effect
+ * @param padChar
+ * the pad character to use
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendFixedWidthPadRight(final Object obj, final int width, final char padChar) {
+ if (width > 0) {
+ ensureCapacity(size + width);
+ String str = (obj == null ? getNullText() : obj.toString());
+ if (str == null) {
+ str = "";
+ }
+ final int strLen = str.length();
+ if (strLen >= width) {
+ str.getChars(0, width, buffer, size);
+ } else {
+ final int padLen = width - strLen;
+ str.getChars(0, strLen, buffer, size);
+ for (int i = 0; i < padLen; i++) {
+ buffer[size + strLen + i] = padChar;
+ }
+ }
+ size += width;
+ }
+ return this;
+ }
+
+ /**
+ * Appends an object to the builder padding on the right to a fixed length. The <code>String.valueOf</code> of the
+ * <code>int</code> value is used. If the object is larger than the length, the right hand side is lost.
+ *
+ * @param value
+ * the value to append
+ * @param width
+ * the fixed field width, zero or negative has no effect
+ * @param padChar
+ * the pad character to use
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder appendFixedWidthPadRight(final int value, final int width, final char padChar) {
+ return appendFixedWidthPadRight(String.valueOf(value), width, padChar);
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Inserts the string representation of an object into this builder. Inserting null will use the stored null text
+ * value.
+ *
+ * @param index
+ * the index to add at, must be valid
+ * @param obj
+ * the object to insert
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public TextStringBuilder insert(final int index, final Object obj) {
+ if (obj == null) {
+ return insert(index, nullText);
+ }
+ return insert(index, obj.toString());
+ }
+
+ /**
+ * Inserts the string into this builder. Inserting null will use the stored null text value.
+ *
+ * @param index
+ * the index to add at, must be valid
+ * @param str
+ * the string to insert
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public TextStringBuilder insert(final int index, String str) {
+ validateIndex(index);
+ if (str == null) {
+ str = nullText;
+ }
+ if (str != null) {
+ final int strLen = str.length();
+ if (strLen > 0) {
+ final int newSize = size + strLen;
+ ensureCapacity(newSize);
+ System.arraycopy(buffer, index, buffer, index + strLen, size - index);
+ size = newSize;
+ str.getChars(0, strLen, buffer, index);
+ }
+ }
+ return this;
+ }
+
+ /**
+ * Inserts the character array into this builder. Inserting null will use the stored null text value.
+ *
+ * @param index
+ * the index to add at, must be valid
+ * @param chars
+ * the char array to insert
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public TextStringBuilder insert(final int index, final char[] chars) {
+ validateIndex(index);
+ if (chars == null) {
+ return insert(index, nullText);
+ }
+ final int len = chars.length;
+ if (len > 0) {
+ ensureCapacity(size + len);
+ System.arraycopy(buffer, index, buffer, index + len, size - index);
+ System.arraycopy(chars, 0, buffer, index, len);
+ size += len;
+ }
+ return this;
+ }
+
+ /**
+ * Inserts part of the character array into this builder. Inserting null will use the stored null text value.
+ *
+ * @param index
+ * the index to add at, must be valid
+ * @param chars
+ * the char array to insert
+ * @param offset
+ * the offset into the character array to start at, must be valid
+ * @param length
+ * the length of the character array part to copy, must be positive
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if any index is invalid
+ */
+ public TextStringBuilder insert(final int index, final char[] chars, final int offset, final int length) {
+ validateIndex(index);
+ if (chars == null) {
+ return insert(index, nullText);
+ }
+ if (offset < 0 || offset > chars.length) {
+ throw new StringIndexOutOfBoundsException("Invalid offset: " + offset);
+ }
+ if (length < 0 || offset + length > chars.length) {
+ throw new StringIndexOutOfBoundsException("Invalid length: " + length);
+ }
+ if (length > 0) {
+ ensureCapacity(size + length);
+ System.arraycopy(buffer, index, buffer, index + length, size - index);
+ System.arraycopy(chars, offset, buffer, index, length);
+ size += length;
+ }
+ return this;
+ }
+
+ /**
+ * Inserts the value into this builder.
+ *
+ * @param index
+ * the index to add at, must be valid
+ * @param value
+ * the value to insert
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public TextStringBuilder insert(int index, final boolean value) {
+ validateIndex(index);
+ if (value) {
+ ensureCapacity(size + TRUE_STRING_SIZE);
+ System.arraycopy(buffer, index, buffer, index + TRUE_STRING_SIZE, size - index);
+ buffer[index++] = 't';
+ buffer[index++] = 'r';
+ buffer[index++] = 'u';
+ buffer[index] = 'e';
+ size += TRUE_STRING_SIZE;
+ } else {
+ ensureCapacity(size + FALSE_STRING_SIZE);
+ System.arraycopy(buffer, index, buffer, index + FALSE_STRING_SIZE, size - index);
+ buffer[index++] = 'f';
+ buffer[index++] = 'a';
+ buffer[index++] = 'l';
+ buffer[index++] = 's';
+ buffer[index] = 'e';
+ size += FALSE_STRING_SIZE;
+ }
+ return this;
+ }
+
+ /**
+ * Inserts the value into this builder.
+ *
+ * @param index
+ * the index to add at, must be valid
+ * @param value
+ * the value to insert
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public TextStringBuilder insert(final int index, final char value) {
+ validateIndex(index);
+ ensureCapacity(size + 1);
+ System.arraycopy(buffer, index, buffer, index + 1, size - index);
+ buffer[index] = value;
+ size++;
+ return this;
+ }
+
+ /**
+ * Inserts the value into this builder.
+ *
+ * @param index
+ * the index to add at, must be valid
+ * @param value
+ * the value to insert
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public TextStringBuilder insert(final int index, final int value) {
+ return insert(index, String.valueOf(value));
+ }
+
+ /**
+ * Inserts the value into this builder.
+ *
+ * @param index
+ * the index to add at, must be valid
+ * @param value
+ * the value to insert
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public TextStringBuilder insert(final int index, final long value) {
+ return insert(index, String.valueOf(value));
+ }
+
+ /**
+ * Inserts the value into this builder.
+ *
+ * @param index
+ * the index to add at, must be valid
+ * @param value
+ * the value to insert
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public TextStringBuilder insert(final int index, final float value) {
+ return insert(index, String.valueOf(value));
+ }
+
+ /**
+ * Inserts the value into this builder.
+ *
+ * @param index
+ * the index to add at, must be valid
+ * @param value
+ * the value to insert
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public TextStringBuilder insert(final int index, final double value) {
+ return insert(index, String.valueOf(value));
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Internal method to delete a range without validation.
+ *
+ * @param startIndex
+ * the start index, must be valid
+ * @param endIndex
+ * the end index (exclusive), must be valid
+ * @param len
+ * the length, must be valid
+ * @throws IndexOutOfBoundsException
+ * if any index is invalid
+ */
+ private void deleteImpl(final int startIndex, final int endIndex, final int len) {
+ System.arraycopy(buffer, endIndex, buffer, startIndex, size - endIndex);
+ size -= len;
+ }
+
+ /**
+ * Deletes the characters between the two specified indices.
+ *
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param endIndex
+ * the end index, exclusive, must be valid except that if too large it is treated as end of string
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public TextStringBuilder delete(final int startIndex, int endIndex) {
+ endIndex = validateRange(startIndex, endIndex);
+ final int len = endIndex - startIndex;
+ if (len > 0) {
+ deleteImpl(startIndex, endIndex, len);
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Deletes the character wherever it occurs in the builder.
+ *
+ * @param ch
+ * the character to delete
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder deleteAll(final char ch) {
+ for (int i = 0; i < size; i++) {
+ if (buffer[i] == ch) {
+ final int start = i;
+ while (++i < size) {
+ if (buffer[i] != ch) {
+ break;
+ }
+ }
+ final int len = i - start;
+ deleteImpl(start, i, len);
+ i -= len;
+ }
+ }
+ return this;
+ }
+
+ /**
+ * Deletes the character wherever it occurs in the builder.
+ *
+ * @param ch
+ * the character to delete
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder deleteFirst(final char ch) {
+ for (int i = 0; i < size; i++) {
+ if (buffer[i] == ch) {
+ deleteImpl(i, i + 1, 1);
+ break;
+ }
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Deletes the string wherever it occurs in the builder.
+ *
+ * @param str
+ * the string to delete, null causes no action
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder deleteAll(final String str) {
+ final int len = (str == null ? 0 : str.length());
+ if (len > 0) {
+ int index = indexOf(str, 0);
+ while (index >= 0) {
+ deleteImpl(index, index + len, len);
+ index = indexOf(str, index);
+ }
+ }
+ return this;
+ }
+
+ /**
+ * Deletes the string wherever it occurs in the builder.
+ *
+ * @param str
+ * the string to delete, null causes no action
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder deleteFirst(final String str) {
+ final int len = (str == null ? 0 : str.length());
+ if (len > 0) {
+ final int index = indexOf(str, 0);
+ if (index >= 0) {
+ deleteImpl(index, index + len, len);
+ }
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Deletes all parts of the builder that the matcher matches.
+ * <p>
+ * Matchers can be used to perform advanced deletion behaviour. For example you could write a matcher to delete all
+ * occurrences where the character 'a' is followed by a number.
+ *
+ * @param matcher
+ * the matcher to use to find the deletion, null causes no action
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder deleteAll(final StringMatcher matcher) {
+ return replace(matcher, null, 0, size, -1);
+ }
+
+ /**
+ * Deletes the first match within the builder using the specified matcher.
+ * <p>
+ * Matchers can be used to perform advanced deletion behaviour. For example you could write a matcher to delete
+ * where the character 'a' is followed by a number.
+ *
+ * @param matcher
+ * the matcher to use to find the deletion, null causes no action
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder deleteFirst(final StringMatcher matcher) {
+ return replace(matcher, null, 0, size, 1);
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Internal method to delete a range without validation.
+ *
+ * @param startIndex
+ * the start index, must be valid
+ * @param endIndex
+ * the end index (exclusive), must be valid
+ * @param removeLen
+ * the length to remove (endIndex - startIndex), must be valid
+ * @param insertStr
+ * the string to replace with, null means delete range
+ * @param insertLen
+ * the length of the insert string, must be valid
+ * @throws IndexOutOfBoundsException
+ * if any index is invalid
+ */
+ private void replaceImpl(final int startIndex, final int endIndex, final int removeLen, final String insertStr,
+ final int insertLen) {
+ final int newSize = size - removeLen + insertLen;
+ if (insertLen != removeLen) {
+ ensureCapacity(newSize);
+ System.arraycopy(buffer, endIndex, buffer, startIndex + insertLen, size - endIndex);
+ size = newSize;
+ }
+ if (insertLen > 0) {
+ insertStr.getChars(0, insertLen, buffer, startIndex);
+ }
+ }
+
+ /**
+ * Replaces a portion of the string builder with another string. The length of the inserted string does not have to
+ * match the removed length.
+ *
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param endIndex
+ * the end index, exclusive, must be valid except that if too large it is treated as end of string
+ * @param replaceStr
+ * the string to replace with, null means delete range
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public TextStringBuilder replace(final int startIndex, int endIndex, final String replaceStr) {
+ endIndex = validateRange(startIndex, endIndex);
+ final int insertLen = (replaceStr == null ? 0 : replaceStr.length());
+ replaceImpl(startIndex, endIndex, endIndex - startIndex, replaceStr, insertLen);
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Replaces the search character with the replace character throughout the builder.
+ *
+ * @param search
+ * the search character
+ * @param replace
+ * the replace character
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder replaceAll(final char search, final char replace) {
+ if (search != replace) {
+ for (int i = 0; i < size; i++) {
+ if (buffer[i] == search) {
+ buffer[i] = replace;
+ }
+ }
+ }
+ return this;
+ }
+
+ /**
+ * Replaces the first instance of the search character with the replace character in the builder.
+ *
+ * @param search
+ * the search character
+ * @param replace
+ * the replace character
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder replaceFirst(final char search, final char replace) {
+ if (search != replace) {
+ for (int i = 0; i < size; i++) {
+ if (buffer[i] == search) {
+ buffer[i] = replace;
+ break;
+ }
+ }
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Replaces the search string with the replace string throughout the builder.
+ *
+ * @param searchStr
+ * the search string, null causes no action to occur
+ * @param replaceStr
+ * the replace string, null is equivalent to an empty string
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder replaceAll(final String searchStr, final String replaceStr) {
+ final int searchLen = (searchStr == null ? 0 : searchStr.length());
+ if (searchLen > 0) {
+ final int replaceLen = (replaceStr == null ? 0 : replaceStr.length());
+ int index = indexOf(searchStr, 0);
+ while (index >= 0) {
+ replaceImpl(index, index + searchLen, searchLen, replaceStr, replaceLen);
+ index = indexOf(searchStr, index + replaceLen);
+ }
+ }
+ return this;
+ }
+
+ /**
+ * Replaces the first instance of the search string with the replace string.
+ *
+ * @param searchStr
+ * the search string, null causes no action to occur
+ * @param replaceStr
+ * the replace string, null is equivalent to an empty string
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder replaceFirst(final String searchStr, final String replaceStr) {
+ final int searchLen = (searchStr == null ? 0 : searchStr.length());
+ if (searchLen > 0) {
+ final int index = indexOf(searchStr, 0);
+ if (index >= 0) {
+ final int replaceLen = (replaceStr == null ? 0 : replaceStr.length());
+ replaceImpl(index, index + searchLen, searchLen, replaceStr, replaceLen);
+ }
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Replaces all matches within the builder with the replace string.
+ * <p>
+ * Matchers can be used to perform advanced replace behaviour. For example you could write a matcher to replace all
+ * occurrences where the character 'a' is followed by a number.
+ *
+ * @param matcher
+ * the matcher to use to find the deletion, null causes no action
+ * @param replaceStr
+ * the replace string, null is equivalent to an empty string
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder replaceAll(final StringMatcher matcher, final String replaceStr) {
+ return replace(matcher, replaceStr, 0, size, -1);
+ }
+
+ /**
+ * Replaces the first match within the builder with the replace string.
+ * <p>
+ * Matchers can be used to perform advanced replace behaviour. For example you could write a matcher to replace
+ * where the character 'a' is followed by a number.
+ *
+ * @param matcher
+ * the matcher to use to find the deletion, null causes no action
+ * @param replaceStr
+ * the replace string, null is equivalent to an empty string
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder replaceFirst(final StringMatcher matcher, final String replaceStr) {
+ return replace(matcher, replaceStr, 0, size, 1);
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Advanced search and replaces within the builder using a matcher.
+ * <p>
+ * Matchers can be used to perform advanced behaviour. For example you could write a matcher to delete all
+ * occurrences where the character 'a' is followed by a number.
+ *
+ * @param matcher
+ * the matcher to use to find the deletion, null causes no action
+ * @param replaceStr
+ * the string to replace the match with, null is a delete
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param endIndex
+ * the end index, exclusive, must be valid except that if too large it is treated as end of string
+ * @param replaceCount
+ * the number of times to replace, -1 for replace all
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if start index is invalid
+ */
+ public TextStringBuilder replace(final StringMatcher matcher, final String replaceStr, final int startIndex,
+ int endIndex, final int replaceCount) {
+ endIndex = validateRange(startIndex, endIndex);
+ return replaceImpl(matcher, replaceStr, startIndex, endIndex, replaceCount);
+ }
+
+ /**
+ * Replaces within the builder using a matcher.
+ * <p>
+ * Matchers can be used to perform advanced behaviour. For example you could write a matcher to delete all
+ * occurrences where the character 'a' is followed by a number.
+ *
+ * @param matcher
+ * the matcher to use to find the deletion, null causes no action
+ * @param replaceStr
+ * the string to replace the match with, null is a delete
+ * @param from
+ * the start index, must be valid
+ * @param to
+ * the end index (exclusive), must be valid
+ * @param replaceCount
+ * the number of times to replace, -1 for replace all
+ * @return this, to enable chaining
+ * @throws IndexOutOfBoundsException
+ * if any index is invalid
+ */
+ private TextStringBuilder replaceImpl(final StringMatcher matcher, final String replaceStr, final int from, int to,
+ int replaceCount) {
+ if (matcher == null || size == 0) {
+ return this;
+ }
+ final int replaceLen = (replaceStr == null ? 0 : replaceStr.length());
+ for (int i = from; i < to && replaceCount != 0; i++) {
+ final char[] buf = buffer;
+ final int removeLen = matcher.isMatch(buf, i, from, to);
+ if (removeLen > 0) {
+ replaceImpl(i, i + removeLen, removeLen, replaceStr, replaceLen);
+ to = to - removeLen + replaceLen;
+ i = i + replaceLen - 1;
+ if (replaceCount > 0) {
+ replaceCount--;
+ }
+ }
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Reverses the string builder placing each character in the opposite index.
+ *
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder reverse() {
+ if (size == 0) {
+ return this;
+ }
+
+ final int half = size / 2;
+ final char[] buf = buffer;
+ for (int leftIdx = 0, rightIdx = size - 1; leftIdx < half; leftIdx++, rightIdx--) {
+ final char swap = buf[leftIdx];
+ buf[leftIdx] = buf[rightIdx];
+ buf[rightIdx] = swap;
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Trims the builder by removing characters less than or equal to a space from the beginning and end.
+ *
+ * @return this, to enable chaining
+ */
+ public TextStringBuilder trim() {
+ if (size == 0) {
+ return this;
+ }
+ int len = size;
+ final char[] buf = buffer;
+ int pos = 0;
+ while (pos < len && buf[pos] <= ' ') {
+ pos++;
+ }
+ while (pos < len && buf[len - 1] <= ' ') {
+ len--;
+ }
+ if (len < size) {
+ delete(len, size);
+ }
+ if (pos > 0) {
+ delete(0, pos);
+ }
+ return this;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Checks whether this builder starts with the specified string.
+ * <p>
+ * Note that this method handles null input quietly, unlike String.
+ *
+ * @param str
+ * the string to search for, null returns false
+ * @return true if the builder starts with the string
+ */
+ public boolean startsWith(final String str) {
+ if (str == null) {
+ return false;
+ }
+ final int len = str.length();
+ if (len == 0) {
+ return true;
+ }
+ if (len > size) {
+ return false;
+ }
+ for (int i = 0; i < len; i++) {
+ if (buffer[i] != str.charAt(i)) {
+ return false;
+ }
+ }
+ return true;
+ }
+
+ /**
+ * Checks whether this builder ends with the specified string.
+ * <p>
+ * Note that this method handles null input quietly, unlike String.
+ *
+ * @param str
+ * the string to search for, null returns false
+ * @return true if the builder ends with the string
+ */
+ public boolean endsWith(final String str) {
+ if (str == null) {
+ return false;
+ }
+ final int len = str.length();
+ if (len == 0) {
+ return true;
+ }
+ if (len > size) {
+ return false;
+ }
+ int pos = size - len;
+ for (int i = 0; i < len; i++, pos++) {
+ if (buffer[pos] != str.charAt(i)) {
+ return false;
+ }
+ }
+ return true;
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public CharSequence subSequence(final int startIndex, final int endIndex) {
+ if (startIndex < 0) {
+ throw new StringIndexOutOfBoundsException(startIndex);
+ }
+ if (endIndex > size) {
+ throw new StringIndexOutOfBoundsException(endIndex);
+ }
+ if (startIndex > endIndex) {
+ throw new StringIndexOutOfBoundsException(endIndex - startIndex);
+ }
+ return substring(startIndex, endIndex);
+ }
+
+ /**
+ * Extracts a portion of this string builder as a string.
+ *
+ * @param start
+ * the start index, inclusive, must be valid
+ * @return the new string
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public String substring(final int start) {
+ return substring(start, size);
+ }
+
+ /**
+ * Extracts a portion of this string builder as a string.
+ * <p>
+ * 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.
+ *
+ * @param startIndex
+ * the start index, inclusive, must be valid
+ * @param endIndex
+ * the end index, exclusive, must be valid except that if too large it is treated as end of string
+ * @return the new string
+ * @throws IndexOutOfBoundsException
+ * if the index is invalid
+ */
+ public String substring(final int startIndex, int endIndex) {
+ endIndex = validateRange(startIndex, endIndex);
+ return new String(buffer, startIndex, endIndex - startIndex);
+ }
+
+ /**
+ * Extracts the leftmost characters from the string builder without throwing an exception.
+ * <p>
+ * This method extracts the left <code>length</code> 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.
+ *
+ * @param length
+ * the number of characters to extract, negative returns empty string
+ * @return the new string
+ */
+ public String leftString(final int length) {
+ if (length <= 0) {
+ return "";
+ } else if (length >= size) {
+ return new String(buffer, 0, size);
+ } else {
+ return new String(buffer, 0, length);
+ }
+ }
+
+ /**
+ * Extracts the rightmost characters from the string builder without throwing an exception.
+ * <p>
+ * This method extracts the right <code>length</code> 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.
+ *
+ * @param length
+ * the number of characters to extract, negative returns empty string
+ * @return the new string
+ */
+ public String rightString(final int length) {
+ if (length <= 0) {
+ return "";
+ } else if (length >= size) {
+ return new String(buffer, 0, size);
+ } else {
+ return new String(buffer, size - length, length);
+ }
+ }
+
+ /**
+ * Extracts some characters from the middle of the string builder without throwing an exception.
+ * <p>
+ * This method extracts <code>length</code> 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.
+ *
+ * @param index
+ * the index to start at, negative means zero
+ * @param length
+ * the number of characters to extract, negative returns empty string
+ * @return the new string
+ */
+ public String midString(int index, final int length) {
+ if (index < 0) {
+ index = 0;
+ }
+ if (length <= 0 || index >= size) {
+ return "";
+ }
+ if (size <= index + length) {
+ return new String(buffer, index, size - index);
+ }
+ return new String(buffer, index, length);
+ }
+
+ // -----------------------------------------------------------------------
+ /**
+ * Checks if the string builder contains the specified char.
+ *
+ * @param ch
+ * the character to find
+ * @return true if the builder contains the character
+ */
+ public boolean contains(final char ch) {
+ final char[] thisBuf = buffer;
+ for (int i = 0; i < this.size; i++) {
+ if (thisBuf[i] == ch) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ /**
+ * Checks if the string builder contains the specified string.
+ *
+ * @param str
+ * the string to find
+ * @return true if the builder contains the string
+ */
+ public boolean contains(final String str) {
+ return indexOf(str, 0) >= 0;
+ }
+
+ /**
+ * Checks if the string builder contains a string matched using the specified matcher.
+ * <p>
+ * Matchers can be used to perform advanced searching behaviour. For example you c
<TRUNCATED>