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