    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.text;
    018
    019import java.io.IOException;
    020import java.io.Reader;
    021import java.io.Serializable;
    022import java.io.Writer;
    023import java.nio.CharBuffer;
    024import java.util.Arrays;
    025import java.util.Iterator;
    026import java.util.List;
    027import java.util.Objects;
    028
    029import org.apache.commons.lang3.ArrayUtils;
    030import org.apache.commons.lang3.StringUtils;
    031import org.apache.commons.text.matcher.StringMatcher;
    032
    033/**
    034 * Builds a string from constituent parts providing a more flexible and powerful API than {@link StringBuffer} and
    035 * {@link StringBuilder}.
    036 * <p>
    037 * The main differences from StringBuffer/StringBuilder are:
    038 * </p>
    039 * <ul>
    040 * <li>Not synchronized</li>
    041 * <li>Not final</li>
    042 * <li>Subclasses have direct access to character array</li>
    043 * <li>Additional methods
    044 * <ul>
    045 * <li>appendWithSeparators - adds an array of values, with a separator</li>
    046 * <li>appendPadding - adds a length padding characters</li>
    047 * <li>appendFixedLength - adds a fixed width field to the builder</li>
    048 * <li>toCharArray/getChars - simpler ways to get a range of the character array</li>
    049 * <li>delete - delete char or string</li>
    050 * <li>replace - search and replace for a char or string</li>
    051 * <li>leftString/rightString/midString - substring without exceptions</li>
    052 * <li>contains - whether the builder contains a char or string</li>
    053 * <li>size/clear/isEmpty - collections style API methods</li>
    054 * </ul>
    055 * </li>
    056 * <li>Views
    057 * <ul>
    058 * <li>asTokenizer - uses the internal buffer as the source of a StrTokenizer</li>
    059 * <li>asReader - uses the internal buffer as the source of a Reader</li>
    060 * <li>asWriter - allows a Writer to write directly to the internal buffer</li>
    061 * </ul>
    062 * </li>
    063 * </ul>
    064 * <p>
    065 * The aim has been to provide an API that mimics very closely what StringBuffer provides, but with additional methods.
    066 * It should be noted that some edge cases, with invalid indices or null input, have been altered - see individual
    067 * methods. The biggest of these changes is that by default, null will not output the text 'null'. This can be
    068 * controlled by a property, {@link #setNullText(String)}.
    069 * </p>
    070 * <p>
    071 * This class is called {@code TextStringBuilder} instead of {@code StringBuilder} to avoid clashing with
    072 * {@link StringBuilder}.
    073 * </p>
    074 *
    075 * @since 1.3
    076 */
    077public class TextStringBuilder implements CharSequence, Appendable, Serializable, Builder<String> {
    078
    079    /**
    080     * Inner class to allow StrBuilder to operate as a reader.
    081     */
    082    class TextStringBuilderReader extends Reader {
    083
    084        /** The last mark position. */
    085        private int mark;
    086
    087        /** The current stream position. */
    088        private int pos;
    089
    090        /**
    091         * Default constructor.
    092         */
    093        TextStringBuilderReader() {
    094        }
    095
    096        /** {@inheritDoc} */
    097        @Override
    098        public void close() {
    099            // do nothing
    100        }
    101
    102        /** {@inheritDoc} */
    103        @Override
    104        public void mark(final int readAheadLimit) {
    105            mark = pos;
    106        }
    107
    108        /** {@inheritDoc} */
    109        @Override
    110        public boolean markSupported() {
    111            return true;
    112        }
    113
    114        /** {@inheritDoc} */
    115        @Override
    116        public int read() {
    117            if (!ready()) {
    118                return -1;
    119            }
    120            return TextStringBuilder.this.charAt(pos++);
    121        }
    122
    123        /** {@inheritDoc} */
    124        @Override
    125        public int read(final char[] b, final int off, int len) {
    126            if (off < 0 || len < 0 || off > b.length || off + len > b.length || off + len < 0) {
    127                throw new IndexOutOfBoundsException();
    128            }
    129            if (len == 0) {
    130                return 0;
    131            }
    132            if (pos >= TextStringBuilder.this.size()) {
    133                return -1;
    134            }
    135            if (pos + len > size()) {
    136                len = TextStringBuilder.this.size() - pos;
    137            }
    138            TextStringBuilder.this.getChars(pos, pos + len, b, off);
    139            pos += len;
    140            return len;
    141        }
    142
    143        /** {@inheritDoc} */
    144        @Override
    145        public boolean ready() {
    146            return pos < TextStringBuilder.this.size();
    147        }
    148
    149        /** {@inheritDoc} */
    150        @Override
    151        public void reset() {
    152            pos = mark;
    153        }
    154
    155        /** {@inheritDoc} */
    156        @Override
    157        public long skip(long n) {
    158            if (pos + n > TextStringBuilder.this.size()) {
    159                n = TextStringBuilder.this.size() - pos;
    160            }
    161            if (n < 0) {
    162                return 0;
    163            }
    164            pos = Math.addExact(pos, Math.toIntExact(n));
    165            return n;
    166        }
    167    }
    168
    169    /**
    170     * Inner class to allow StrBuilder to operate as a tokenizer.
    171     */
    172    class TextStringBuilderTokenizer extends StringTokenizer {
    173
    174        /**
    175         * Default constructor.
    176         */
    177        TextStringBuilderTokenizer() {
    178        }
    179
    180        /** {@inheritDoc} */
    181        @Override
    182        public String getContent() {
    183            final String str = super.getContent();
    184            if (str == null) {
    185                return TextStringBuilder.this.toString();
    186            }
    187            return str;
    188        }
    189
    190        /** {@inheritDoc} */
    191        @Override
    192        protected List<String> tokenize(final char[] chars, final int offset, final int count) {
    193            if (chars == null) {
    194                return super.tokenize(TextStringBuilder.this.getBuffer(), 0, TextStringBuilder.this.size());
    195            }
    196            return super.tokenize(chars, offset, count);
    197        }
    198    }
    199
    200    /**
    201     * Inner class to allow StrBuilder to operate as a writer.
    202     */
    203    class TextStringBuilderWriter extends Writer {
    204
    205        /**
    206         * Default constructor.
    207         */
    208        TextStringBuilderWriter() {
    209        }
    210
    211        /** {@inheritDoc} */
    212        @Override
    213        public void close() {
    214            // do nothing
    215        }
    216
    217        /** {@inheritDoc} */
    218        @Override
    219        public void flush() {
    220            // do nothing
    221        }
    222
    223        /** {@inheritDoc} */
    224        @Override
    225        public void write(final char[] cbuf) {
    226            TextStringBuilder.this.append(cbuf);
    227        }
    228
    229        /** {@inheritDoc} */
    230        @Override
    231        public void write(final char[] cbuf, final int off, final int len) {
    232            TextStringBuilder.this.append(cbuf, off, len);
    233        }
    234
    235        /** {@inheritDoc} */
    236        @Override
    237        public void write(final int c) {
    238            TextStringBuilder.this.append((char) c);
    239        }
    240
    241        /** {@inheritDoc} */
    242        @Override
    243        public void write(final String str) {
    244            TextStringBuilder.this.append(str);
    245        }
    246
    247        /** {@inheritDoc} */
    248        @Override
    249        public void write(final String str, final int off, final int len) {
    250            TextStringBuilder.this.append(str, off, len);
    251        }
    252    }
    253
    254    /** The space character. */
    255    private static final char SPACE = ' ';
    256
    257    /**
    258     * The extra capacity for new builders.
    259     */
    260    static final int CAPACITY = 32;
    261
    262    /**
    263     * End-Of-Stream.
    264     */
    265    private static final int EOS = -1;
    266
    267    /**
    268     * The size of the string {@code "false"}.
    269     */
    270    private static final int FALSE_STRING_SIZE = Boolean.FALSE.toString().length();
    271
    272    /**
    273     * Required for serialization support.
    274     *
    275     * @see java.io.Serializable
    276     */
    277    private static final long serialVersionUID = 1L;
    278
    279    /**
    280     * The size of the string {@code "true"}.
    281     */
    282    private static final int TRUE_STRING_SIZE = Boolean.TRUE.toString().length();
    283
    284    /**
    285     * The maximum size buffer to allocate.
    286     *
    287     * <p>This is set to the same size used in the JDK {@code java.util.ArrayList}:</p>
    288     * <blockquote>
    289     * Some VMs reserve some header words in an array.
    290     * Attempts to allocate larger arrays may result in
    291     * OutOfMemoryError: Requested array size exceeds VM limit.
    292     * </blockquote>
    293     */
    294    private static final int MAX_BUFFER_SIZE = Integer.MAX_VALUE - 8;
    295
    296    /**
    297     * Creates a positive capacity at least as large the minimum required capacity.
    298     * If the minimum capacity is negative then this throws an OutOfMemoryError as no array
    299     * can be allocated.
    300     *
    301     * @param minCapacity the minimum capacity
    302     * @return the capacity
    303     * @throws OutOfMemoryError if the {@code minCapacity} is negative
    304     */
    305    private static int createPositiveCapacity(final int minCapacity) {
    306        if (minCapacity < 0) {
    307            // overflow
    308            throw new OutOfMemoryError("Unable to allocate array size: " + Integer.toUnsignedString(minCapacity));
    309        }
    310        // This is called when we require buffer expansion to a very big array.
    311        // Use the conservative maximum buffer size if possible, otherwise the biggest required.
    312        //
    313        // Note: In this situation JDK 1.8 java.util.ArrayList returns Integer.MAX_VALUE.
    314        // This excludes some VMs that can exceed MAX_BUFFER_SIZE but not allocate a full
    315        // Integer.MAX_VALUE length array.
    316        // The result is that we may have to allocate an array of this size more than once if
    317        // the capacity must be expanded again.
    318        return Math.max(minCapacity, MAX_BUFFER_SIZE);
    319    }
    320
    321    /**
    322     * Constructs an instance from a reference to a character array. Changes to the input chars are reflected in this
    323     * instance until the internal buffer needs to be reallocated. Using a reference to an array allows the instance to
    324     * be initialized without copying the input array.
    325     *
    326     * @param initialBuffer The initial array that will back the new builder.
    327     * @return A new instance.
    328     * @since 1.9
    329     */
    330    public static TextStringBuilder wrap(final char[] initialBuffer) {
    331        Objects.requireNonNull(initialBuffer, "initialBuffer");
    332        return new TextStringBuilder(initialBuffer, initialBuffer.length);
    333    }
    334
    335    /**
    336     * Constructs an instance from a reference to a character array. Changes to the input chars are reflected in this
    337     * instance until the internal buffer needs to be reallocated. Using a reference to an array allows the instance to
    338     * be initialized without copying the input array.
    339     *
    340     * @param initialBuffer The initial array that will back the new builder.
    341     * @param length The length of the subarray to be used; must be non-negative and no larger than
    342     *        {@code initialBuffer.length}. The new builder's size will be set to {@code length}.
    343     * @return A new instance.
    344     * @since 1.9
    345     */
    346    public static TextStringBuilder wrap(final char[] initialBuffer, final int length) {
    347        return new TextStringBuilder(initialBuffer, length);
    348    }
    349
    350    /** Internal data storage. */
    351    private char[] buffer;
    352
    353    /** The new line. */
    354    private String newLine;
    355
    356    /** The null text. */
    357    private String nullText;
    358
    359    /** Incremented when the buffer is reallocated. */
    360    private int reallocations;
    361
    362    /** Current size of the buffer. */
    363    private int size;
    364
    365    /**
    366     * Constructs an empty builder with an initial capacity of 32 characters.
    367     */
    368    public TextStringBuilder() {
    369        this(CAPACITY);
    370    }
    371
    372    /**
    373     * Constructs an instance from a reference to a character array.
    374     *
    375     * @param initialBuffer a reference to a character array, must not be null.
    376     * @param length The length of the subarray to be used; must be non-negative and no larger than
    377     *        {@code initialBuffer.length}. The new builder's size will be set to {@code length}.
    378     * @throws NullPointerException If {@code initialBuffer} is null.
    379     * @throws IllegalArgumentException if {@code length} is bad.
    380     */
    381    private TextStringBuilder(final char[] initialBuffer, final int length) {
    382        this.buffer = Objects.requireNonNull(initialBuffer, "initialBuffer");
    383        if (length < 0 || length > initialBuffer.length) {
    384            throw new IllegalArgumentException("initialBuffer.length=" + initialBuffer.length + ", length=" + length);
    385        }
    386        this.size = length;
    387    }
    388
    389    /**
    390     * Constructs an instance from a character sequence, allocating 32 extra characters for growth.
    391     *
    392     * @param seq the string to copy, null treated as blank string
    393     * @since 1.9
    394     */
    395    public TextStringBuilder(final CharSequence seq) {
    396        this(StringUtils.length(seq) + CAPACITY);
    397        if (seq != null) {
    398            append(seq);
    399        }
    400    }
    401
    402    /**
    403     * Constructs an instance with the specified initial capacity.
    404     *
    405     * @param initialCapacity the initial capacity, zero or less will be converted to 32
    406     */
    407    public TextStringBuilder(final int initialCapacity) {
    408        buffer = new char[initialCapacity <= 0 ? CAPACITY : initialCapacity];
    409    }
    410
    411    /**
    412     * Constructs an instance from a string, allocating 32 extra characters for growth.
    413     *
    414     * @param str the string to copy, null treated as blank string
    415     */
    416    public TextStringBuilder(final String str) {
    417        this(StringUtils.length(str) + CAPACITY);
    418        if (str != null) {
    419            append(str);
    420        }
    421    }
    422
    423    /**
    424     * Appends a boolean value to the string builder.
    425     *
    426     * @param value the value to append
    427     * @return this, to enable chaining
    428     */
    429    public TextStringBuilder append(final boolean value) {
    430        if (value) {
    431            ensureCapacityInternal(size + TRUE_STRING_SIZE);
    432            appendTrue(size);
    433        } else {
    434            ensureCapacityInternal(size + FALSE_STRING_SIZE);
    435            appendFalse(size);
    436        }
    437        return this;
    438    }
    439
    440    /**
    441     * Appends a char value to the string builder.
    442     *
    443     * @param ch the value to append
    444     * @return this, to enable chaining
    445     */
    446    @Override
    447    public TextStringBuilder append(final char ch) {
    448        final int len = length();
    449        ensureCapacityInternal(len + 1);
    450        buffer[size++] = ch;
    451        return this;
    452    }
    453
    454    /**
    455     * Appends a char array to the string builder. Appending null will call {@link #appendNull()}.
    456     *
    457     * @param chars the char array to append
    458     * @return this, to enable chaining
    459     */
    460    public TextStringBuilder append(final char[] chars) {
    461        if (chars == null) {
    462            return appendNull();
    463        }
    464        final int strLen = chars.length;
    465        if (strLen > 0) {
    466            final int len = length();
    467            ensureCapacityInternal(len + strLen);
    468            System.arraycopy(chars, 0, buffer, len, strLen);
    469            size += strLen;
    470        }
    471        return this;
    472    }
    473
    474    /**
    475     * Appends a char array to the string builder. Appending null will call {@link #appendNull()}.
    476     *
    477     * @param chars the char array to append
    478     * @param startIndex the start index, inclusive, must be valid
    479     * @param length the length to append, must be valid
    480     * @return this, to enable chaining
    481     * @throws StringIndexOutOfBoundsException if {@code startIndex} is not in the
    482     *  range {@code 0 <= startIndex <= chars.length}
    483     * @throws StringIndexOutOfBoundsException if {@code length < 0}
    484     * @throws StringIndexOutOfBoundsException if {@code startIndex + length > chars.length}
    485     */
    486    public TextStringBuilder append(final char[] chars, final int startIndex, final int length) {
    487        if (chars == null) {
    488            return appendNull();
    489        }
    490        if (startIndex < 0 || startIndex > chars.length) {
    491            throw new StringIndexOutOfBoundsException("Invalid startIndex: " + length);
    492        }
    493        if (length < 0 || startIndex + length > chars.length) {
    494            throw new StringIndexOutOfBoundsException("Invalid length: " + length);
    495        }
    496        if (length > 0) {
    497            final int len = length();
    498            ensureCapacityInternal(len + length);
    499            System.arraycopy(chars, startIndex, buffer, len, length);
    500            size += length;
    501        }
    502        return this;
    503    }
    504
    505    /**
    506     * Appends the contents of a char buffer to this string builder. Appending null will call {@link #appendNull()}.
    507     *
    508     * @param str the char buffer to append
    509     * @return this, to enable chaining
    510     */
    511    public TextStringBuilder append(final CharBuffer str) {
    512        return append(str, 0, StringUtils.length(str));
    513    }
    514
    515    /**
    516     * Appends the contents of a char buffer to this string builder. Appending null will call {@link #appendNull()}.
    517     *
    518     * @param buf the char buffer to append
    519     * @param startIndex the start index, inclusive, must be valid
    520     * @param length the length to append, must be valid
    521     * @return this, to enable chaining
    522     */
    523    public TextStringBuilder append(final CharBuffer buf, final int startIndex, final int length) {
    524        if (buf == null) {
    525            return appendNull();
    526        }
    527        if (buf.hasArray()) {
    528            final int totalLength = buf.remaining();
    529            if (startIndex < 0 || startIndex > totalLength) {
    530                throw new StringIndexOutOfBoundsException("startIndex must be valid");
    531            }
    532            if (length < 0 || startIndex + length > totalLength) {
    533                throw new StringIndexOutOfBoundsException("length must be valid");
    534            }
    535            final int len = length();
    536            ensureCapacityInternal(len + length);
    537            System.arraycopy(buf.array(), buf.arrayOffset() + buf.position() + startIndex, buffer, len, length);
    538            size += length;
    539        } else {
    540            append(buf.toString(), startIndex, length);
    541        }
    542        return this;
    543    }
    544
    545    /**
    546     * Appends a CharSequence to this string builder. Appending null will call {@link #appendNull()}.
    547     *
    548     * @param seq the CharSequence to append
    549     * @return this, to enable chaining
    550     */
    551    @Override
    552    public TextStringBuilder append(final CharSequence seq) {
    553        if (seq == null) {
    554            return appendNull();
    555        }
    556        if (seq instanceof TextStringBuilder) {
    557            return append((TextStringBuilder) seq);
    558        }
    559        if (seq instanceof StringBuilder) {
    560            return append((StringBuilder) seq);
    561        }
    562        if (seq instanceof StringBuffer) {
    563            return append((StringBuffer) seq);
    564        }
    565        if (seq instanceof CharBuffer) {
    566            return append((CharBuffer) seq);
    567        }
    568        return append(seq.toString());
    569    }
    570
    571    /**
    572     * Appends part of a CharSequence to this string builder. Appending null will call {@link #appendNull()}.
    573     *
    574     * @param seq the CharSequence to append
    575     * @param startIndex the start index, inclusive, must be valid
    576     * @param endIndex the end index, exclusive, must be valid
    577     * @return this, to enable chaining
    578     */
    579    @Override
    580    public TextStringBuilder append(final CharSequence seq, final int startIndex, final int endIndex) {
    581        if (seq == null) {
    582            return appendNull();
    583        }
    584        if (endIndex <= 0) {
    585            throw new StringIndexOutOfBoundsException("endIndex must be valid");
    586        }
    587        if (startIndex >= endIndex) {
    588            throw new StringIndexOutOfBoundsException("endIndex must be greater than startIndex");
    589        }
    590        return append(seq.toString(), startIndex, endIndex - startIndex);
    591    }
    592
    593    /**
    594     * Appends a double value to the string builder using {@code String.valueOf}.
    595     *
    596     * @param value the value to append
    597     * @return this, to enable chaining
    598     */
    599    public TextStringBuilder append(final double value) {
    600        return append(String.valueOf(value));
    601    }
    602
    603    /**
    604     * Appends a float value to the string builder using {@code String.valueOf}.
    605     *
    606     * @param value the value to append
    607     * @return this, to enable chaining
    608     */
    609    public TextStringBuilder append(final float value) {
    610        return append(String.valueOf(value));
    611    }
    612
    613    /**
    614     * Appends an int value to the string builder using {@code String.valueOf}.
    615     *
    616     * @param value the value to append
    617     * @return this, to enable chaining
    618     */
    619    public TextStringBuilder append(final int value) {
    620        return append(String.valueOf(value));
    621    }
    622
    623    /**
    624     * Appends a long value to the string builder using {@code String.valueOf}.
    625     *
    626     * @param value the value to append
    627     * @return this, to enable chaining
    628     */
    629    public TextStringBuilder append(final long value) {
    630        return append(String.valueOf(value));
    631    }
    632
    633    /**
    634     * Appends an object to this string builder. Appending null will call {@link #appendNull()}.
    635     *
    636     * @param obj the object to append
    637     * @return this, to enable chaining
    638     */
    639    public TextStringBuilder append(final Object obj) {
    640        if (obj == null) {
    641            return appendNull();
    642        }
    643        if (obj instanceof CharSequence) {
    644            return append((CharSequence) obj);
    645        }
    646        return append(obj.toString());
    647    }
    648
    649    /**
    650     * Appends a string to this string builder. Appending null will call {@link #appendNull()}.
    651     *
    652     * @param str the string to append
    653     * @return this, to enable chaining
    654     */
    655    public TextStringBuilder append(final String str) {
    656        return append(str, 0, StringUtils.length(str));
    657    }
    658
    659    /**
    660     * Appends part of a string to this string builder. Appending null will call {@link #appendNull()}.
    661     *
    662     * @param str the string to append
    663     * @param startIndex the start index, inclusive, must be valid
    664     * @param length the length to append, must be valid
    665     * @return this, to enable chaining
    666     * @throws StringIndexOutOfBoundsException if {@code startIndex} is not in the
    667     *  range {@code 0 <= startIndex <= str.length()}
    668     * @throws StringIndexOutOfBoundsException if {@code length < 0}
    669     * @throws StringIndexOutOfBoundsException if {@code startIndex + length > str.length()}
    670     */
    671    public TextStringBuilder append(final String str, final int startIndex, final int length) {
    672        if (str == null) {
    673            return appendNull();
    674        }
    675        if (startIndex < 0 || startIndex > str.length()) {
    676            throw new StringIndexOutOfBoundsException("startIndex must be valid");
    677        }
    678        if (length < 0 || startIndex + length > str.length()) {
    679            throw new StringIndexOutOfBoundsException("length must be valid");
    680        }
    681        if (length > 0) {
    682            final int len = length();
    683            ensureCapacityInternal(len + length);
    684            str.getChars(startIndex, startIndex + length, buffer, len);
    685            size += length;
    686        }
    687        return this;
    688    }
    689
    690    /**
    691     * Calls {@link String#format(String, Object...)} and appends the result.
    692     *
    693     * @param format the format string
    694     * @param objs the objects to use in the format string
    695     * @return {@code this} to enable chaining
    696     * @see String#format(String, Object...)
    697     */
    698    public TextStringBuilder append(final String format, final Object... objs) {
    699        return append(String.format(format, objs));
    700    }
    701
    702    /**
    703     * Appends a string buffer to this string builder. Appending null will call {@link #appendNull()}.
    704     *
    705     * @param str the string buffer to append
    706     * @return this, to enable chaining
    707     */
    708    public TextStringBuilder append(final StringBuffer str) {
    709        return append(str, 0, StringUtils.length(str));
    710    }
    711
    712    /**
    713     * Appends part of a string buffer to this string builder. Appending null will call {@link #appendNull()}.
    714     *
    715     * @param str the string to append
    716     * @param startIndex the start index, inclusive, must be valid
    717     * @param length the length to append, must be valid
    718     * @return this, to enable chaining
    719     */
    720    public TextStringBuilder append(final StringBuffer str, final int startIndex, final int length) {
    721        if (str == null) {
    722            return appendNull();
    723        }
    724        if (startIndex < 0 || startIndex > str.length()) {
    725            throw new StringIndexOutOfBoundsException("startIndex must be valid");
    726        }
    727        if (length < 0 || startIndex + length > str.length()) {
    728            throw new StringIndexOutOfBoundsException("length must be valid");
    729        }
    730        if (length > 0) {
    731            final int len = length();
    732            ensureCapacityInternal(len + length);
    733            str.getChars(startIndex, startIndex + length, buffer, len);
    734            size += length;
    735        }
    736        return this;
    737    }
    738
    739    /**
    740     * Appends a StringBuilder to this string builder. Appending null will call {@link #appendNull()}.
    741     *
    742     * @param str the StringBuilder to append
    743     * @return this, to enable chaining
    744     */
    745    public TextStringBuilder append(final StringBuilder str) {
    746        return append(str, 0, StringUtils.length(str));
    747    }
    748
    749    /**
    750     * Appends part of a StringBuilder to this string builder. Appending null will call {@link #appendNull()}.
    751     *
    752     * @param str the StringBuilder to append
    753     * @param startIndex the start index, inclusive, must be valid
    754     * @param length the length to append, must be valid
    755     * @return this, to enable chaining
    756     */
    757    public TextStringBuilder append(final StringBuilder str, final int startIndex, final int length) {
    758        if (str == null) {
    759            return appendNull();
    760        }
    761        if (startIndex < 0 || startIndex > str.length()) {
    762            throw new StringIndexOutOfBoundsException("startIndex must be valid");
    763        }
    764        if (length < 0 || startIndex + length > str.length()) {
    765            throw new StringIndexOutOfBoundsException("length must be valid");
    766        }
    767        if (length > 0) {
    768            final int len = length();
    769            ensureCapacityInternal(len + length);
    770            str.getChars(startIndex, startIndex + length, buffer, len);
    771            size += length;
    772        }
    773        return this;
    774    }
    775
    776    /**
    777     * Appends another string builder to this string builder. Appending null will call {@link #appendNull()}.
    778     *
    779     * @param str the string builder to append
    780     * @return this, to enable chaining
    781     */
    782    public TextStringBuilder append(final TextStringBuilder str) {
    783        return append(str, 0, StringUtils.length(str));
    784    }
    785
    786    /**
    787     * Appends part of a string builder to this string builder. Appending null will call {@link #appendNull()}.
    788     *
    789     * @param str the string to append
    790     * @param startIndex the start index, inclusive, must be valid
    791     * @param length the length to append, must be valid
    792     * @return this, to enable chaining
    793     */
    794    public TextStringBuilder append(final TextStringBuilder str, final int startIndex, final int length) {
    795        if (str == null) {
    796            return appendNull();
    797        }
    798        if (startIndex < 0 || startIndex > str.length()) {
    799            throw new StringIndexOutOfBoundsException("startIndex must be valid");
    800        }
    801        if (length < 0 || startIndex + length > str.length()) {
    802            throw new StringIndexOutOfBoundsException("length must be valid");
    803        }
    804        if (length > 0) {
    805            final int len = length();
    806            ensureCapacityInternal(len + length);
    807            str.getChars(startIndex, startIndex + length, buffer, len);
    808            size += length;
    809        }
    810        return this;
    811    }
    812
    813    /**
    814     * Appends each item in an iterable to the builder without any separators. Appending a null iterable will have no
    815     * effect. Each object is appended using {@link #append(Object)}.
    816     *
    817     * @param iterable the iterable to append
    818     * @return this, to enable chaining
    819     */
    820    public TextStringBuilder appendAll(final Iterable<?> iterable) {
    821        if (iterable != null) {
    822            iterable.forEach(this::append);
    823        }
    824        return this;
    825    }
    826
    827    /**
    828     * Appends each item in an iterator to the builder without any separators. Appending a null iterator will have no
    829     * effect. Each object is appended using {@link #append(Object)}.
    830     *
    831     * @param it the iterator to append
    832     * @return this, to enable chaining
    833     */
    834    public TextStringBuilder appendAll(final Iterator<?> it) {
    835        if (it != null) {
    836            it.forEachRemaining(this::append);
    837        }
    838        return this;
    839    }
    840
    841    /**
    842     * Appends each item in an array to the builder without any separators. Appending a null array will have no effect.
    843     * Each object is appended using {@link #append(Object)}.
    844     *
    845     * @param <T> the element type
    846     * @param array the array to append
    847     * @return this, to enable chaining
    848     */
    849    public <T> TextStringBuilder appendAll(@SuppressWarnings("unchecked") final T... array) {
    850        /*
    851         * @SuppressWarnings used to hide warning about vararg usage. We cannot use @SafeVarargs, since this method is
    852         * not final. Using @SuppressWarnings is fine, because it isn't inherited by subclasses, so each subclass must
    853         * vouch for itself whether its use of 'array' is safe.
    854         */
    855        if (array != null && array.length > 0) {
    856            for (final Object element : array) {
    857                append(element);
    858            }
    859        }
    860        return this;
    861    }
    862
    863    /** Appends {@code "false"}. */
    864    private void appendFalse(int index) {
    865        buffer[index++] = 'f';
    866        buffer[index++] = 'a';
    867        buffer[index++] = 'l';
    868        buffer[index++] = 's';
    869        buffer[index] = 'e';
    870        size += FALSE_STRING_SIZE;
    871    }
    872
    873    /**
    874     * Appends an object to the builder padding on the left to a fixed width. The {@code String.valueOf} of the
    875     * {@code int} value is used. If the formatted value is larger than the length, the left hand side is lost.
    876     *
    877     * @param value the value to append
    878     * @param width the fixed field width, zero or negative has no effect
    879     * @param padChar the pad character to use
    880     * @return this, to enable chaining
    881     */
    882    public TextStringBuilder appendFixedWidthPadLeft(final int value, final int width, final char padChar) {
    883        return appendFixedWidthPadLeft(String.valueOf(value), width, padChar);
    884    }
    885
    886    /**
    887     * Appends an object to the builder padding on the left to a fixed width. The {@code toString} of the object is
    888     * used. If the object is larger than the length, the left hand side is lost. If the object is null, the null text
    889     * value is used.
    890     *
    891     * @param obj the object to append, null uses null text
    892     * @param width the fixed field width, zero or negative has no effect
    893     * @param padChar the pad character to use
    894     * @return this, to enable chaining
    895     */
    896    public TextStringBuilder appendFixedWidthPadLeft(final Object obj, final int width, final char padChar) {
    897        if (width > 0) {
    898            ensureCapacityInternal(size + width);
    899            String str = obj == null ? getNullText() : obj.toString();
    900            if (str == null) {
    901                str = StringUtils.EMPTY;
    902            }
    903            final int strLen = str.length();
    904            if (strLen >= width) {
    905                str.getChars(strLen - width, strLen, buffer, size);
    906            } else {
    907                final int padLen = width - strLen;
    908                for (int i = 0; i < padLen; i++) {
    909                    buffer[size + i] = padChar;
    910                }
    911                str.getChars(0, strLen, buffer, size + padLen);
    912            }
    913            size += width;
    914        }
    915        return this;
    916    }
    917
    918    /**
    919     * Appends an object to the builder padding on the right to a fixed length. The {@code String.valueOf} of the
    920     * {@code int} value is used. If the object is larger than the length, the right hand side is lost.
    921     *
    922     * @param value the value to append
    923     * @param width the fixed field width, zero or negative has no effect
    924     * @param padChar the pad character to use
    925     * @return this, to enable chaining
    926     */
    927    public TextStringBuilder appendFixedWidthPadRight(final int value, final int width, final char padChar) {
    928        return appendFixedWidthPadRight(String.valueOf(value), width, padChar);
    929    }
    930
    931    /**
    932     * Appends an object to the builder padding on the right to a fixed length. The {@code toString} of the object is
    933     * used. If the object is larger than the length, the right hand side is lost. If the object is null, null text
    934     * value is used.
    935     *
    936     * @param obj the object to append, null uses null text
    937     * @param width the fixed field width, zero or negative has no effect
    938     * @param padChar the pad character to use
    939     * @return this, to enable chaining
    940     */
    941    public TextStringBuilder appendFixedWidthPadRight(final Object obj, final int width, final char padChar) {
    942        if (width > 0) {
    943            ensureCapacityInternal(size + width);
    944            String str = obj == null ? getNullText() : obj.toString();
    945            if (str == null) {
    946                str = StringUtils.EMPTY;
    947            }
    948            final int strLen = str.length();
    949            if (strLen >= width) {
    950                str.getChars(0, width, buffer, size);
    951            } else {
    952                final int padLen = width - strLen;
    953                str.getChars(0, strLen, buffer, size);
    954                for (int i = 0; i < padLen; i++) {
    955                    buffer[size + strLen + i] = padChar;
    956                }
    957            }
    958            size += width;
    959        }
    960        return this;
    961    }
    962
    963    /**
    964     * Appends a boolean value followed by a new line to the string builder.
    965     *
    966     * @param value the value to append
    967     * @return this, to enable chaining
    968     */
    969    public TextStringBuilder appendln(final boolean value) {
    970        return append(value).appendNewLine();
    971    }
    972
    973    /**
    974     * Appends a char value followed by a new line to the string builder.
    975     *
    976     * @param ch the value to append
    977     * @return this, to enable chaining
    978     */
    979    public TextStringBuilder appendln(final char ch) {
    980        return append(ch).appendNewLine();
    981    }
    982
    983    /**
    984     * Appends a char array followed by a new line to the string builder. Appending null will call
    985     * {@link #appendNull()}.
    986     *
    987     * @param chars the char array to append
    988     * @return this, to enable chaining
    989     */
    990    public TextStringBuilder appendln(final char[] chars) {
    991        return append(chars).appendNewLine();
    992    }
    993
    994    /**
    995     * Appends a char array followed by a new line to the string builder. Appending null will call
    996     * {@link #appendNull()}.
    997     *
    998     * @param chars the char array to append
    999     * @param startIndex the start index, inclusive, must be valid
    1000     * @param length the length to append, must be valid
    1001     * @return this, to enable chaining
    1002     */
    1003    public TextStringBuilder appendln(final char[] chars, final int startIndex, final int length) {
    1004        return append(chars, startIndex, length).appendNewLine();
    1005    }
    1006
    1007    /**
    1008     * Appends a double value followed by a new line to the string builder using {@code String.valueOf}.
    1009     *
    1010     * @param value the value to append
    1011     * @return this, to enable chaining
    1012     */
    1013    public TextStringBuilder appendln(final double value) {
    1014        return append(value).appendNewLine();
    1015    }
    1016
    1017    /**
    1018     * Appends a float value followed by a new line to the string builder using {@code String.valueOf}.
    1019     *
    1020     * @param value the value to append
    1021     * @return this, to enable chaining
    1022     */
    1023    public TextStringBuilder appendln(final float value) {
    1024        return append(value).appendNewLine();
    1025    }
    1026
    1027    /**
    1028     * Appends an int value followed by a new line to the string builder using {@code String.valueOf}.
    1029     *
    1030     * @param value the value to append
    1031     * @return this, to enable chaining
    1032     */
    1033    public TextStringBuilder appendln(final int value) {
    1034        return append(value).appendNewLine();
    1035    }
    1036
    1037    /**
    1038     * Appends a long value followed by a new line to the string builder using {@code String.valueOf}.
    1039     *
    1040     * @param value the value to append
    1041     * @return this, to enable chaining
    1042     */
    1043    public TextStringBuilder appendln(final long value) {
    1044        return append(value).appendNewLine();
    1045    }
    1046
    1047    /**
    1048     * Appends an object followed by a new line to this string builder. Appending null will call {@link #appendNull()}.
    1049     *
    1050     * @param obj the object to append
    1051     * @return this, to enable chaining
    1052     */
    1053    public TextStringBuilder appendln(final Object obj) {
    1054        return append(obj).appendNewLine();
    1055    }
    1056
    1057    /**
    1058     * Appends a string followed by a new line to this string builder. Appending null will call {@link #appendNull()}.
    1059     *
    1060     * @param str the string to append
    1061     * @return this, to enable chaining
    1062     */
    1063    public TextStringBuilder appendln(final String str) {
    1064        return append(str).appendNewLine();
    1065    }
    1066
    1067    /**
    1068     * Appends part of a string followed by a new line to this string builder. Appending null will call
    1069     * {@link #appendNull()}.
    1070     *
    1071     * @param str the string to append
    1072     * @param startIndex the start index, inclusive, must be valid
    1073     * @param length the length to append, must be valid
    1074     * @return this, to enable chaining
    1075     */
    1076    public TextStringBuilder appendln(final String str, final int startIndex, final int length) {
    1077        return append(str, startIndex, length).appendNewLine();
    1078    }
    1079
    1080    /**
    1081     * Calls {@link String#format(String, Object...)} and appends the result.
    1082     *
    1083     * @param format the format string
    1084     * @param objs the objects to use in the format string
    1085     * @return {@code this} to enable chaining
    1086     * @see String#format(String, Object...)
    1087     */
    1088    public TextStringBuilder appendln(final String format, final Object... objs) {
    1089        return append(format, objs).appendNewLine();
    1090    }
    1091
    1092    /**
    1093     * Appends a string buffer followed by a new line to this string builder. Appending null will call
    1094     * {@link #appendNull()}.
    1095     *
    1096     * @param str the string buffer to append
    1097     * @return this, to enable chaining
    1098     */
    1099    public TextStringBuilder appendln(final StringBuffer str) {
    1100        return append(str).appendNewLine();
    1101    }
    1102
    1103    /**
    1104     * Appends part of a string buffer followed by a new line to this string builder. Appending null will call
    1105     * {@link #appendNull()}.
    1106     *
    1107     * @param str the string to append
    1108     * @param startIndex the start index, inclusive, must be valid
    1109     * @param length the length to append, must be valid
    1110     * @return this, to enable chaining
    1111     */
    1112    public TextStringBuilder appendln(final StringBuffer str, final int startIndex, final int length) {
    1113        return append(str, startIndex, length).appendNewLine();
    1114    }
    1115
    1116    /**
    1117     * Appends a string builder followed by a new line to this string builder. Appending null will call
    1118     * {@link #appendNull()}.
    1119     *
    1120     * @param str the string builder to append
    1121     * @return this, to enable chaining
    1122     */
    1123    public TextStringBuilder appendln(final StringBuilder str) {
    1124        return append(str).appendNewLine();
    1125    }
    1126
    1127    /**
    1128     * Appends part of a string builder followed by a new line to this string builder. Appending null will call
    1129     * {@link #appendNull()}.
    1130     *
    1131     * @param str the string builder to append
    1132     * @param startIndex the start index, inclusive, must be valid
    1133     * @param length the length to append, must be valid
    1134     * @return this, to enable chaining
    1135     */
    1136    public TextStringBuilder appendln(final StringBuilder str, final int startIndex, final int length) {
    1137        return append(str, startIndex, length).appendNewLine();
    1138    }
    1139
    1140    /**
    1141     * Appends another string builder followed by a new line to this string builder. Appending null will call
    1142     * {@link #appendNull()}.
    1143     *
    1144     * @param str the string builder to append
    1145     * @return this, to enable chaining
    1146     */
    1147    public TextStringBuilder appendln(final TextStringBuilder str) {
    1148        return append(str).appendNewLine();
    1149    }
    1150
    1151    /**
    1152     * Appends part of a string builder followed by a new line to this string builder. Appending null will call
    1153     * {@link #appendNull()}.
    1154     *
    1155     * @param str the string to append
    1156     * @param startIndex the start index, inclusive, must be valid
    1157     * @param length the length to append, must be valid
    1158     * @return this, to enable chaining
    1159     */
    1160    public TextStringBuilder appendln(final TextStringBuilder str, final int startIndex, final int length) {
    1161        return append(str, startIndex, length).appendNewLine();
    1162    }
    1163
    1164    /**
    1165     * Appends the new line string to this string builder.
    1166     * <p>
    1167     * The new line string can be altered using {@link #setNewLineText(String)}. This might be used to force the output
    1168     * to always use Unix line endings even when on Windows.
    1169     * </p>
    1170     *
    1171     * @return this, to enable chaining
    1172     */
    1173    public TextStringBuilder appendNewLine() {
    1174        if (newLine == null) {
    1175            append(System.lineSeparator());
    1176            return this;
    1177        }
    1178        return append(newLine);
    1179    }
    1180
    1181    /**
    1182     * Appends the text representing {@code null} to this string builder.
    1183     *
    1184     * @return this, to enable chaining
    1185     */
    1186    public TextStringBuilder appendNull() {
    1187        if (nullText == null) {
    1188            return this;
    1189        }
    1190        return append(nullText);
    1191    }
    1192
    1193    /**
    1194     * Appends the pad character to the builder the specified number of times.
    1195     *
    1196     * @param length the length to append, negative means no append
    1197     * @param padChar the character to append
    1198     * @return this, to enable chaining
    1199     */
    1200    public TextStringBuilder appendPadding(final int length, final char padChar) {
    1201        if (length >= 0) {
    1202            ensureCapacityInternal(size + length);
    1203            for (int i = 0; i < length; i++) {
    1204                buffer[size++] = padChar;
    1205            }
    1206        }
    1207        return this;
    1208    }
    1209
    1210    /**
    1211     * Appends a separator if the builder is currently non-empty. The separator is appended using {@link #append(char)}.
    1212     * <p>
    1213     * This method is useful for adding a separator each time around the loop except the first.
    1214     * </p>
    1215     *
    1216     * <pre>
    1217     * for (Iterator it = list.iterator(); it.hasNext();) {
    1218     *     appendSeparator(',');
    1219     *     append(it.next());
    1220     * }
    1221     * </pre>
    1222     *
    1223     * <p>
    1224     * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}.
    1225     * </p>
    1226     *
    1227     * @param separator the separator to use
    1228     * @return this, to enable chaining
    1229     */
    1230    public TextStringBuilder appendSeparator(final char separator) {
    1231        if (isNotEmpty()) {
    1232            append(separator);
    1233        }
    1234        return this;
    1235    }
    1236
    1237    /**
    1238     * Appends one of both separators to the builder If the builder is currently empty it will append the
    1239     * defaultIfEmpty-separator Otherwise it will append the standard-separator
    1240     *
    1241     * The separator is appended using {@link #append(char)}.
    1242     *
    1243     * @param standard the separator if builder is not empty
    1244     * @param defaultIfEmpty the separator if builder is empty
    1245     * @return this, to enable chaining
    1246     */
    1247    public TextStringBuilder appendSeparator(final char standard, final char defaultIfEmpty) {
    1248        if (isEmpty()) {
    1249            append(defaultIfEmpty);
    1250        } else {
    1251            append(standard);
    1252        }
    1253        return this;
    1254    }
    1255
    1256    /**
    1257     * Appends a separator to the builder if the loop index is greater than zero. The separator is appended using
    1258     * {@link #append(char)}.
    1259     * <p>
    1260     * This method is useful for adding a separator each time around the loop except the first.
    1261     * </p>
    1262     *
    1263     * <pre>
    1264     * for (int i = 0; i &lt; list.size(); i++) {
    1265     *     appendSeparator(",", i);
    1266     *     append(list.get(i));
    1267     * }
    1268     * </pre>
    1269     *
    1270     * <p>
    1271     * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}.
    1272     * </p>
    1273     *
    1274     * @param separator the separator to use
    1275     * @param loopIndex the loop index
    1276     * @return this, to enable chaining
    1277     */
    1278    public TextStringBuilder appendSeparator(final char separator, final int loopIndex) {
    1279        if (loopIndex > 0) {
    1280            append(separator);
    1281        }
    1282        return this;
    1283    }
    1284
    1285    /**
    1286     * Appends a separator if the builder is currently non-empty. Appending a null separator will have no effect. The
    1287     * separator is appended using {@link #append(String)}.
    1288     * <p>
    1289     * This method is useful for adding a separator each time around the loop except the first.
    1290     * </p>
    1291     *
    1292     * <pre>
    1293     * for (Iterator it = list.iterator(); it.hasNext();) {
    1294     *     appendSeparator(",");
    1295     *     append(it.next());
    1296     * }
    1297     * </pre>
    1298     *
    1299     * <p>
    1300     * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}.
    1301     * </p>
    1302     *
    1303     * @param separator the separator to use, null means no separator
    1304     * @return this, to enable chaining
    1305     */
    1306    public TextStringBuilder appendSeparator(final String separator) {
    1307        return appendSeparator(separator, null);
    1308    }
    1309
    1310    /**
    1311     * Appends a separator to the builder if the loop index is greater than zero. Appending a null separator will have
    1312     * no effect. The separator is appended using {@link #append(String)}.
    1313     * <p>
    1314     * This method is useful for adding a separator each time around the loop except the first.
    1315     * </p>
    1316     *
    1317     * <pre>
    1318     * for (int i = 0; i &lt; list.size(); i++) {
    1319     *     appendSeparator(",", i);
    1320     *     append(list.get(i));
    1321     * }
    1322     * </pre>
    1323     *
    1324     * <p>
    1325     * Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}.
    1326     * </p>
    1327     *
    1328     * @param separator the separator to use, null means no separator
    1329     * @param loopIndex the loop index
    1330     * @return this, to enable chaining
    1331     */
    1332    public TextStringBuilder appendSeparator(final String separator, final int loopIndex) {
    1333        if (separator != null && loopIndex > 0) {
    1334            append(separator);
    1335        }
    1336        return this;
    1337    }
    1338
    1339    /**
    1340     * Appends one of both separators to the StrBuilder. If the builder is currently empty, it will append the
    1341     * defaultIfEmpty-separator, otherwise it will append the standard-separator.
    1342     * <p>
    1343     * Appending a null separator will have no effect. The separator is appended using {@link #append(String)}.
    1344     * </p>
    1345     * <p>
    1346     * This method is for example useful for constructing queries
    1347     * </p>
    1348     *
    1349     * <pre>
    1350     * StrBuilder whereClause = new StrBuilder();
    1351     * if (searchCommand.getPriority() != null) {
    1352     *  whereClause.appendSeparator(" and", " where");
    1353     *  whereClause.append(" priority = ?")
    1354     * }
    1355     * if (searchCommand.getComponent() != null) {
    1356     *  whereClause.appendSeparator(" and", " where");
    1357     *  whereClause.append(" component = ?")
    1358     * }
    1359     * selectClause.append(whereClause)
    1360     * </pre>
    1361     *
    1362     * @param standard the separator if builder is not empty, null means no separator
    1363     * @param defaultIfEmpty the separator if builder is empty, null means no separator
    1364     * @return this, to enable chaining
    1365     */
    1366    public TextStringBuilder appendSeparator(final String standard, final String defaultIfEmpty) {
    1367        final String str = isEmpty() ? defaultIfEmpty : standard;
    1368        if (str != null) {
    1369            append(str);
    1370        }
    1371        return this;
    1372    }
    1373
    1374    /**
    1375     * Appends current contents of this {@code StrBuilder} to the provided {@link Appendable}.
    1376     * <p>
    1377     * This method tries to avoid doing any extra copies of contents.
    1378     * </p>
    1379     *
    1380     * @param appendable the appendable to append data to
    1381     * @throws IOException if an I/O error occurs.
    1382     *
    1383     * @see #readFrom(Readable)
    1384     */
    1385    public void appendTo(final Appendable appendable) throws IOException {
    1386        if (appendable instanceof Writer) {
    1387            ((Writer) appendable).write(buffer, 0, size);
    1388        } else if (appendable instanceof StringBuilder) {
    1389            ((StringBuilder) appendable).append(buffer, 0, size);
    1390        } else if (appendable instanceof StringBuffer) {
    1391            ((StringBuffer) appendable).append(buffer, 0, size);
    1392        } else if (appendable instanceof CharBuffer) {
    1393            ((CharBuffer) appendable).put(buffer, 0, size);
    1394        } else {
    1395            appendable.append(this);
    1396        }
    1397    }
    1398
    1399    /** Appends {@code "true"}. */
    1400    private void appendTrue(int index) {
    1401        buffer[index++] = 't';
    1402        buffer[index++] = 'r';
    1403        buffer[index++] = 'u';
    1404        buffer[index] = 'e';
    1405        size += TRUE_STRING_SIZE;
    1406    }
    1407
    1408    /**
    1409     * Appends an iterable placing separators between each value, but not before the first or after the last. Appending
    1410     * a null iterable will have no effect. Each object is appended using {@link #append(Object)}.
    1411     *
    1412     * @param iterable the iterable to append
    1413     * @param separator the separator to use, null means no separator
    1414     * @return this, to enable chaining
    1415     */
    1416    public TextStringBuilder appendWithSeparators(final Iterable<?> iterable, final String separator) {
    1417        if (iterable != null) {
    1418            appendWithSeparators(iterable.iterator(), separator);
    1419        }
    1420        return this;
    1421    }
    1422
    1423    /**
    1424     * Appends an iterator placing separators between each value, but not before the first or after the last. Appending
    1425     * a null iterator will have no effect. Each object is appended using {@link #append(Object)}.
    1426     *
    1427     * @param it the iterator to append
    1428     * @param separator the separator to use, null means no separator
    1429     * @return this, to enable chaining
    1430     */
    1431    public TextStringBuilder appendWithSeparators(final Iterator<?> it, final String separator) {
    1432        if (it != null) {
    1433            final String sep = Objects.toString(separator, StringUtils.EMPTY);
    1434            while (it.hasNext()) {
    1435                append(it.next());
    1436                if (it.hasNext()) {
    1437                    append(sep);
    1438                }
    1439            }
    1440        }
    1441        return this;
    1442    }
    1443
    1444    /**
    1445     * Appends an array placing separators between each value, but not before the first or after the last. Appending a
    1446     * null array will have no effect. Each object is appended using {@link #append(Object)}.
    1447     *
    1448     * @param array the array to append
    1449     * @param separator the separator to use, null means no separator
    1450     * @return this, to enable chaining
    1451     */
    1452    public TextStringBuilder appendWithSeparators(final Object[] array, final String separator) {
    1453        if (array != null && array.length > 0) {
    1454            final String sep = Objects.toString(separator, StringUtils.EMPTY);
    1455            append(array[0]);
    1456            for (int i = 1; i < array.length; i++) {
    1457                append(sep);
    1458                append(array[i]);
    1459            }
    1460        }
    1461        return this;
    1462    }
    1463
    1464    /**
    1465     * Gets the contents of this builder as a Reader.
    1466     * <p>
    1467     * This method allows the contents of the builder to be read using any standard method that expects a Reader.
    1468     * </p>
    1469     * <p>
    1470     * To use, simply create a {@code StrBuilder}, populate it with data, call {@code asReader}, and then read away.
    1471     * </p>
    1472     * <p>
    1473     * The internal character array is shared between the builder and the reader. This allows you to append to the
    1474     * builder after creating the reader, and the changes will be picked up. Note however, that no synchronization
    1475     * occurs, so you must perform all operations with the builder and the reader in one thread.
    1476     * </p>
    1477     * <p>
    1478     * The returned reader supports marking, and ignores the flush method.
    1479     * </p>
    1480     *
    1481     * @return a reader that reads from this builder
    1482     */
    1483    public Reader asReader() {
    1484        return new TextStringBuilderReader();
    1485    }
    1486
    1487    /**
    1488     * Creates a tokenizer that can tokenize the contents of this builder.
    1489     * <p>
    1490     * This method allows the contents of this builder to be tokenized. The tokenizer will be setup by default to
    1491     * tokenize on space, tab, newline and form feed (as per StringTokenizer). These values can be changed on the
    1492     * tokenizer class, before retrieving the tokens.
    1493     * </p>
    1494     * <p>
    1495     * The returned tokenizer is linked to this builder. You may intermix calls to the builder and tokenizer within
    1496     * certain limits, however there is no synchronization. Once the tokenizer has been used once, it must be
    1497     * {@link StringTokenizer#reset() reset} to pickup the latest changes in the builder. For example:
    1498     * </p>
    1499     *
    1500     * <pre>
    1501     * StrBuilder b = new StrBuilder();
    1502     * b.append("a b ");
    1503     * StrTokenizer t = b.asTokenizer();
    1504     * String[] tokens1 = t.getTokenArray(); // returns a,b
    1505     * b.append("c d ");
    1506     * String[] tokens2 = t.getTokenArray(); // returns a,b (c and d ignored)
    1507     * t.reset(); // reset causes builder changes to be picked up
    1508     * String[] tokens3 = t.getTokenArray(); // returns a,b,c,d
    1509     * </pre>
    1510     *
    1511     * <p>
    1512     * In addition to simply intermixing appends and tokenization, you can also call the set methods on the tokenizer to
    1513     * alter how it tokenizes. Just remember to call reset when you want to pickup builder changes.
    1514     * </p>
    1515     * <p>
    1516     * Calling {@link StringTokenizer#reset(String)} or {@link StringTokenizer#reset(char[])} with a non-null value will
    1517     * break the link with the builder.
    1518     * </p>
    1519     *
    1520     * @return a tokenizer that is linked to this builder
    1521     */
    1522    public StringTokenizer asTokenizer() {
    1523        return new TextStringBuilderTokenizer();
    1524    }
    1525
    1526    /**
    1527     * Gets this builder as a Writer that can be written to.
    1528     * <p>
    1529     * This method allows you to populate the contents of the builder using any standard method that takes a Writer.
    1530     * </p>
    1531     * <p>
    1532     * To use, simply create a {@code StrBuilder}, call {@code asWriter}, and populate away. The data is available at
    1533     * any time using the methods of the {@code StrBuilder}.
    1534     * </p>
    1535     * <p>
    1536     * The internal character array is shared between the builder and the writer. This allows you to intermix calls that
    1537     * append to the builder and write using the writer and the changes will be occur correctly. Note however, that no
    1538     * synchronization occurs, so you must perform all operations with the builder and the writer in one thread.
    1539     * </p>
    1540     * <p>
    1541     * The returned writer ignores the close and flush methods.
    1542     * </p>
    1543     *
    1544     * @return a writer that populates this builder
    1545     */
    1546    public Writer asWriter() {
    1547        return new TextStringBuilderWriter();
    1548    }
    1549
    1550    /**
    1551     * Implement the {@link Builder} interface.
    1552     *
    1553     * @return The builder as a String
    1554     * @see #toString()
    1555     */
    1556    @Override
    1557    public String build() {
    1558        return toString();
    1559    }
    1560
    1561    /**
    1562     * Gets the current size of the internal character array buffer.
    1563     *
    1564     * @return The capacity
    1565     */
    1566    public int capacity() {
    1567        return buffer.length;
    1568    }
    1569
    1570    /**
    1571     * Gets the character at the specified index.
    1572     *
    1573     * @see #setCharAt(int, char)
    1574     * @see #deleteCharAt(int)
    1575     * @param index the index to retrieve, must be valid
    1576     * @return The character at the index
    1577     * @throws IndexOutOfBoundsException if the index is invalid
    1578     */
    1579    @Override
    1580    public char charAt(final int index) {
    1581        validateIndex(index);
    1582        return buffer[index];
    1583    }
    1584
    1585    /**
    1586     * Clears the string builder (convenience Collections API style method).
    1587     * <p>
    1588     * This method does not reduce the size of the internal character buffer. To do that, call {@code clear()} followed
    1589     * by {@link #minimizeCapacity()}.
    1590     * </p>
    1591     * <p>
    1592     * This method is the same as {@link #setLength(int)} called with zero and is provided to match the API of
    1593     * Collections.
    1594     * </p>
    1595     *
    1596     * @return this, to enable chaining
    1597     */
    1598    public TextStringBuilder clear() {
    1599        size = 0;
    1600        return this;
    1601    }
    1602
    1603    /**
    1604     * Tests if the string builder contains the specified char.
    1605     *
    1606     * @param ch the character to find
    1607     * @return true if the builder contains the character
    1608     */
    1609    public boolean contains(final char ch) {
    1610        final char[] thisBuf = buffer;
    1611        for (int i = 0; i < this.size; i++) {
    1612            if (thisBuf[i] == ch) {
    1613                return true;
    1614            }
    1615        }
    1616        return false;
    1617    }
    1618
    1619    /**
    1620     * Tests if the string builder contains the specified string.
    1621     *
    1622     * @param str the string to find
    1623     * @return true if the builder contains the string
    1624     */
    1625    public boolean contains(final String str) {
    1626        return indexOf(str, 0) >= 0;
    1627    }
    1628
    1629    /**
    1630     * Tests if the string builder contains a string matched using the specified matcher.
    1631     * <p>
    1632     * Matchers can be used to perform advanced searching behavior. For example you could write a matcher to search for
    1633     * the character 'a' followed by a number.
    1634     * </p>
    1635     *
    1636     * @param matcher the matcher to use, null returns -1
    1637     * @return true if the matcher finds a match in the builder
    1638     */
    1639    public boolean contains(final StringMatcher matcher) {
    1640        return indexOf(matcher, 0) >= 0;
    1641    }
    1642
    1643    /**
    1644     * Deletes the characters between the two specified indices.
    1645     *
    1646     * @param startIndex the start index, inclusive, must be valid
    1647     * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string
    1648     * @return this, to enable chaining
    1649     * @throws IndexOutOfBoundsException if the index is invalid
    1650     */
    1651    public TextStringBuilder delete(final int startIndex, final int endIndex) {
    1652        final int actualEndIndex = validateRange(startIndex, endIndex);
    1653        final int len = actualEndIndex - startIndex;
    1654        if (len > 0) {
    1655            deleteImpl(startIndex, actualEndIndex, len);
    1656        }
    1657        return this;
    1658    }
    1659
    1660    /**
    1661     * Deletes the character wherever it occurs in the builder.
    1662     *
    1663     * @param ch the character to delete
    1664     * @return this, to enable chaining
    1665     */
    1666    public TextStringBuilder deleteAll(final char ch) {
    1667        for (int i = 0; i < size; i++) {
    1668            if (buffer[i] == ch) {
    1669                final int start = i;
    1670                while (++i < size) {
    1671                    if (buffer[i] != ch) {
    1672                        break;
    1673                    }
    1674                }
    1675                final int len = i - start;
    1676                deleteImpl(start, i, len);
    1677                i -= len;
    1678            }
    1679        }
    1680        return this;
    1681    }
    1682
    1683    /**
    1684     * Deletes the string wherever it occurs in the builder.
    1685     *
    1686     * @param str the string to delete, null causes no action
    1687     * @return this, to enable chaining
    1688     */
    1689    public TextStringBuilder deleteAll(final String str) {
    1690        final int len = str == null ? 0 : str.length();
    1691        if (len > 0) {
    1692            int index = indexOf(str, 0);
    1693            while (index >= 0) {
    1694                deleteImpl(index, index + len, len);
    1695                index = indexOf(str, index);
    1696            }
    1697        }
    1698        return this;
    1699    }
    1700
    1701    /**
    1702     * Deletes all parts of the builder that the matcher matches.
    1703     * <p>
    1704     * Matchers can be used to perform advanced deletion behavior. For example you could write a matcher to delete all
    1705     * occurrences where the character 'a' is followed by a number.
    1706     * </p>
    1707     *
    1708     * @param matcher the matcher to use to find the deletion, null causes no action
    1709     * @return this, to enable chaining
    1710     */
    1711    public TextStringBuilder deleteAll(final StringMatcher matcher) {
    1712        return replace(matcher, null, 0, size, -1);
    1713    }
    1714
    1715    /**
    1716     * Deletes the character at the specified index.
    1717     *
    1718     * @see #charAt(int)
    1719     * @see #setCharAt(int, char)
    1720     * @param index the index to delete
    1721     * @return this, to enable chaining
    1722     * @throws IndexOutOfBoundsException if the index is invalid
    1723     */
    1724    public TextStringBuilder deleteCharAt(final int index) {
    1725        validateIndex(index);
    1726        deleteImpl(index, index + 1, 1);
    1727        return this;
    1728    }
    1729
    1730    /**
    1731     * Deletes the character wherever it occurs in the builder.
    1732     *
    1733     * @param ch the character to delete
    1734     * @return this, to enable chaining
    1735     */
    1736    public TextStringBuilder deleteFirst(final char ch) {
    1737        for (int i = 0; i < size; i++) {
    1738            if (buffer[i] == ch) {
    1739                deleteImpl(i, i + 1, 1);
    1740                break;
    1741            }
    1742        }
    1743        return this;
    1744    }
    1745
    1746    /**
    1747     * Deletes the string wherever it occurs in the builder.
    1748     *
    1749     * @param str the string to delete, null causes no action
    1750     * @return this, to enable chaining
    1751     */
    1752    public TextStringBuilder deleteFirst(final String str) {
    1753        final int len = str == null ? 0 : str.length();
    1754        if (len > 0) {
    1755            final int index = indexOf(str, 0);
    1756            if (index >= 0) {
    1757                deleteImpl(index, index + len, len);
    1758            }
    1759        }
    1760        return this;
    1761    }
    1762
    1763    /**
    1764     * Deletes the first match within the builder using the specified matcher.
    1765     * <p>
    1766     * Matchers can be used to perform advanced deletion behavior. For example you could write a matcher to delete where
    1767     * the character 'a' is followed by a number.
    1768     * </p>
    1769     *
    1770     * @param matcher the matcher to use to find the deletion, null causes no action
    1771     * @return this, to enable chaining
    1772     */
    1773    public TextStringBuilder deleteFirst(final StringMatcher matcher) {
    1774        return replace(matcher, null, 0, size, 1);
    1775    }
    1776
    1777    /**
    1778     * Internal method to delete a range without validation.
    1779     *
    1780     * @param startIndex the start index, must be valid
    1781     * @param endIndex the end index (exclusive), must be valid
    1782     * @param len the length, must be valid
    1783     * @throws IndexOutOfBoundsException if any index is invalid
    1784     */
    1785    private void deleteImpl(final int startIndex, final int endIndex, final int len) {
    1786        System.arraycopy(buffer, endIndex, buffer, startIndex, size - endIndex);
    1787        size -= len;
    1788    }
    1789
    1790    /**
    1791     * Gets the character at the specified index before deleting it.
    1792     *
    1793     * @see #charAt(int)
    1794     * @see #deleteCharAt(int)
    1795     * @param index the index to retrieve, must be valid
    1796     * @return The character at the index
    1797     * @throws IndexOutOfBoundsException if the index is invalid
    1798     * @since 1.9
    1799     */
    1800    public char drainChar(final int index) {
    1801        validateIndex(index);
    1802        final char c = buffer[index];
    1803        deleteCharAt(index);
    1804        return c;
    1805    }
    1806
    1807    /**
    1808     * Drains (copies, then deletes) this character sequence into the specified array. This is equivalent to copying the
    1809     * characters from this sequence into the target and then deleting those character from this sequence.
    1810     *
    1811     * @param startIndex first index to copy, inclusive.
    1812     * @param endIndex last index to copy, exclusive.
    1813     * @param target the target array, must not be {@code null}.
    1814     * @param targetIndex the index to start copying in the target.
    1815     * @return How many characters where copied (then deleted). If this builder is empty, return {@code 0}.
    1816     * @since 1.9
    1817     */
    1818    public int drainChars(final int startIndex, final int endIndex, final char[] target, final int targetIndex) {
    1819        final int length = endIndex - startIndex;
    1820        if (isEmpty() || length == 0 || target.length == 0) {
    1821            return 0;
    1822        }
    1823        final int actualLen = Math.min(Math.min(size, length), target.length - targetIndex);
    1824        getChars(startIndex, actualLen, target, targetIndex);
    1825        delete(startIndex, actualLen);
    1826        return actualLen;
    1827    }
    1828
    1829    /**
    1830     * Checks whether this builder ends with the specified string.
    1831     * <p>
    1832     * Note that this method handles null input quietly, unlike String.
    1833     * </p>
    1834     *
    1835     * @param str the string to search for, null returns false
    1836     * @return true if the builder ends with the string
    1837     */
    1838    public boolean endsWith(final String str) {
    1839        if (str == null) {
    1840            return false;
    1841        }
    1842        final int len = str.length();
    1843        if (len == 0) {
    1844            return true;
    1845        }
    1846        if (len > size) {
    1847            return false;
    1848        }
    1849        int pos = size - len;
    1850        for (int i = 0; i < len; i++, pos++) {
    1851            if (buffer[pos] != str.charAt(i)) {
    1852                return false;
    1853            }
    1854        }
    1855        return true;
    1856    }
    1857
    1858    /**
    1859     * Tests the capacity and ensures that it is at least the size specified.
    1860     *
    1861     * <p>
    1862     * Note: This method can be used to minimise memory reallocations during
    1863     * repeated addition of values by pre-allocating the character buffer.
    1864     * The method ignores a negative {@code capacity} argument.
    1865     * </p>
    1866     *
    1867     * @param capacity the capacity to ensure
    1868     * @return this, to enable chaining
    1869     * @throws OutOfMemoryError if the capacity cannot be allocated
    1870     */
    1871    public TextStringBuilder ensureCapacity(final int capacity) {
    1872        if (capacity > 0) {
    1873            ensureCapacityInternal(capacity);
    1874        }
    1875        return this;
    1876    }
    1877
    1878    /**
    1879     * Ensures that the buffer is at least the size specified. The {@code capacity} argument
    1880     * is treated as an unsigned integer.
    1881     *
    1882     * <p>
    1883     * This method will raise an {@link OutOfMemoryError} if the capacity is too large
    1884     * for an array, or cannot be allocated.
    1885     * </p>
    1886     *
    1887     * @param capacity the capacity to ensure
    1888     * @throws OutOfMemoryError if the capacity cannot be allocated
    1889     */
    1890    private void ensureCapacityInternal(final int capacity) {
    1891        // Check for overflow of the current buffer.
    1892        // Assumes capacity is an unsigned integer up to Integer.MAX_VALUE * 2
    1893        // (the largest possible addition of two maximum length arrays).
    1894        if (capacity - buffer.length > 0) {
    1895            resizeBuffer(capacity);
    1896        }
    1897    }
    1898
    1899    /**
    1900     * Tests the contents of this builder against another to see if they contain the same character content.
    1901     *
    1902     * @param obj the object to check, null returns false
    1903     * @return true if the builders contain the same characters in the same order
    1904     */
    1905    @Override
    1906    public boolean equals(final Object obj) {
    1907        return obj instanceof TextStringBuilder && equals((TextStringBuilder) obj);
    1908    }
    1909
    1910    /**
    1911     * Tests the contents of this builder against another to see if they contain the same character content.
    1912     *
    1913     * @param other the object to check, null returns false
    1914     * @return true if the builders contain the same characters in the same order
    1915     */
    1916    public boolean equals(final TextStringBuilder other) {
    1917        if (this == other) {
    1918            return true;
    1919        }
    1920        if (other == null) {
    1921            return false;
    1922        }
    1923        if (this.size != other.size) {
    1924            return false;
    1925        }
    1926        // Be aware not to use Arrays.equals(buffer, other.buffer) for equals() method
    1927        // as length of the buffers may be different (TEXT-211)
    1928        final char[] thisBuf = this.buffer;
    1929        final char[] otherBuf = other.buffer;
    1930        for (int i = size - 1; i >= 0; i--) {
    1931            if (thisBuf[i] != otherBuf[i]) {
    1932                return false;
    1933            }
    1934        }
    1935        return true;
    1936    }
    1937
    1938    /**
    1939     * Tests the contents of this builder against another to see if they contain the same character content ignoring
    1940     * case.
    1941     *
    1942     * @param other the object to check, null returns false
    1943     * @return true if the builders contain the same characters in the same order
    1944     */
    1945    public boolean equalsIgnoreCase(final TextStringBuilder other) {
    1946        if (this == other) {
    1947            return true;
    1948        }
    1949        if (this.size != other.size) {
    1950            return false;
    1951        }
    1952        final char[] thisBuf = this.buffer;
    1953        final char[] otherBuf = other.buffer;
    1954        for (int i = size - 1; i >= 0; i--) {
    1955            final char c1 = thisBuf[i];
    1956            final char c2 = otherBuf[i];
    1957            if (c1 != c2 && Character.toUpperCase(c1) != Character.toUpperCase(c2)) {
    1958                return false;
    1959            }
    1960        }
    1961        return true;
    1962    }
    1963
    1964    /** Gets a direct reference to internal storage, not for public consumption. */
    1965    char[] getBuffer() {
    1966        return buffer;
    1967    }
    1968
    1969    /**
    1970     * Copies this character array into the specified array.
    1971     *
    1972     * @param target the target array, null will cause an array to be created
    1973     * @return The input array, unless that was null or too small
    1974     */
    1975    public char[] getChars(char[] target) {
    1976        final int len = length();
    1977        if (target == null || target.length < len) {
    1978            target = new char[len];
    1979        }
    1980        System.arraycopy(buffer, 0, target, 0, len);
    1981        return target;
    1982    }
    1983
    1984    /**
    1985     * Copies this character array into the specified array.
    1986     *
    1987     * @param startIndex first index to copy, inclusive, must be valid.
    1988     * @param endIndex last index to copy, exclusive, must be valid.
    1989     * @param target the target array, must not be null or too small.
    1990     * @param targetIndex the index to start copying in target.
    1991     * @throws NullPointerException if the array is null.
    1992     * @throws IndexOutOfBoundsException if any index is invalid.
    1993     */
    1994    public void getChars(final int startIndex, final int endIndex, final char[] target, final int targetIndex) {
    1995        if (startIndex < 0) {
    1996            throw new StringIndexOutOfBoundsException(startIndex);
    1997        }
    1998        if (endIndex < 0 || endIndex > length()) {
    1999            throw new StringIndexOutOfBoundsException(endIndex);
    2000        }
    2001        if (startIndex > endIndex) {
    2002            throw new StringIndexOutOfBoundsException("end < start");
    2003        }
    2004        System.arraycopy(buffer, startIndex, target, targetIndex, endIndex - startIndex);
    2005    }
    2006
    2007    /**
    2008     * Gets the text to be appended when a new line is added.
    2009     *
    2010     * @return The new line text, null means use system default
    2011     */
    2012    public String getNewLineText() {
    2013        return newLine;
    2014    }
    2015
    2016    /**
    2017     * Gets the text to be appended when null is added.
    2018     *
    2019     * @return The null text, null means no append
    2020     */
    2021    public String getNullText() {
    2022        return nullText;
    2023    }
    2024
    2025    /**
    2026     * Gets a suitable hash code for this builder.
    2027     *
    2028     * @return a hash code
    2029     */
    2030    @Override
    2031    public int hashCode() {
    2032        // no allocation
    2033        final char[] buf = buffer;
    2034        int result = 0;
    2035        for (int i = 0; i < size; i++) {
    2036            result = 31 * result + buf[i];
    2037        }
    2038        return result;
    2039    }
    2040
    2041    /**
    2042     * Searches the string builder to find the first reference to the specified char.
    2043     *
    2044     * @param ch the character to find
    2045     * @return The first index of the character, or -1 if not found
    2046     */
    2047    public int indexOf(final char ch) {
    2048        return indexOf(ch, 0);
    2049    }
    2050
    2051    /**
    2052     * Searches the string builder to find the first reference to the specified char.
    2053     *
    2054     * @param ch the character to find
    2055     * @param startIndex the index to start at, invalid index rounded to edge
    2056     * @return The first index of the character, or -1 if not found
    2057     */
    2058    public int indexOf(final char ch, int startIndex) {
    2059        startIndex = Math.max(0, startIndex);
    2060        if (startIndex >= size) {
    2061            return StringUtils.INDEX_NOT_FOUND;
    2062        }
    2063        final char[] thisBuf = buffer;
    2064        for (int i = startIndex; i < size; i++) {
    2065            if (thisBuf[i] == ch) {
    2066                return i;
    2067            }
    2068        }
    2069        return StringUtils.INDEX_NOT_FOUND;
    2070    }
    2071
    2072    /**
    2073     * Searches the string builder to find the first reference to the specified string.
    2074     * <p>
    2075     * Note that a null input string will return -1, whereas the JDK throws an exception.
    2076     * </p>
    2077     *
    2078     * @param str the string to find, null returns -1
    2079     * @return The first index of the string, or -1 if not found
    2080     */
    2081    public int indexOf(final String str) {
    2082        return indexOf(str, 0);
    2083    }
    2084
    2085    /**
    2086     * Searches the string builder to find the first reference to the specified string starting searching from the given
    2087     * index.
    2088     * <p>
    2089     * Note that a null input string will return -1, whereas the JDK throws an exception.
    2090     * </p>
    2091     *
    2092     * @param str the string to find, null returns -1
    2093     * @param startIndex the index to start at, invalid index rounded to edge
    2094     * @return The first index of the string, or -1 if not found
    2095     */
    2096    public int indexOf(final String str, int startIndex) {
    2097        startIndex = Math.max(0, startIndex);
    2098        if (str == null || startIndex >= size) {
    2099            return StringUtils.INDEX_NOT_FOUND;
    2100        }
    2101        final int strLen = str.length();
    2102        if (strLen == 1) {
    2103            return indexOf(str.charAt(0), startIndex);
    2104        }
    2105        if (strLen == 0) {
    2106            return startIndex;
    2107        }
    2108        if (strLen > size) {
    2109            return StringUtils.INDEX_NOT_FOUND;
    2110        }
    2111        final char[] thisBuf = buffer;
    2112        final int len = size - strLen + 1;
    2113        outer: for (int i = startIndex; i < len; i++) {
    2114            for (int j = 0; j < strLen; j++) {
    2115                if (str.charAt(j) != thisBuf[i + j]) {
    2116                    continue outer;
    2117                }
    2118            }
    2119            return i;
    2120        }
    2121        return StringUtils.INDEX_NOT_FOUND;
    2122    }
    2123
    2124    /**
    2125     * Searches the string builder using the matcher to find the first match.
    2126     * <p>
    2127     * Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the
    2128     * character 'a' followed by a number.
    2129     * </p>
    2130     *
    2131     * @param matcher the matcher to use, null returns -1
    2132     * @return The first index matched, or -1 if not found
    2133     */
    2134    public int indexOf(final StringMatcher matcher) {
    2135        return indexOf(matcher, 0);
    2136    }
    2137
    2138    /**
    2139     * Searches the string builder using the matcher to find the first match searching from the given index.
    2140     * <p>
    2141     * Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the
    2142     * character 'a' followed by a number.
    2143     * </p>
    2144     *
    2145     * @param matcher the matcher to use, null returns -1
    2146     * @param startIndex the index to start at, invalid index rounded to edge
    2147     * @return The first index matched, or -1 if not found
    2148     */
    2149    public int indexOf(final StringMatcher matcher, int startIndex) {
    2150        startIndex = Math.max(0, startIndex);
    2151        if (matcher == null || startIndex >= size) {
    2152            return StringUtils.INDEX_NOT_FOUND;
    2153        }
    2154        final int len = size;
    2155        final char[] buf = buffer;
    2156        for (int i = startIndex; i < len; i++) {
    2157            if (matcher.isMatch(buf, i, startIndex, len) > 0) {
    2158                return i;
    2159            }
    2160        }
    2161        return StringUtils.INDEX_NOT_FOUND;
    2162    }
    2163
    2164    /**
    2165     * Inserts the value into this builder.
    2166     *
    2167     * @param index the index to add at, must be valid
    2168     * @param value the value to insert
    2169     * @return this, to enable chaining
    2170     * @throws IndexOutOfBoundsException if the index is invalid
    2171     */
    2172    public TextStringBuilder insert(final int index, final boolean value) {
    2173        validateIndex(index);
    2174        if (value) {
    2175            ensureCapacityInternal(size + TRUE_STRING_SIZE);
    2176            System.arraycopy(buffer, index, buffer, index + TRUE_STRING_SIZE, size - index);
    2177            appendTrue(index);
    2178        } else {
    2179            ensureCapacityInternal(size + FALSE_STRING_SIZE);
    2180            System.arraycopy(buffer, index, buffer, index + FALSE_STRING_SIZE, size - index);
    2181            appendFalse(index);
    2182        }
    2183        return this;
    2184    }
    2185
    2186    /**
    2187     * Inserts the value into this builder.
    2188     *
    2189     * @param index the index to add at, must be valid
    2190     * @param value the value to insert
    2191     * @return this, to enable chaining
    2192     * @throws IndexOutOfBoundsException if the index is invalid
    2193     */
    2194    public TextStringBuilder insert(final int index, final char value) {
    2195        validateIndex(index);
    2196        ensureCapacityInternal(size + 1);
    2197        System.arraycopy(buffer, index, buffer, index + 1, size - index);
    2198        buffer[index] = value;
    2199        size++;
    2200        return this;
    2201    }
    2202
    2203    /**
    2204     * Inserts the character array into this builder. Inserting null will use the stored null text value.
    2205     *
    2206     * @param index the index to add at, must be valid
    2207     * @param chars the char array to insert
    2208     * @return this, to enable chaining
    2209     * @throws IndexOutOfBoundsException if the index is invalid
    2210     */
    2211    public TextStringBuilder insert(final int index, final char[] chars) {
    2212        validateIndex(index);
    2213        if (chars == null) {
    2214            return insert(index, nullText);
    2215        }
    2216        final int len = chars.length;
    2217        if (len > 0) {
    2218            ensureCapacityInternal(size + len);
    2219            System.arraycopy(buffer, index, buffer, index + len, size - index);
    2220            System.arraycopy(chars, 0, buffer, index, len);
    2221            size += len;
    2222        }
    2223        return this;
    2224    }
    2225
    2226    /**
    2227     * Inserts part of the character array into this builder. Inserting null will use the stored null text value.
    2228     *
    2229     * @param index the index to add at, must be valid
    2230     * @param chars the char array to insert
    2231     * @param offset the offset into the character array to start at, must be valid
    2232     * @param length the length of the character array part to copy, must be positive
    2233     * @return this, to enable chaining
    2234     * @throws IndexOutOfBoundsException if any index is invalid
    2235     */
    2236    public TextStringBuilder insert(final int index, final char[] chars, final int offset, final int length) {
    2237        validateIndex(index);
    2238        if (chars == null) {
    2239            return insert(index, nullText);
    2240        }
    2241        if (offset < 0 || offset > chars.length) {
    2242            throw new StringIndexOutOfBoundsException("Invalid offset: " + offset);
    2243        }
    2244        if (length < 0 || offset + length > chars.length) {
    2245            throw new StringIndexOutOfBoundsException("Invalid length: " + length);
    2246        }
    2247        if (length > 0) {
    2248            ensureCapacityInternal(size + length);
    2249            System.arraycopy(buffer, index, buffer, index + length, size - index);
    2250            System.arraycopy(chars, offset, buffer, index, length);
    2251            size += length;
    2252        }
    2253        return this;
    2254    }
    2255
    2256    /**
    2257     * Inserts the value into this builder.
    2258     *
    2259     * @param index the index to add at, must be valid
    2260     * @param value the value to insert
    2261     * @return this, to enable chaining
    2262     * @throws IndexOutOfBoundsException if the index is invalid
    2263     */
    2264    public TextStringBuilder insert(final int index, final double value) {
    2265        return insert(index, String.valueOf(value));
    2266    }
    2267
    2268    /**
    2269     * Inserts the value into this builder.
    2270     *
    2271     * @param index the index to add at, must be valid
    2272     * @param value the value to insert
    2273     * @return this, to enable chaining
    2274     * @throws IndexOutOfBoundsException if the index is invalid
    2275     */
    2276    public TextStringBuilder insert(final int index, final float value) {
    2277        return insert(index, String.valueOf(value));
    2278    }
    2279
    2280    /**
    2281     * Inserts the value into this builder.
    2282     *
    2283     * @param index the index to add at, must be valid
    2284     * @param value the value to insert
    2285     * @return this, to enable chaining
    2286     * @throws IndexOutOfBoundsException if the index is invalid
    2287     */
    2288    public TextStringBuilder insert(final int index, final int value) {
    2289        return insert(index, String.valueOf(value));
    2290    }
    2291
    2292    /**
    2293     * Inserts the value into this builder.
    2294     *
    2295     * @param index the index to add at, must be valid
    2296     * @param value the value to insert
    2297     * @return this, to enable chaining
    2298     * @throws IndexOutOfBoundsException if the index is invalid
    2299     */
    2300    public TextStringBuilder insert(final int index, final long value) {
    2301        return insert(index, String.valueOf(value));
    2302    }
    2303
    2304    /**
    2305     * Inserts the string representation of an object into this builder. Inserting null will use the stored null text
    2306     * value.
    2307     *
    2308     * @param index the index to add at, must be valid
    2309     * @param obj the object to insert
    2310     * @return this, to enable chaining
    2311     * @throws IndexOutOfBoundsException if the index is invalid
    2312     */
    2313    public TextStringBuilder insert(final int index, final Object obj) {
    2314        if (obj == null) {
    2315            return insert(index, nullText);
    2316        }
    2317        return insert(index, obj.toString());
    2318    }
    2319
    2320    /**
    2321     * Inserts the string into this builder. Inserting null will use the stored null text value.
    2322     *
    2323     * @param index the index to add at, must be valid
    2324     * @param str the string to insert
    2325     * @return this, to enable chaining
    2326     * @throws IndexOutOfBoundsException if the index is invalid
    2327     */
    2328    public TextStringBuilder insert(final int index, String str) {
    2329        validateIndex(index);
    2330        if (str == null) {
    2331            str = nullText;
    2332        }
    2333        if (str != null) {
    2334            final int strLen = str.length();
    2335            if (strLen > 0) {
    2336                final int newSize = size + strLen;
    2337                ensureCapacityInternal(newSize);
    2338                System.arraycopy(buffer, index, buffer, index + strLen, size - index);
    2339                size = newSize;
    2340                str.getChars(0, strLen, buffer, index);
    2341            }
    2342        }
    2343        return this;
    2344    }
    2345
    2346    /**
    2347     * Checks is the string builder is empty (convenience Collections API style method).
    2348     * <p>
    2349     * This method is the same as checking {@link #length()} and is provided to match the API of Collections.
    2350     * </p>
    2351     *
    2352     * @return {@code true} if the size is {@code 0}.
    2353     */
    2354    public boolean isEmpty() {
    2355        return size == 0;
    2356    }
    2357
    2358    /**
    2359     * Checks is the string builder is not empty.
    2360     * <p>
    2361     * This method is the same as checking {@link #length()}.
    2362     * </p>
    2363     *
    2364     * @return {@code true} if the size is not {@code 0}.
    2365     * @since 1.9
    2366     */
    2367    public boolean isNotEmpty() {
    2368        return size != 0;
    2369    }
    2370
    2371    /**
    2372     * Gets whether the internal buffer has been reallocated.
    2373     *
    2374     * @return Whether the internal buffer has been reallocated.
    2375     * @since 1.9
    2376     */
    2377    public boolean isReallocated() {
    2378        return reallocations > 0;
    2379    }
    2380
    2381    /**
    2382     * Searches the string builder to find the last reference to the specified char.
    2383     *
    2384     * @param ch the character to find
    2385     * @return The last index of the character, or -1 if not found
    2386     */
    2387    public int lastIndexOf(final char ch) {
    2388        return lastIndexOf(ch, size - 1);
    2389    }
    2390
    2391    /**
    2392     * Searches the string builder to find the last reference to the specified char.
    2393     *
    2394     * @param ch the character to find
    2395     * @param startIndex the index to start at, invalid index rounded to edge
    2396     * @return The last index of the character, or -1 if not found
    2397     */
    2398    public int lastIndexOf(final char ch, int startIndex) {
    2399        startIndex = startIndex >= size ? size - 1 : startIndex;
    2400        if (startIndex < 0) {
    2401            return StringUtils.INDEX_NOT_FOUND;
    2402        }
    2403        for (int i = startIndex; i >= 0; i--) {
    2404            if (buffer[i] == ch) {
    2405                return i;
    2406            }
    2407        }
    2408        return StringUtils.INDEX_NOT_FOUND;
    2409    }
    2410
    2411    /**
    2412     * Searches the string builder to find the last reference to the specified string.
    2413     * <p>
    2414     * Note that a null input string will return -1, whereas the JDK throws an exception.
    2415     * </p>
    2416     *
    2417     * @param str the string to find, null returns -1
    2418     * @return The last index of the string, or -1 if not found
    2419     */
    2420    public int lastIndexOf(final String str) {
    2421        return lastIndexOf(str, size - 1);
    2422    }
    2423
    2424    /**
    2425     * Searches the string builder to find the last reference to the specified string starting searching from the given
    2426     * index.
    2427     * <p>
    2428     * Note that a null input string will return -1, whereas the JDK throws an exception.
    2429     * </p>
    2430     *
    2431     * @param str the string to find, null returns -1
    2432     * @param startIndex the index to start at, invalid index rounded to edge
    2433     * @return The last index of the string, or -1 if not found
    2434     */
    2435    public int lastIndexOf(final String str, int startIndex) {
    2436        startIndex = startIndex >= size ? size - 1 : startIndex;
    2437        if (str == null || startIndex < 0) {
    2438            return StringUtils.INDEX_NOT_FOUND;
    2439        }
    2440        final int strLen = str.length();
    2441        if (strLen > 0 && strLen <= size) {
    2442            if (strLen == 1) {
    2443                return lastIndexOf(str.charAt(0), startIndex);
    2444            }
    2445
    2446            outer: for (int i = startIndex - strLen + 1; i >= 0; i--) {
    2447                for (int j = 0; j < strLen; j++) {
    2448                    if (str.charAt(j) != buffer[i + j]) {
    2449                        continue outer;
    2450                    }
    2451                }
    2452                return i;
    2453            }
    2454
    2455        } else if (strLen == 0) {
    2456            return startIndex;
    2457        }
    2458        return StringUtils.INDEX_NOT_FOUND;
    2459    }
    2460
    2461    /**
    2462     * Searches the string builder using the matcher to find the last match.
    2463     * <p>
    2464     * Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the
    2465     * character 'a' followed by a number.
    2466     * </p>
    2467     *
    2468     * @param matcher the matcher to use, null returns -1
    2469     * @return The last index matched, or -1 if not found
    2470     */
    2471    public int lastIndexOf(final StringMatcher matcher) {
    2472        return lastIndexOf(matcher, size);
    2473    }
    2474
    2475    /**
    2476     * Searches the string builder using the matcher to find the last match searching from the given index.
    2477     * <p>
    2478     * Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the
    2479     * character 'a' followed by a number.
    2480     * </p>
    2481     *
    2482     * @param matcher the matcher to use, null returns -1
    2483     * @param startIndex the index to start at, invalid index rounded to edge
    2484     * @return The last index matched, or -1 if not found
    2485     */
    2486    public int lastIndexOf(final StringMatcher matcher, int startIndex) {
    2487        startIndex = startIndex >= size ? size - 1 : startIndex;
    2488        if (matcher == null || startIndex < 0) {
    2489            return StringUtils.INDEX_NOT_FOUND;
    2490        }
    2491        final char[] buf = buffer;
    2492        final int endIndex = startIndex + 1;
    2493        for (int i = startIndex; i >= 0; i--) {
    2494            if (matcher.isMatch(buf, i, 0, endIndex) > 0) {
    2495                return i;
    2496            }
    2497        }
    2498        return StringUtils.INDEX_NOT_FOUND;
    2499    }
    2500
    2501    /**
    2502     * Extracts the leftmost characters from the string builder without throwing an exception.
    2503     * <p>
    2504     * This method extracts the left {@code length} characters from the builder. If this many characters are not
    2505     * available, the whole builder is returned. Thus the returned string may be shorter than the length requested.
    2506     * </p>
    2507     *
    2508     * @param length the number of characters to extract, negative returns empty string
    2509     * @return The new string
    2510     */
    2511    public String leftString(final int length) {
    2512        if (length <= 0) {
    2513            return StringUtils.EMPTY;
    2514        }
    2515        if (length >= size) {
    2516            return new String(buffer, 0, size);
    2517        }
    2518        return new String(buffer, 0, length);
    2519    }
    2520
    2521    /**
    2522     * Gets the length of the string builder.
    2523     *
    2524     * @return The length
    2525     */
    2526    @Override
    2527    public int length() {
    2528        return size;
    2529    }
    2530
    2531    /**
    2532     * Extracts some characters from the middle of the string builder without throwing an exception.
    2533     * <p>
    2534     * This method extracts {@code length} characters from the builder at the specified index. If the index is negative
    2535     * it is treated as zero. If the index is greater than the builder size, it is treated as the builder size. If the
    2536     * length is negative, the empty string is returned. If insufficient characters are available in the builder, as
    2537     * much as possible is returned. Thus the returned string may be shorter than the length requested.
    2538     * </p>
    2539     *
    2540     * @param index the index to start at, negative means zero
    2541     * @param length the number of characters to extract, negative returns empty string
    2542     * @return The new string
    2543     */
    2544    public String midString(int index, final int length) {
    2545        if (index < 0) {
    2546            index = 0;
    2547        }
    2548        if (length <= 0 || index >= size) {
    2549            return StringUtils.EMPTY;
    2550        }
    2551        if (size <= index + length) {
    2552            return new String(buffer, index, size - index);
    2553        }
    2554        return new String(buffer, index, length);
    2555    }
    2556
    2557    /**
    2558     * Minimizes the capacity to the actual length of the string.
    2559     *
    2560     * @return this, to enable chaining
    2561     */
    2562    public TextStringBuilder minimizeCapacity() {
    2563        if (buffer.length > size) {
    2564            reallocate(size);
    2565        }
    2566        return this;
    2567    }
    2568
    2569    /**
    2570     * If possible, reads chars from the provided {@link CharBuffer} directly into underlying character buffer without
    2571     * making extra copies.
    2572     *
    2573     * @param charBuffer CharBuffer to read.
    2574     * @return The number of characters read.
    2575     *
    2576     * @see #appendTo(Appendable)
    2577     * @since 1.9
    2578     */
    2579    public int readFrom(final CharBuffer charBuffer) {
    2580        final int oldSize = size;
    2581        final int remaining = charBuffer.remaining();
    2582        ensureCapacityInternal(size + remaining);
    2583        charBuffer.get(buffer, size, remaining);
    2584        size += remaining;
    2585        return size - oldSize;
    2586    }
    2587
    2588    /**
    2589     * If possible, reads all chars from the provided {@link Readable} directly into underlying character buffer without
    2590     * making extra copies.
    2591     *
    2592     * @param readable object to read from
    2593     * @return The number of characters read
    2594     * @throws IOException if an I/O error occurs.
    2595     *
    2596     * @see #appendTo(Appendable)
    2597     */
    2598    public int readFrom(final Readable readable) throws IOException {
    2599        if (readable instanceof Reader) {
    2600            return readFrom((Reader) readable);
    2601        }
    2602        if (readable instanceof CharBuffer) {
    2603            return readFrom((CharBuffer) readable);
    2604        }
    2605        final int oldSize = size;
    2606        while (true) {
    2607            ensureCapacityInternal(size + 1);
    2608            final CharBuffer buf = CharBuffer.wrap(buffer, size, buffer.length - size);
    2609            final int read = readable.read(buf);
    2610            if (read == EOS) {
    2611                break;
    2612            }
    2613            size += read;
    2614        }
    2615        return size - oldSize;
    2616    }
    2617
    2618    /**
    2619     * If possible, reads all chars from the provided {@link Reader} directly into underlying character buffer without
    2620     * making extra copies.
    2621     *
    2622     * @param reader Reader to read.
    2623     * @return The number of characters read or -1 if we reached the end of stream.
    2624     * @throws IOException if an I/O error occurs.
    2625     *
    2626     * @see #appendTo(Appendable)
    2627     * @since 1.9
    2628     */
    2629    public int readFrom(final Reader reader) throws IOException {
    2630        final int oldSize = size;
    2631        ensureCapacityInternal(size + 1);
    2632        int readCount = reader.read(buffer, size, buffer.length - size);
    2633        if (readCount == EOS) {
    2634            return EOS;
    2635        }
    2636        do {
    2637            size += readCount;
    2638            ensureCapacityInternal(size + 1);
    2639            readCount = reader.read(buffer, size, buffer.length - size);
    2640        } while (readCount != EOS);
    2641        return size - oldSize;
    2642    }
    2643
    2644    /**
    2645     * If possible, reads {@code count} chars from the provided {@link Reader} directly into underlying character buffer
    2646     * without making extra copies.
    2647     *
    2648     * @param reader Reader to read.
    2649     * @param count The maximum characters to read, a value &lt;= 0 returns 0.
    2650     * @return The number of characters read. If less than {@code count}, then we've reached the end-of-stream, or -1 if
    2651     *         we reached the end of stream.
    2652     * @throws IOException if an I/O error occurs.
    2653     * @see #appendTo(Appendable)
    2654     * @since 1.9
    2655     */
    2656    public int readFrom(final Reader reader, final int count) throws IOException {
    2657        if (count <= 0) {
    2658            return 0;
    2659        }
    2660        final int oldSize = size;
    2661        ensureCapacityInternal(size + count);
    2662        int target = count;
    2663        int readCount = reader.read(buffer, size, target);
    2664        if (readCount == EOS) {
    2665            return EOS;
    2666        }
    2667        do {
    2668            target -= readCount;
    2669            size += readCount;
    2670            readCount = reader.read(buffer, size, target);
    2671        } while (target > 0 && readCount != EOS);
    2672        return size - oldSize;
    2673    }
    2674
    2675    /**
    2676     * Reallocates the buffer to the new length.
    2677     *
    2678     * @param newLength the length of the copy to be returned
    2679     */
    2680    private void reallocate(final int newLength) {
    2681        this.buffer = Arrays.copyOf(buffer, newLength);
    2682        this.reallocations++;
    2683    }
    2684
    2685    /**
    2686     * Replaces a portion of the string builder with another string. The length of the inserted string does not have to
    2687     * match the removed length.
    2688     *
    2689     * @param startIndex the start index, inclusive, must be valid
    2690     * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string
    2691     * @param replaceStr the string to replace with, null means delete range
    2692     * @return this, to enable chaining
    2693     * @throws IndexOutOfBoundsException if the index is invalid
    2694     */
    2695    public TextStringBuilder replace(final int startIndex, int endIndex, final String replaceStr) {
    2696        endIndex = validateRange(startIndex, endIndex);
    2697        final int insertLen = replaceStr == null ? 0 : replaceStr.length();
    2698        replaceImpl(startIndex, endIndex, endIndex - startIndex, replaceStr, insertLen);
    2699        return this;
    2700    }
    2701
    2702    /**
    2703     * Advanced search and replaces within the builder using a matcher.
    2704     * <p>
    2705     * Matchers can be used to perform advanced behavior. For example you could write a matcher to delete all
    2706     * occurrences where the character 'a' is followed by a number.
    2707     * </p>
    2708     *
    2709     * @param matcher the matcher to use to find the deletion, null causes no action
    2710     * @param replaceStr the string to replace the match with, null is a delete
    2711     * @param startIndex the start index, inclusive, must be valid
    2712     * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string
    2713     * @param replaceCount the number of times to replace, -1 for replace all
    2714     * @return this, to enable chaining
    2715     * @throws IndexOutOfBoundsException if start index is invalid
    2716     */
    2717    public TextStringBuilder replace(final StringMatcher matcher, final String replaceStr, final int startIndex,
    2718        int endIndex, final int replaceCount) {
    2719        endIndex = validateRange(startIndex, endIndex);
    2720        return replaceImpl(matcher, replaceStr, startIndex, endIndex, replaceCount);
    2721    }
    2722
    2723    /**
    2724     * Replaces the search character with the replace character throughout the builder.
    2725     *
    2726     * @param search the search character
    2727     * @param replace the replace character
    2728     * @return this, to enable chaining
    2729     */
    2730    public TextStringBuilder replaceAll(final char search, final char replace) {
    2731        if (search != replace) {
    2732            for (int i = 0; i < size; i++) {
    2733                if (buffer[i] == search) {
    2734                    buffer[i] = replace;
    2735                }
    2736            }
    2737        }
    2738        return this;
    2739    }
    2740
    2741    /**
    2742     * Replaces the search string with the replace string throughout the builder.
    2743     *
    2744     * @param searchStr the search string, null causes no action to occur
    2745     * @param replaceStr the replace string, null is equivalent to an empty string
    2746     * @return this, to enable chaining
    2747     */
    2748    public TextStringBuilder replaceAll(final String searchStr, final String replaceStr) {
    2749        final int searchLen = searchStr == null ? 0 : searchStr.length();
    2750        if (searchLen > 0) {
    2751            final int replaceLen = replaceStr == null ? 0 : replaceStr.length();
    2752            int index = indexOf(searchStr, 0);
    2753            while (index >= 0) {
    2754                replaceImpl(index, index + searchLen, searchLen, replaceStr, replaceLen);
    2755                index = indexOf(searchStr, index + replaceLen);
    2756            }
    2757        }
    2758        return this;
    2759    }
    2760
    2761    /**
    2762     * Replaces all matches within the builder with the replace string.
    2763     * <p>
    2764     * Matchers can be used to perform advanced replace behavior. For example you could write a matcher to replace all
    2765     * occurrences where the character 'a' is followed by a number.
    2766     * </p>
    2767     *
    2768     * @param matcher the matcher to use to find the deletion, null causes no action
    2769     * @param replaceStr the replace string, null is equivalent to an empty string
    2770     * @return this, to enable chaining
    2771     */
    2772    public TextStringBuilder replaceAll(final StringMatcher matcher, final String replaceStr) {
    2773        return replace(matcher, replaceStr, 0, size, -1);
    2774    }
    2775
    2776    /**
    2777     * Replaces the first instance of the search character with the replace character in the builder.
    2778     *
    2779     * @param search the search character
    2780     * @param replace the replace character
    2781     * @return this, to enable chaining
    2782     */
    2783    public TextStringBuilder replaceFirst(final char search, final char replace) {
    2784        if (search != replace) {
    2785            for (int i = 0; i < size; i++) {
    2786                if (buffer[i] == search) {
    2787                    buffer[i] = replace;
    2788                    break;
    2789                }
    2790            }
    2791        }
    2792        return this;
    2793    }
    2794
    2795    /**
    2796     * Replaces the first instance of the search string with the replace string.
    2797     *
    2798     * @param searchStr the search string, null causes no action to occur
    2799     * @param replaceStr the replace string, null is equivalent to an empty string
    2800     * @return this, to enable chaining
    2801     */
    2802    public TextStringBuilder replaceFirst(final String searchStr, final String replaceStr) {
    2803        final int searchLen = searchStr == null ? 0 : searchStr.length();
    2804        if (searchLen > 0) {
    2805            final int index = indexOf(searchStr, 0);
    2806            if (index >= 0) {
    2807                final int replaceLen = replaceStr == null ? 0 : replaceStr.length();
    2808                replaceImpl(index, index + searchLen, searchLen, replaceStr, replaceLen);
    2809            }
    2810        }
    2811        return this;
    2812    }
    2813
    2814    /**
    2815     * Replaces the first match within the builder with the replace string.
    2816     * <p>
    2817     * Matchers can be used to perform advanced replace behavior. For example you could write a matcher to replace where
    2818     * the character 'a' is followed by a number.
    2819     * </p>
    2820     *
    2821     * @param matcher the matcher to use to find the deletion, null causes no action
    2822     * @param replaceStr the replace string, null is equivalent to an empty string
    2823     * @return this, to enable chaining
    2824     */
    2825    public TextStringBuilder replaceFirst(final StringMatcher matcher, final String replaceStr) {
    2826        return replace(matcher, replaceStr, 0, size, 1);
    2827    }
    2828
    2829    /**
    2830     * Internal method to delete a range without validation.
    2831     *
    2832     * @param startIndex the start index, must be valid
    2833     * @param endIndex the end index (exclusive), must be valid
    2834     * @param removeLen the length to remove (endIndex - startIndex), must be valid
    2835     * @param insertStr the string to replace with, null means delete range
    2836     * @param insertLen the length of the insert string, must be valid
    2837     * @throws IndexOutOfBoundsException if any index is invalid
    2838     */
    2839    private void replaceImpl(final int startIndex, final int endIndex, final int removeLen, final String insertStr,
    2840        final int insertLen) {
    2841        final int newSize = size - removeLen + insertLen;
    2842        if (insertLen != removeLen) {
    2843            ensureCapacityInternal(newSize);
    2844            System.arraycopy(buffer, endIndex, buffer, startIndex + insertLen, size - endIndex);
    2845            size = newSize;
    2846        }
    2847        if (insertLen > 0) {
    2848            insertStr.getChars(0, insertLen, buffer, startIndex);
    2849        }
    2850    }
    2851
    2852    /**
    2853     * Replaces within the builder using a matcher.
    2854     * <p>
    2855     * Matchers can be used to perform advanced behavior. For example you could write a matcher to delete all
    2856     * occurrences where the character 'a' is followed by a number.
    2857     * </p>
    2858     *
    2859     * @param matcher the matcher to use to find the deletion, null causes no action
    2860     * @param replaceStr the string to replace the match with, null is a delete
    2861     * @param from the start index, must be valid
    2862     * @param to the end index (exclusive), must be valid
    2863     * @param replaceCount the number of times to replace, -1 for replace all
    2864     * @return this, to enable chaining
    2865     * @throws IndexOutOfBoundsException if any index is invalid
    2866     */
    2867    private TextStringBuilder replaceImpl(final StringMatcher matcher, final String replaceStr, final int from, int to,
    2868        int replaceCount) {
    2869        if (matcher == null || size == 0) {
    2870            return this;
    2871        }
    2872        final int replaceLen = replaceStr == null ? 0 : replaceStr.length();
    2873        for (int i = from; i < to && replaceCount != 0; i++) {
    2874            final char[] buf = buffer;
    2875            final int removeLen = matcher.isMatch(buf, i, from, to);
    2876            if (removeLen > 0) {
    2877                replaceImpl(i, i + removeLen, removeLen, replaceStr, replaceLen);
    2878                to = to - removeLen + replaceLen;
    2879                i = i + replaceLen - 1;
    2880                if (replaceCount > 0) {
    2881                    replaceCount--;
    2882                }
    2883            }
    2884        }
    2885        return this;
    2886    }
    2887
    2888    /**
    2889     * Resizes the buffer to at least the size specified.
    2890     *
    2891     * @param minCapacity the minimum required capacity
    2892     * @throws OutOfMemoryError if the {@code minCapacity} is negative
    2893     */
    2894    private void resizeBuffer(final int minCapacity) {
    2895        // Overflow-conscious code treats the min and new capacity as unsigned.
    2896        final int oldCapacity = buffer.length;
    2897        int newCapacity = oldCapacity * 2;
    2898        if (Integer.compareUnsigned(newCapacity, minCapacity) < 0) {
    2899            newCapacity = minCapacity;
    2900        }
    2901        if (Integer.compareUnsigned(newCapacity, MAX_BUFFER_SIZE) > 0) {
    2902            newCapacity = createPositiveCapacity(minCapacity);
    2903        }
    2904        reallocate(newCapacity);
    2905    }
    2906
    2907    /**
    2908     * Reverses the string builder placing each character in the opposite index.
    2909     *
    2910     * @return this, to enable chaining
    2911     */
    2912    public TextStringBuilder reverse() {
    2913        if (size == 0) {
    2914            return this;
    2915        }
    2916
    2917        final int half = size / 2;
    2918        final char[] buf = buffer;
    2919        for (int leftIdx = 0, rightIdx = size - 1; leftIdx < half; leftIdx++, rightIdx--) {
    2920            final char swap = buf[leftIdx];
    2921            buf[leftIdx] = buf[rightIdx];
    2922            buf[rightIdx] = swap;
    2923        }
    2924        return this;
    2925    }
    2926
    2927    /**
    2928     * Extracts the rightmost characters from the string builder without throwing an exception.
    2929     * <p>
    2930     * This method extracts the right {@code length} characters from the builder. If this many characters are not
    2931     * available, the whole builder is returned. Thus the returned string may be shorter than the length requested.
    2932     * </p>
    2933     *
    2934     * @param length the number of characters to extract, negative returns empty string
    2935     * @return The new string
    2936     */
    2937    public String rightString(final int length) {
    2938        if (length <= 0) {
    2939            return StringUtils.EMPTY;
    2940        }
    2941        if (length >= size) {
    2942            return new String(buffer, 0, size);
    2943        }
    2944        return new String(buffer, size - length, length);
    2945    }
    2946
    2947    /**
    2948     * Clears and sets this builder to the given value.
    2949     *
    2950     * @see #charAt(int)
    2951     * @see #deleteCharAt(int)
    2952     * @param str the new value.
    2953     * @return this, to enable chaining
    2954     * @since 1.9
    2955     */
    2956    public TextStringBuilder set(final CharSequence str) {
    2957        clear();
    2958        append(str);
    2959        return this;
    2960    }
    2961
    2962    /**
    2963     * Sets the character at the specified index.
    2964     *
    2965     * @see #charAt(int)
    2966     * @see #deleteCharAt(int)
    2967     * @param index the index to set
    2968     * @param ch the new character
    2969     * @return this, to enable chaining
    2970     * @throws IndexOutOfBoundsException if the index is invalid
    2971     */
    2972    public TextStringBuilder setCharAt(final int index, final char ch) {
    2973        validateIndex(index);
    2974        buffer[index] = ch;
    2975        return this;
    2976    }
    2977
    2978    /**
    2979     * Updates the length of the builder by either dropping the last characters or adding filler of Unicode zero.
    2980     *
    2981     * @param length the length to set to, must be zero or positive
    2982     * @return this, to enable chaining
    2983     * @throws IndexOutOfBoundsException if the length is negative
    2984     */
    2985    public TextStringBuilder setLength(final int length) {
    2986        if (length < 0) {
    2987            throw new StringIndexOutOfBoundsException(length);
    2988        }
    2989        if (length < size) {
    2990            size = length;
    2991        } else if (length > size) {
    2992            ensureCapacityInternal(length);
    2993            final int oldEnd = size;
    2994            size = length;
    2995            Arrays.fill(buffer, oldEnd, length, '\0');
    2996        }
    2997        return this;
    2998    }
    2999
    3000    /**
    3001     * Sets the text to be appended when a new line is added.
    3002     *
    3003     * @param newLine the new line text, null means use system default
    3004     * @return this, to enable chaining
    3005     */
    3006    public TextStringBuilder setNewLineText(final String newLine) {
    3007        this.newLine = newLine;
    3008        return this;
    3009    }
    3010
    3011    /**
    3012     * Sets the text to be appended when null is added.
    3013     *
    3014     * @param nullText the null text, null means no append
    3015     * @return this, to enable chaining
    3016     */
    3017    public TextStringBuilder setNullText(String nullText) {
    3018        if (nullText != null && nullText.isEmpty()) {
    3019            nullText = null;
    3020        }
    3021        this.nullText = nullText;
    3022        return this;
    3023    }
    3024
    3025    /**
    3026     * Gets the length of the string builder.
    3027     * <p>
    3028     * This method is the same as {@link #length()} and is provided to match the API of Collections.
    3029     * </p>
    3030     *
    3031     * @return The length
    3032     */
    3033    public int size() {
    3034        return size;
    3035    }
    3036
    3037    /**
    3038     * Checks whether this builder starts with the specified string.
    3039     * <p>
    3040     * Note that this method handles null input quietly, unlike String.
    3041     * </p>
    3042     *
    3043     * @param str the string to search for, null returns false
    3044     * @return true if the builder starts with the string
    3045     */
    3046    public boolean startsWith(final String str) {
    3047        if (str == null) {
    3048            return false;
    3049        }
    3050        final int len = str.length();
    3051        if (len == 0) {
    3052            return true;
    3053        }
    3054        if (len > size) {
    3055            return false;
    3056        }
    3057        for (int i = 0; i < len; i++) {
    3058            if (buffer[i] != str.charAt(i)) {
    3059                return false;
    3060            }
    3061        }
    3062        return true;
    3063    }
    3064
    3065    /**
    3066     * {@inheritDoc}
    3067     */
    3068    @Override
    3069    public CharSequence subSequence(final int startIndex, final int endIndex) {
    3070        if (startIndex < 0) {
    3071            throw new StringIndexOutOfBoundsException(startIndex);
    3072        }
    3073        if (endIndex > size) {
    3074            throw new StringIndexOutOfBoundsException(endIndex);
    3075        }
    3076        if (startIndex > endIndex) {
    3077            throw new StringIndexOutOfBoundsException(endIndex - startIndex);
    3078        }
    3079        return substring(startIndex, endIndex);
    3080    }
    3081
    3082    /**
    3083     * Extracts a portion of this string builder as a string.
    3084     *
    3085     * @param start the start index, inclusive, must be valid
    3086     * @return The new string
    3087     * @throws IndexOutOfBoundsException if the index is invalid
    3088     */
    3089    public String substring(final int start) {
    3090        return substring(start, size);
    3091    }
    3092
    3093    /**
    3094     * Extracts a portion of this string builder as a string.
    3095     * <p>
    3096     * Note: This method treats an endIndex greater than the length of the builder as equal to the length of the
    3097     * builder, and continues without error, unlike StringBuffer or String.
    3098     * </p>
    3099     *
    3100     * @param startIndex the start index, inclusive, must be valid
    3101     * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string
    3102     * @return The new string
    3103     * @throws IndexOutOfBoundsException if the index is invalid
    3104     */
    3105    public String substring(final int startIndex, int endIndex) {
    3106        endIndex = validateRange(startIndex, endIndex);
    3107        return new String(buffer, startIndex, endIndex - startIndex);
    3108    }
    3109
    3110    /**
    3111     * Copies the builder's character array into a new character array.
    3112     *
    3113     * @return a new array that represents the contents of the builder
    3114     */
    3115    public char[] toCharArray() {
    3116        return size == 0 ? ArrayUtils.EMPTY_CHAR_ARRAY : Arrays.copyOf(buffer, size);
    3117    }
    3118
    3119    /**
    3120     * Copies part of the builder's character array into a new character array.
    3121     *
    3122     * @param startIndex the start index, inclusive, must be valid
    3123     * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string
    3124     * @return a new array that holds part of the contents of the builder
    3125     * @throws IndexOutOfBoundsException if startIndex is invalid, or if endIndex is invalid (but endIndex greater than
    3126     *         size is valid)
    3127     */
    3128    public char[] toCharArray(final int startIndex, int endIndex) {
    3129        endIndex = validateRange(startIndex, endIndex);
    3130        final int len = endIndex - startIndex;
    3131        return len == 0 ? ArrayUtils.EMPTY_CHAR_ARRAY : Arrays.copyOfRange(buffer, startIndex, endIndex);
    3132    }
    3133
    3134    /**
    3135     * Gets a String version of the string builder, creating a new instance each time the method is called.
    3136     * <p>
    3137     * Note that unlike StringBuffer, the string version returned is independent of the string builder.
    3138     * </p>
    3139     *
    3140     * @return The builder as a String
    3141     */
    3142    @Override
    3143    public String toString() {
    3144        return new String(buffer, 0, size);
    3145    }
    3146
    3147    /**
    3148     * Gets a StringBuffer version of the string builder, creating a new instance each time the method is called.
    3149     *
    3150     * @return The builder as a StringBuffer
    3151     */
    3152    public StringBuffer toStringBuffer() {
    3153        return new StringBuffer(size).append(buffer, 0, size);
    3154    }
    3155
    3156    /**
    3157     * Gets a StringBuilder version of the string builder, creating a new instance each time the method is called.
    3158     *
    3159     * @return The builder as a StringBuilder
    3160     */
    3161    public StringBuilder toStringBuilder() {
    3162        return new StringBuilder(size).append(buffer, 0, size);
    3163    }
    3164
    3165    /**
    3166     * Trims the builder by removing characters less than or equal to a space from the beginning and end.
    3167     *
    3168     * @return this, to enable chaining
    3169     */
    3170    public TextStringBuilder trim() {
    3171        if (size == 0) {
    3172            return this;
    3173        }
    3174        int len = size;
    3175        final char[] buf = buffer;
    3176        int pos = 0;
    3177        while (pos < len && buf[pos] <= SPACE) {
    3178            pos++;
    3179        }
    3180        while (pos < len && buf[len - 1] <= SPACE) {
    3181            len--;
    3182        }
    3183        if (len < size) {
    3184            delete(len, size);
    3185        }
    3186        if (pos > 0) {
    3187            delete(0, pos);
    3188        }
    3189        return this;
    3190    }
    3191
    3192    /**
    3193     * Validates that an index is in the range {@code 0 <= index <= size}.
    3194     *
    3195     * @param index the index to test.
    3196     * @throws IndexOutOfBoundsException Thrown when the index is not the range {@code 0 <= index <= size}.
    3197     */
    3198    protected void validateIndex(final int index) {
    3199        if (index < 0 || index >= size) {
    3200            throw new StringIndexOutOfBoundsException(index);
    3201        }
    3202    }
    3203
    3204    /**
    3205     * Validates parameters defining a range of the builder.
    3206     *
    3207     * @param startIndex the start index, inclusive, must be valid
    3208     * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string
    3209     * @return A valid end index.
    3210     * @throws StringIndexOutOfBoundsException if the index is invalid
    3211     */
    3212    protected int validateRange(final int startIndex, int endIndex) {
    3213        if (startIndex < 0) {
    3214            throw new StringIndexOutOfBoundsException(startIndex);
    3215        }
    3216        if (endIndex > size) {
    3217            endIndex = size;
    3218        }
    3219        if (startIndex > endIndex) {
    3220            throw new StringIndexOutOfBoundsException("end < start");
    3221        }
    3222        return endIndex;
    3223    }
    3224
    3225}