AbstractStringBuilder.java 56.1 KB
Newer Older
D
duke 已提交
1
/*
2
 * Copyright (c) 2003, 2012, Oracle and/or its affiliates. All rights reserved.
D
duke 已提交
3 4 5 6
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
7
 * published by the Free Software Foundation.  Oracle designates this
D
duke 已提交
8
 * particular file as subject to the "Classpath" exception as provided
9
 * by Oracle in the LICENSE file that accompanied this code.
D
duke 已提交
10 11 12 13 14 15 16 17 18 19 20
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
21 22 23
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
D
duke 已提交
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
 */

package java.lang;

import sun.misc.FloatingDecimal;
import java.util.Arrays;

/**
 * A mutable sequence of characters.
 * <p>
 * Implements a modifiable string. At any point in time it contains some
 * particular sequence of characters, but the length and content of the
 * sequence can be changed through certain method calls.
 *
 * @author      Michael McCloskey
39 40
 * @author      Martin Buchholz
 * @author      Ulf Zibis
D
duke 已提交
41 42 43 44 45 46
 * @since       1.5
 */
abstract class AbstractStringBuilder implements Appendable, CharSequence {
    /**
     * The value is used for character storage.
     */
47
    char[] value;
D
duke 已提交
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93

    /**
     * The count is the number of characters used.
     */
    int count;

    /**
     * This no-arg constructor is necessary for serialization of subclasses.
     */
    AbstractStringBuilder() {
    }

    /**
     * Creates an AbstractStringBuilder of the specified capacity.
     */
    AbstractStringBuilder(int capacity) {
        value = new char[capacity];
    }

    /**
     * Returns the length (character count).
     *
     * @return  the length of the sequence of characters currently
     *          represented by this object
     */
    public int length() {
        return count;
    }

    /**
     * Returns the current capacity. The capacity is the amount of storage
     * available for newly inserted characters, beyond which an allocation
     * will occur.
     *
     * @return  the current capacity
     */
    public int capacity() {
        return value.length;
    }

    /**
     * Ensures that the capacity is at least equal to the specified minimum.
     * If the current capacity is less than the argument, then a new internal
     * array is allocated with greater capacity. The new capacity is the
     * larger of:
     * <ul>
94 95
     * <li>The {@code minimumCapacity} argument.
     * <li>Twice the old capacity, plus {@code 2}.
D
duke 已提交
96
     * </ul>
97
     * If the {@code minimumCapacity} argument is nonpositive, this
D
duke 已提交
98
     * method takes no action and simply returns.
99 100
     * Note that subsequent operations on this object can reduce the
     * actual capacity below that requested here.
D
duke 已提交
101 102 103 104
     *
     * @param   minimumCapacity   the minimum desired capacity.
     */
    public void ensureCapacity(int minimumCapacity) {
105 106
        if (minimumCapacity > 0)
            ensureCapacityInternal(minimumCapacity);
107 108 109 110 111 112 113
    }

    /**
     * This method has the same contract as ensureCapacity, but is
     * never synchronized.
     */
    private void ensureCapacityInternal(int minimumCapacity) {
114
        // overflow-conscious code
115
        if (minimumCapacity - value.length > 0)
D
duke 已提交
116 117 118 119 120 121 122 123
            expandCapacity(minimumCapacity);
    }

    /**
     * This implements the expansion semantics of ensureCapacity with no
     * size check or synchronization.
     */
    void expandCapacity(int minimumCapacity) {
124
        int newCapacity = value.length * 2 + 2;
125 126
        if (newCapacity - minimumCapacity < 0)
            newCapacity = minimumCapacity;
D
duke 已提交
127
        if (newCapacity < 0) {
128 129
            if (minimumCapacity < 0) // overflow
                throw new OutOfMemoryError();
D
duke 已提交
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
            newCapacity = Integer.MAX_VALUE;
        }
        value = Arrays.copyOf(value, newCapacity);
    }

    /**
     * Attempts to reduce storage used for the character sequence.
     * If the buffer is larger than necessary to hold its current sequence of
     * characters, then it may be resized to become more space efficient.
     * Calling this method may, but is not required to, affect the value
     * returned by a subsequent call to the {@link #capacity()} method.
     */
    public void trimToSize() {
        if (count < value.length) {
            value = Arrays.copyOf(value, count);
        }
    }

    /**
     * Sets the length of the character sequence.
     * The sequence is changed to a new character sequence
     * whose length is specified by the argument. For every nonnegative
152
     * index <i>k</i> less than {@code newLength}, the character at
D
duke 已提交
153 154 155
     * index <i>k</i> in the new character sequence is the same as the
     * character at index <i>k</i> in the old sequence if <i>k</i> is less
     * than the length of the old character sequence; otherwise, it is the
156
     * null character {@code '\u005Cu0000'}.
D
duke 已提交
157
     *
158
     * In other words, if the {@code newLength} argument is less than
D
duke 已提交
159 160
     * the current length, the length is changed to the specified length.
     * <p>
161
     * If the {@code newLength} argument is greater than or equal
D
duke 已提交
162
     * to the current length, sufficient null characters
163 164
     * ({@code '\u005Cu0000'}) are appended so that
     * length becomes the {@code newLength} argument.
D
duke 已提交
165
     * <p>
166 167
     * The {@code newLength} argument must be greater than or equal
     * to {@code 0}.
D
duke 已提交
168 169 170
     *
     * @param      newLength   the new length
     * @throws     IndexOutOfBoundsException  if the
171
     *               {@code newLength} argument is negative.
D
duke 已提交
172 173 174 175
     */
    public void setLength(int newLength) {
        if (newLength < 0)
            throw new StringIndexOutOfBoundsException(newLength);
176
        ensureCapacityInternal(newLength);
D
duke 已提交
177 178 179 180 181 182 183 184 185 186

        if (count < newLength) {
            for (; count < newLength; count++)
                value[count] = '\0';
        } else {
            count = newLength;
        }
    }

    /**
187 188 189
     * Returns the {@code char} value in this sequence at the specified index.
     * The first {@code char} value is at index {@code 0}, the next at index
     * {@code 1}, and so on, as in array indexing.
D
duke 已提交
190 191
     * <p>
     * The index argument must be greater than or equal to
192
     * {@code 0}, and less than the length of this sequence.
D
duke 已提交
193
     *
194
     * <p>If the {@code char} value specified by the index is a
D
duke 已提交
195 196 197
     * <a href="Character.html#unicode">surrogate</a>, the surrogate
     * value is returned.
     *
198 199 200 201
     * @param      index   the index of the desired {@code char} value.
     * @return     the {@code char} value at the specified index.
     * @throws     IndexOutOfBoundsException  if {@code index} is
     *             negative or greater than or equal to {@code length()}.
D
duke 已提交
202 203 204 205 206 207 208 209 210
     */
    public char charAt(int index) {
        if ((index < 0) || (index >= count))
            throw new StringIndexOutOfBoundsException(index);
        return value[index];
    }

    /**
     * Returns the character (Unicode code point) at the specified
211 212 213
     * index. The index refers to {@code char} values
     * (Unicode code units) and ranges from {@code 0} to
     * {@link #length()}{@code  - 1}.
D
duke 已提交
214
     *
215
     * <p> If the {@code char} value specified at the given index
D
duke 已提交
216 217
     * is in the high-surrogate range, the following index is less
     * than the length of this sequence, and the
218
     * {@code char} value at the following index is in the
D
duke 已提交
219 220
     * low-surrogate range, then the supplementary code point
     * corresponding to this surrogate pair is returned. Otherwise,
221
     * the {@code char} value at the given index is returned.
D
duke 已提交
222
     *
223
     * @param      index the index to the {@code char} values
D
duke 已提交
224
     * @return     the code point value of the character at the
225 226
     *             {@code index}
     * @exception  IndexOutOfBoundsException  if the {@code index}
D
duke 已提交
227 228 229 230 231 232 233 234 235 236 237 238
     *             argument is negative or not less than the length of this
     *             sequence.
     */
    public int codePointAt(int index) {
        if ((index < 0) || (index >= count)) {
            throw new StringIndexOutOfBoundsException(index);
        }
        return Character.codePointAt(value, index);
    }

    /**
     * Returns the character (Unicode code point) before the specified
239 240
     * index. The index refers to {@code char} values
     * (Unicode code units) and ranges from {@code 1} to {@link
D
duke 已提交
241 242
     * #length()}.
     *
243 244 245 246
     * <p> If the {@code char} value at {@code (index - 1)}
     * is in the low-surrogate range, {@code (index - 2)} is not
     * negative, and the {@code char} value at {@code (index -
     * 2)} is in the high-surrogate range, then the
D
duke 已提交
247
     * supplementary code point value of the surrogate pair is
248 249
     * returned. If the {@code char} value at {@code index -
     * 1} is an unpaired low-surrogate or a high-surrogate, the
D
duke 已提交
250 251 252 253
     * surrogate value is returned.
     *
     * @param     index the index following the code point that should be returned
     * @return    the Unicode code point value before the given index.
254
     * @exception IndexOutOfBoundsException if the {@code index}
D
duke 已提交
255 256 257 258 259 260 261 262 263 264 265 266 267 268
     *            argument is less than 1 or greater than the length
     *            of this sequence.
     */
    public int codePointBefore(int index) {
        int i = index - 1;
        if ((i < 0) || (i >= count)) {
            throw new StringIndexOutOfBoundsException(index);
        }
        return Character.codePointBefore(value, index);
    }

    /**
     * Returns the number of Unicode code points in the specified text
     * range of this sequence. The text range begins at the specified
269 270 271 272
     * {@code beginIndex} and extends to the {@code char} at
     * index {@code endIndex - 1}. Thus the length (in
     * {@code char}s) of the text range is
     * {@code endIndex-beginIndex}. Unpaired surrogates within
D
duke 已提交
273 274
     * this sequence count as one code point each.
     *
275
     * @param beginIndex the index to the first {@code char} of
D
duke 已提交
276
     * the text range.
277
     * @param endIndex the index after the last {@code char} of
D
duke 已提交
278 279 280 281
     * the text range.
     * @return the number of Unicode code points in the specified text
     * range
     * @exception IndexOutOfBoundsException if the
282
     * {@code beginIndex} is negative, or {@code endIndex}
D
duke 已提交
283
     * is larger than the length of this sequence, or
284
     * {@code beginIndex} is larger than {@code endIndex}.
D
duke 已提交
285 286 287 288 289 290 291 292 293 294
     */
    public int codePointCount(int beginIndex, int endIndex) {
        if (beginIndex < 0 || endIndex > count || beginIndex > endIndex) {
            throw new IndexOutOfBoundsException();
        }
        return Character.codePointCountImpl(value, beginIndex, endIndex-beginIndex);
    }

    /**
     * Returns the index within this sequence that is offset from the
295
     * given {@code index} by {@code codePointOffset} code
D
duke 已提交
296
     * points. Unpaired surrogates within the text range given by
297
     * {@code index} and {@code codePointOffset} count as
D
duke 已提交
298 299 300 301 302
     * one code point each.
     *
     * @param index the index to be offset
     * @param codePointOffset the offset in code points
     * @return the index within this sequence
303
     * @exception IndexOutOfBoundsException if {@code index}
D
duke 已提交
304
     *   is negative or larger then the length of this sequence,
305 306 307 308 309 310
     *   or if {@code codePointOffset} is positive and the subsequence
     *   starting with {@code index} has fewer than
     *   {@code codePointOffset} code points,
     *   or if {@code codePointOffset} is negative and the subsequence
     *   before {@code index} has fewer than the absolute value of
     *   {@code codePointOffset} code points.
D
duke 已提交
311 312 313 314 315 316 317 318 319 320 321
     */
    public int offsetByCodePoints(int index, int codePointOffset) {
        if (index < 0 || index > count) {
            throw new IndexOutOfBoundsException();
        }
        return Character.offsetByCodePointsImpl(value, 0, count,
                                                index, codePointOffset);
    }

    /**
     * Characters are copied from this sequence into the
322 323 324 325 326 327
     * destination character array {@code dst}. The first character to
     * be copied is at index {@code srcBegin}; the last character to
     * be copied is at index {@code srcEnd-1}. The total number of
     * characters to be copied is {@code srcEnd-srcBegin}. The
     * characters are copied into the subarray of {@code dst} starting
     * at index {@code dstBegin} and ending at index:
D
duke 已提交
328 329 330 331 332 333 334
     * <p><blockquote><pre>
     * dstbegin + (srcEnd-srcBegin) - 1
     * </pre></blockquote>
     *
     * @param      srcBegin   start copying at this offset.
     * @param      srcEnd     stop copying at this offset.
     * @param      dst        the array to copy the data into.
335 336 337
     * @param      dstBegin   offset into {@code dst}.
     * @throws     NullPointerException if {@code dst} is
     *             {@code null}.
D
duke 已提交
338 339
     * @throws     IndexOutOfBoundsException  if any of the following is true:
     *             <ul>
340 341 342 343 344 345 346 347
     *             <li>{@code srcBegin} is negative
     *             <li>{@code dstBegin} is negative
     *             <li>the {@code srcBegin} argument is greater than
     *             the {@code srcEnd} argument.
     *             <li>{@code srcEnd} is greater than
     *             {@code this.length()}.
     *             <li>{@code dstBegin+srcEnd-srcBegin} is greater than
     *             {@code dst.length}
D
duke 已提交
348 349
     *             </ul>
     */
350
    public void getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)
D
duke 已提交
351 352 353 354 355 356 357 358 359 360 361
    {
        if (srcBegin < 0)
            throw new StringIndexOutOfBoundsException(srcBegin);
        if ((srcEnd < 0) || (srcEnd > count))
            throw new StringIndexOutOfBoundsException(srcEnd);
        if (srcBegin > srcEnd)
            throw new StringIndexOutOfBoundsException("srcBegin > srcEnd");
        System.arraycopy(value, srcBegin, dst, dstBegin, srcEnd - srcBegin);
    }

    /**
362
     * The character at the specified index is set to {@code ch}. This
D
duke 已提交
363 364
     * sequence is altered to represent a new character sequence that is
     * identical to the old character sequence, except that it contains the
365
     * character {@code ch} at position {@code index}.
D
duke 已提交
366 367
     * <p>
     * The index argument must be greater than or equal to
368
     * {@code 0}, and less than the length of this sequence.
D
duke 已提交
369 370 371
     *
     * @param      index   the index of the character to modify.
     * @param      ch      the new character.
372 373
     * @throws     IndexOutOfBoundsException  if {@code index} is
     *             negative or greater than or equal to {@code length()}.
D
duke 已提交
374 375 376 377 378 379 380 381
     */
    public void setCharAt(int index, char ch) {
        if ((index < 0) || (index >= count))
            throw new StringIndexOutOfBoundsException(index);
        value[index] = ch;
    }

    /**
382
     * Appends the string representation of the {@code Object} argument.
D
duke 已提交
383
     * <p>
384 385 386 387
     * The overall effect is exactly as if the argument were converted
     * to a string by the method {@link String#valueOf(Object)},
     * and the characters of that string were then
     * {@link #append(String) appended} to this character sequence.
D
duke 已提交
388
     *
389
     * @param   obj   an {@code Object}.
D
duke 已提交
390 391 392 393 394 395 396 397 398
     * @return  a reference to this object.
     */
    public AbstractStringBuilder append(Object obj) {
        return append(String.valueOf(obj));
    }

    /**
     * Appends the specified string to this character sequence.
     * <p>
399
     * The characters of the {@code String} argument are appended, in
D
duke 已提交
400
     * order, increasing the length of this sequence by the length of the
401 402
     * argument. If {@code str} is {@code null}, then the four
     * characters {@code "null"} are appended.
D
duke 已提交
403 404
     * <p>
     * Let <i>n</i> be the length of this character sequence just prior to
405
     * execution of the {@code append} method. Then the character at
D
duke 已提交
406 407 408
     * index <i>k</i> in the new character sequence is equal to the character
     * at index <i>k</i> in the old character sequence, if <i>k</i> is less
     * than <i>n</i>; otherwise, it is equal to the character at index
409
     * <i>k-n</i> in the argument {@code str}.
D
duke 已提交
410 411 412 413 414 415 416
     *
     * @param   str   a string.
     * @return  a reference to this object.
     */
    public AbstractStringBuilder append(String str) {
        if (str == null) str = "null";
        int len = str.length();
417
        ensureCapacityInternal(count + len);
D
duke 已提交
418
        str.getChars(0, len, value, count);
419
        count += len;
D
duke 已提交
420 421 422 423 424 425 426 427
        return this;
    }

    // Documentation in subclasses because of synchro difference
    public AbstractStringBuilder append(StringBuffer sb) {
        if (sb == null)
            return append("null");
        int len = sb.length();
428
        ensureCapacityInternal(count + len);
D
duke 已提交
429
        sb.getChars(0, len, value, count);
430
        count += len;
D
duke 已提交
431 432 433 434 435 436 437 438 439 440 441 442 443 444 445
        return this;
    }

    // Documentation in subclasses because of synchro difference
    public AbstractStringBuilder append(CharSequence s) {
        if (s == null)
            s = "null";
        if (s instanceof String)
            return this.append((String)s);
        if (s instanceof StringBuffer)
            return this.append((StringBuffer)s);
        return this.append(s, 0, s.length());
    }

    /**
446
     * Appends a subsequence of the specified {@code CharSequence} to this
D
duke 已提交
447 448
     * sequence.
     * <p>
449 450 451 452
     * Characters of the argument {@code s}, starting at
     * index {@code start}, are appended, in order, to the contents of
     * this sequence up to the (exclusive) index {@code end}. The length
     * of this sequence is increased by the value of {@code end - start}.
D
duke 已提交
453 454
     * <p>
     * Let <i>n</i> be the length of this character sequence just prior to
455
     * execution of the {@code append} method. Then the character at
D
duke 已提交
456 457 458
     * index <i>k</i> in this character sequence becomes equal to the
     * character at index <i>k</i> in this sequence, if <i>k</i> is less than
     * <i>n</i>; otherwise, it is equal to the character at index
459
     * <i>k+start-n</i> in the argument {@code s}.
D
duke 已提交
460
     * <p>
461
     * If {@code s} is {@code null}, then this method appends
D
duke 已提交
462
     * characters as if the s parameter was a sequence containing the four
463
     * characters {@code "null"}.
D
duke 已提交
464 465 466 467 468 469
     *
     * @param   s the sequence to append.
     * @param   start   the starting index of the subsequence to be appended.
     * @param   end     the end index of the subsequence to be appended.
     * @return  a reference to this object.
     * @throws     IndexOutOfBoundsException if
470 471 472
     *             {@code start} is negative, or
     *             {@code start} is greater than {@code end} or
     *             {@code end} is greater than {@code s.length()}
D
duke 已提交
473 474 475 476
     */
    public AbstractStringBuilder append(CharSequence s, int start, int end) {
        if (s == null)
            s = "null";
477
        if ((start < 0) || (start > end) || (end > s.length()))
D
duke 已提交
478 479 480 481
            throw new IndexOutOfBoundsException(
                "start " + start + ", end " + end + ", s.length() "
                + s.length());
        int len = end - start;
482 483 484 485
        ensureCapacityInternal(count + len);
        for (int i = start, j = count; i < end; i++, j++)
            value[j] = s.charAt(i);
        count += len;
D
duke 已提交
486 487 488 489
        return this;
    }

    /**
490
     * Appends the string representation of the {@code char} array
D
duke 已提交
491 492 493 494 495 496
     * argument to this sequence.
     * <p>
     * The characters of the array argument are appended, in order, to
     * the contents of this sequence. The length of this sequence
     * increases by the length of the argument.
     * <p>
497 498 499 500
     * The overall effect is exactly as if the argument were converted
     * to a string by the method {@link String#valueOf(char[])},
     * and the characters of that string were then
     * {@link #append(String) appended} to this character sequence.
D
duke 已提交
501 502 503 504
     *
     * @param   str   the characters to be appended.
     * @return  a reference to this object.
     */
505
    public AbstractStringBuilder append(char[] str) {
506 507 508 509
        int len = str.length;
        ensureCapacityInternal(count + len);
        System.arraycopy(str, 0, value, count, len);
        count += len;
D
duke 已提交
510 511 512 513 514
        return this;
    }

    /**
     * Appends the string representation of a subarray of the
515
     * {@code char} array argument to this sequence.
D
duke 已提交
516
     * <p>
517 518
     * Characters of the {@code char} array {@code str}, starting at
     * index {@code offset}, are appended, in order, to the contents
D
duke 已提交
519
     * of this sequence. The length of this sequence increases
520
     * by the value of {@code len}.
D
duke 已提交
521
     * <p>
522 523 524 525
     * The overall effect is exactly as if the arguments were converted
     * to a string by the method {@link String#valueOf(char[],int,int)},
     * and the characters of that string were then
     * {@link #append(String) appended} to this character sequence.
D
duke 已提交
526 527
     *
     * @param   str      the characters to be appended.
528 529
     * @param   offset   the index of the first {@code char} to append.
     * @param   len      the number of {@code char}s to append.
D
duke 已提交
530
     * @return  a reference to this object.
531 532 533
     * @throws IndexOutOfBoundsException
     *         if {@code offset < 0} or {@code len < 0}
     *         or {@code offset+len > str.length}
D
duke 已提交
534 535
     */
    public AbstractStringBuilder append(char str[], int offset, int len) {
536 537
        if (len > 0)                // let arraycopy report AIOOBE for len < 0
            ensureCapacityInternal(count + len);
D
duke 已提交
538
        System.arraycopy(str, offset, value, count, len);
539
        count += len;
D
duke 已提交
540 541 542 543
        return this;
    }

    /**
544
     * Appends the string representation of the {@code boolean}
D
duke 已提交
545 546
     * argument to the sequence.
     * <p>
547 548 549 550
     * The overall effect is exactly as if the argument were converted
     * to a string by the method {@link String#valueOf(boolean)},
     * and the characters of that string were then
     * {@link #append(String) appended} to this character sequence.
D
duke 已提交
551
     *
552
     * @param   b   a {@code boolean}.
D
duke 已提交
553 554 555 556
     * @return  a reference to this object.
     */
    public AbstractStringBuilder append(boolean b) {
        if (b) {
557
            ensureCapacityInternal(count + 4);
D
duke 已提交
558 559 560 561 562
            value[count++] = 't';
            value[count++] = 'r';
            value[count++] = 'u';
            value[count++] = 'e';
        } else {
563
            ensureCapacityInternal(count + 5);
D
duke 已提交
564 565 566 567 568 569 570 571 572 573
            value[count++] = 'f';
            value[count++] = 'a';
            value[count++] = 'l';
            value[count++] = 's';
            value[count++] = 'e';
        }
        return this;
    }

    /**
574
     * Appends the string representation of the {@code char}
D
duke 已提交
575 576 577
     * argument to this sequence.
     * <p>
     * The argument is appended to the contents of this sequence.
578
     * The length of this sequence increases by {@code 1}.
D
duke 已提交
579
     * <p>
580 581 582 583
     * The overall effect is exactly as if the argument were converted
     * to a string by the method {@link String#valueOf(char)},
     * and the character in that string were then
     * {@link #append(String) appended} to this character sequence.
D
duke 已提交
584
     *
585
     * @param   c   a {@code char}.
D
duke 已提交
586 587 588
     * @return  a reference to this object.
     */
    public AbstractStringBuilder append(char c) {
589
        ensureCapacityInternal(count + 1);
D
duke 已提交
590 591 592 593 594
        value[count++] = c;
        return this;
    }

    /**
595
     * Appends the string representation of the {@code int}
D
duke 已提交
596 597
     * argument to this sequence.
     * <p>
598 599 600 601
     * The overall effect is exactly as if the argument were converted
     * to a string by the method {@link String#valueOf(int)},
     * and the characters of that string were then
     * {@link #append(String) appended} to this character sequence.
D
duke 已提交
602
     *
603
     * @param   i   an {@code int}.
D
duke 已提交
604 605 606 607 608 609 610 611 612 613
     * @return  a reference to this object.
     */
    public AbstractStringBuilder append(int i) {
        if (i == Integer.MIN_VALUE) {
            append("-2147483648");
            return this;
        }
        int appendedLength = (i < 0) ? Integer.stringSize(-i) + 1
                                     : Integer.stringSize(i);
        int spaceNeeded = count + appendedLength;
614
        ensureCapacityInternal(spaceNeeded);
D
duke 已提交
615 616 617 618 619 620
        Integer.getChars(i, spaceNeeded, value);
        count = spaceNeeded;
        return this;
    }

    /**
621
     * Appends the string representation of the {@code long}
D
duke 已提交
622 623
     * argument to this sequence.
     * <p>
624 625 626 627
     * The overall effect is exactly as if the argument were converted
     * to a string by the method {@link String#valueOf(long)},
     * and the characters of that string were then
     * {@link #append(String) appended} to this character sequence.
D
duke 已提交
628
     *
629
     * @param   l   a {@code long}.
D
duke 已提交
630 631 632 633 634 635 636 637 638 639
     * @return  a reference to this object.
     */
    public AbstractStringBuilder append(long l) {
        if (l == Long.MIN_VALUE) {
            append("-9223372036854775808");
            return this;
        }
        int appendedLength = (l < 0) ? Long.stringSize(-l) + 1
                                     : Long.stringSize(l);
        int spaceNeeded = count + appendedLength;
640
        ensureCapacityInternal(spaceNeeded);
D
duke 已提交
641 642 643 644 645 646
        Long.getChars(l, spaceNeeded, value);
        count = spaceNeeded;
        return this;
    }

    /**
647
     * Appends the string representation of the {@code float}
D
duke 已提交
648 649
     * argument to this sequence.
     * <p>
650 651 652 653
     * The overall effect is exactly as if the argument were converted
     * to a string by the method {@link String#valueOf(float)},
     * and the characters of that string were then
     * {@link #append(String) appended} to this character sequence.
D
duke 已提交
654
     *
655
     * @param   f   a {@code float}.
D
duke 已提交
656 657 658 659 660 661 662 663
     * @return  a reference to this object.
     */
    public AbstractStringBuilder append(float f) {
        new FloatingDecimal(f).appendTo(this);
        return this;
    }

    /**
664
     * Appends the string representation of the {@code double}
D
duke 已提交
665 666
     * argument to this sequence.
     * <p>
667 668 669 670
     * The overall effect is exactly as if the argument were converted
     * to a string by the method {@link String#valueOf(double)},
     * and the characters of that string were then
     * {@link #append(String) appended} to this character sequence.
D
duke 已提交
671
     *
672
     * @param   d   a {@code double}.
D
duke 已提交
673 674 675 676 677 678 679 680 681
     * @return  a reference to this object.
     */
    public AbstractStringBuilder append(double d) {
        new FloatingDecimal(d).appendTo(this);
        return this;
    }

    /**
     * Removes the characters in a substring of this sequence.
682 683
     * The substring begins at the specified {@code start} and extends to
     * the character at index {@code end - 1} or to the end of the
D
duke 已提交
684
     * sequence if no such character exists. If
685
     * {@code start} is equal to {@code end}, no changes are made.
D
duke 已提交
686 687 688 689
     *
     * @param      start  The beginning index, inclusive.
     * @param      end    The ending index, exclusive.
     * @return     This object.
690 691 692
     * @throws     StringIndexOutOfBoundsException  if {@code start}
     *             is negative, greater than {@code length()}, or
     *             greater than {@code end}.
D
duke 已提交
693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709
     */
    public AbstractStringBuilder delete(int start, int end) {
        if (start < 0)
            throw new StringIndexOutOfBoundsException(start);
        if (end > count)
            end = count;
        if (start > end)
            throw new StringIndexOutOfBoundsException();
        int len = end - start;
        if (len > 0) {
            System.arraycopy(value, start+len, value, start, count-end);
            count -= len;
        }
        return this;
    }

    /**
710
     * Appends the string representation of the {@code codePoint}
D
duke 已提交
711 712 713 714 715 716 717
     * argument to this sequence.
     *
     * <p> The argument is appended to the contents of this sequence.
     * The length of this sequence increases by
     * {@link Character#charCount(int) Character.charCount(codePoint)}.
     *
     * <p> The overall effect is exactly as if the argument were
718 719 720
     * converted to a {@code char} array by the method
     * {@link Character#toChars(int)} and the character in that array
     * were then {@link #append(char[]) appended} to this character
D
duke 已提交
721 722 723 724 725
     * sequence.
     *
     * @param   codePoint   a Unicode code point
     * @return  a reference to this object.
     * @exception IllegalArgumentException if the specified
726
     * {@code codePoint} isn't a valid Unicode code point
D
duke 已提交
727 728
     */
    public AbstractStringBuilder appendCodePoint(int codePoint) {
729 730 731 732 733 734 735 736
        final int count = this.count;

        if (Character.isBmpCodePoint(codePoint)) {
            ensureCapacityInternal(count + 1);
            value[count] = (char) codePoint;
            this.count = count + 1;
        } else if (Character.isValidCodePoint(codePoint)) {
            ensureCapacityInternal(count + 2);
D
duke 已提交
737
            Character.toSurrogates(codePoint, value, count);
738 739 740
            this.count = count + 2;
        } else {
            throw new IllegalArgumentException();
D
duke 已提交
741 742 743 744 745
        }
        return this;
    }

    /**
746 747
     * Removes the {@code char} at the specified position in this
     * sequence. This sequence is shortened by one {@code char}.
D
duke 已提交
748 749 750 751
     *
     * <p>Note: If the character at the given index is a supplementary
     * character, this method does not remove the entire character. If
     * correct handling of supplementary characters is required,
752 753 754
     * determine the number of {@code char}s to remove by calling
     * {@code Character.charCount(thisSequence.codePointAt(index))},
     * where {@code thisSequence} is this sequence.
D
duke 已提交
755
     *
756
     * @param       index  Index of {@code char} to remove
D
duke 已提交
757
     * @return      This object.
758
     * @throws      StringIndexOutOfBoundsException  if the {@code index}
D
duke 已提交
759
     *              is negative or greater than or equal to
760
     *              {@code length()}.
D
duke 已提交
761 762 763 764 765 766 767 768 769 770 771
     */
    public AbstractStringBuilder deleteCharAt(int index) {
        if ((index < 0) || (index >= count))
            throw new StringIndexOutOfBoundsException(index);
        System.arraycopy(value, index+1, value, index, count-index-1);
        count--;
        return this;
    }

    /**
     * Replaces the characters in a substring of this sequence
772 773 774
     * with characters in the specified {@code String}. The substring
     * begins at the specified {@code start} and extends to the character
     * at index {@code end - 1} or to the end of the
D
duke 已提交
775 776
     * sequence if no such character exists. First the
     * characters in the substring are removed and then the specified
777
     * {@code String} is inserted at {@code start}. (This
D
duke 已提交
778 779 780 781 782 783 784
     * sequence will be lengthened to accommodate the
     * specified String if necessary.)
     *
     * @param      start    The beginning index, inclusive.
     * @param      end      The ending index, exclusive.
     * @param      str   String that will replace previous contents.
     * @return     This object.
785 786 787
     * @throws     StringIndexOutOfBoundsException  if {@code start}
     *             is negative, greater than {@code length()}, or
     *             greater than {@code end}.
D
duke 已提交
788 789 790 791 792 793 794 795 796 797 798 799 800
     */
    public AbstractStringBuilder replace(int start, int end, String str) {
        if (start < 0)
            throw new StringIndexOutOfBoundsException(start);
        if (start > count)
            throw new StringIndexOutOfBoundsException("start > length()");
        if (start > end)
            throw new StringIndexOutOfBoundsException("start > end");

        if (end > count)
            end = count;
        int len = str.length();
        int newCount = count + len - (end - start);
801
        ensureCapacityInternal(newCount);
D
duke 已提交
802 803 804 805 806 807 808 809

        System.arraycopy(value, end, value, start + len, count - end);
        str.getChars(value, start);
        count = newCount;
        return this;
    }

    /**
810
     * Returns a new {@code String} that contains a subsequence of
D
duke 已提交
811 812 813 814 815 816
     * characters currently contained in this character sequence. The
     * substring begins at the specified index and extends to the end of
     * this sequence.
     *
     * @param      start    The beginning index, inclusive.
     * @return     The new string.
817
     * @throws     StringIndexOutOfBoundsException  if {@code start} is
D
duke 已提交
818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854
     *             less than zero, or greater than the length of this object.
     */
    public String substring(int start) {
        return substring(start, count);
    }

    /**
     * Returns a new character sequence that is a subsequence of this sequence.
     *
     * <p> An invocation of this method of the form
     *
     * <blockquote><pre>
     * sb.subSequence(begin,&nbsp;end)</pre></blockquote>
     *
     * behaves in exactly the same way as the invocation
     *
     * <blockquote><pre>
     * sb.substring(begin,&nbsp;end)</pre></blockquote>
     *
     * This method is provided so that this class can
     * implement the {@link CharSequence} interface. </p>
     *
     * @param      start   the start index, inclusive.
     * @param      end     the end index, exclusive.
     * @return     the specified subsequence.
     *
     * @throws  IndexOutOfBoundsException
     *          if <tt>start</tt> or <tt>end</tt> are negative,
     *          if <tt>end</tt> is greater than <tt>length()</tt>,
     *          or if <tt>start</tt> is greater than <tt>end</tt>
     * @spec JSR-51
     */
    public CharSequence subSequence(int start, int end) {
        return substring(start, end);
    }

    /**
855
     * Returns a new {@code String} that contains a subsequence of
D
duke 已提交
856
     * characters currently contained in this sequence. The
857 858
     * substring begins at the specified {@code start} and
     * extends to the character at index {@code end - 1}.
D
duke 已提交
859 860 861 862
     *
     * @param      start    The beginning index, inclusive.
     * @param      end      The ending index, exclusive.
     * @return     The new string.
863 864 865 866
     * @throws     StringIndexOutOfBoundsException  if {@code start}
     *             or {@code end} are negative or greater than
     *             {@code length()}, or {@code start} is
     *             greater than {@code end}.
D
duke 已提交
867 868 869 870 871 872 873 874 875 876 877 878
     */
    public String substring(int start, int end) {
        if (start < 0)
            throw new StringIndexOutOfBoundsException(start);
        if (end > count)
            throw new StringIndexOutOfBoundsException(end);
        if (start > end)
            throw new StringIndexOutOfBoundsException(end - start);
        return new String(value, start, end - start);
    }

    /**
879
     * Inserts the string representation of a subarray of the {@code str}
D
duke 已提交
880
     * array argument into this sequence. The subarray begins at the
881
     * specified {@code offset} and extends {@code len} {@code char}s.
D
duke 已提交
882
     * The characters of the subarray are inserted into this sequence at
883 884
     * the position indicated by {@code index}. The length of this
     * sequence increases by {@code len} {@code char}s.
D
duke 已提交
885 886
     *
     * @param      index    position at which to insert subarray.
887 888
     * @param      str       A {@code char} array.
     * @param      offset   the index of the first {@code char} in subarray to
D
duke 已提交
889
     *             be inserted.
890
     * @param      len      the number of {@code char}s in the subarray to
D
duke 已提交
891 892
     *             be inserted.
     * @return     This object
893 894 895 896 897
     * @throws     StringIndexOutOfBoundsException  if {@code index}
     *             is negative or greater than {@code length()}, or
     *             {@code offset} or {@code len} are negative, or
     *             {@code (offset+len)} is greater than
     *             {@code str.length}.
D
duke 已提交
898
     */
899
    public AbstractStringBuilder insert(int index, char[] str, int offset,
D
duke 已提交
900 901 902 903 904 905 906 907
                                        int len)
    {
        if ((index < 0) || (index > length()))
            throw new StringIndexOutOfBoundsException(index);
        if ((offset < 0) || (len < 0) || (offset > str.length - len))
            throw new StringIndexOutOfBoundsException(
                "offset " + offset + ", len " + len + ", str.length "
                + str.length);
908
        ensureCapacityInternal(count + len);
D
duke 已提交
909 910
        System.arraycopy(value, index, value, index + len, count - index);
        System.arraycopy(str, offset, value, index, len);
911
        count += len;
D
duke 已提交
912 913 914 915
        return this;
    }

    /**
916
     * Inserts the string representation of the {@code Object}
D
duke 已提交
917 918
     * argument into this character sequence.
     * <p>
919 920 921 922 923
     * The overall effect is exactly as if the second argument were
     * converted to a string by the method {@link String#valueOf(Object)},
     * and the characters of that string were then
     * {@link #insert(int,String) inserted} into this character
     * sequence at the indicated offset.
D
duke 已提交
924
     * <p>
925 926 927
     * The {@code offset} argument must be greater than or equal to
     * {@code 0}, and less than or equal to the {@linkplain #length() length}
     * of this sequence.
D
duke 已提交
928 929
     *
     * @param      offset   the offset.
930
     * @param      obj      an {@code Object}.
D
duke 已提交
931 932 933 934 935 936 937 938 939 940
     * @return     a reference to this object.
     * @throws     StringIndexOutOfBoundsException  if the offset is invalid.
     */
    public AbstractStringBuilder insert(int offset, Object obj) {
        return insert(offset, String.valueOf(obj));
    }

    /**
     * Inserts the string into this character sequence.
     * <p>
941
     * The characters of the {@code String} argument are inserted, in
D
duke 已提交
942 943 944
     * order, into this sequence at the indicated offset, moving up any
     * characters originally above that position and increasing the length
     * of this sequence by the length of the argument. If
945 946
     * {@code str} is {@code null}, then the four characters
     * {@code "null"} are inserted into this sequence.
D
duke 已提交
947 948 949 950 951
     * <p>
     * The character at index <i>k</i> in the new character sequence is
     * equal to:
     * <ul>
     * <li>the character at index <i>k</i> in the old character sequence, if
952 953 954 955 956
     * <i>k</i> is less than {@code offset}
     * <li>the character at index <i>k</i>{@code -offset} in the
     * argument {@code str}, if <i>k</i> is not less than
     * {@code offset} but is less than {@code offset+str.length()}
     * <li>the character at index <i>k</i>{@code -str.length()} in the
D
duke 已提交
957
     * old character sequence, if <i>k</i> is not less than
958
     * {@code offset+str.length()}
D
duke 已提交
959
     * </ul><p>
960 961 962
     * The {@code offset} argument must be greater than or equal to
     * {@code 0}, and less than or equal to the {@linkplain #length() length}
     * of this sequence.
D
duke 已提交
963 964 965 966 967 968 969 970 971 972 973 974
     *
     * @param      offset   the offset.
     * @param      str      a string.
     * @return     a reference to this object.
     * @throws     StringIndexOutOfBoundsException  if the offset is invalid.
     */
    public AbstractStringBuilder insert(int offset, String str) {
        if ((offset < 0) || (offset > length()))
            throw new StringIndexOutOfBoundsException(offset);
        if (str == null)
            str = "null";
        int len = str.length();
975
        ensureCapacityInternal(count + len);
D
duke 已提交
976 977
        System.arraycopy(value, offset, value, offset + len, count - offset);
        str.getChars(value, offset);
978
        count += len;
D
duke 已提交
979 980 981 982
        return this;
    }

    /**
983
     * Inserts the string representation of the {@code char} array
D
duke 已提交
984 985 986 987
     * argument into this sequence.
     * <p>
     * The characters of the array argument are inserted into the
     * contents of this sequence at the position indicated by
988
     * {@code offset}. The length of this sequence increases by
D
duke 已提交
989 990
     * the length of the argument.
     * <p>
991 992 993 994 995 996 997 998 999
     * The overall effect is exactly as if the second argument were
     * converted to a string by the method {@link String#valueOf(char[])},
     * and the characters of that string were then
     * {@link #insert(int,String) inserted} into this character
     * sequence at the indicated offset.
     * <p>
     * The {@code offset} argument must be greater than or equal to
     * {@code 0}, and less than or equal to the {@linkplain #length() length}
     * of this sequence.
D
duke 已提交
1000 1001 1002 1003 1004 1005
     *
     * @param      offset   the offset.
     * @param      str      a character array.
     * @return     a reference to this object.
     * @throws     StringIndexOutOfBoundsException  if the offset is invalid.
     */
1006
    public AbstractStringBuilder insert(int offset, char[] str) {
D
duke 已提交
1007 1008 1009
        if ((offset < 0) || (offset > length()))
            throw new StringIndexOutOfBoundsException(offset);
        int len = str.length;
1010
        ensureCapacityInternal(count + len);
D
duke 已提交
1011 1012
        System.arraycopy(value, offset, value, offset + len, count - offset);
        System.arraycopy(str, 0, value, offset, len);
1013
        count += len;
D
duke 已提交
1014 1015 1016 1017
        return this;
    }

    /**
1018
     * Inserts the specified {@code CharSequence} into this sequence.
D
duke 已提交
1019
     * <p>
1020
     * The characters of the {@code CharSequence} argument are inserted,
D
duke 已提交
1021 1022 1023 1024 1025
     * in order, into this sequence at the indicated offset, moving up
     * any characters originally above that position and increasing the length
     * of this sequence by the length of the argument s.
     * <p>
     * The result of this method is exactly the same as if it were an
1026 1027 1028
     * invocation of this object's
     * {@link #insert(int,CharSequence,int,int) insert}(dstOffset, s, 0, s.length())
     * method.
D
duke 已提交
1029
     *
1030 1031
     * <p>If {@code s} is {@code null}, then the four characters
     * {@code "null"} are inserted into this sequence.
D
duke 已提交
1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046
     *
     * @param      dstOffset   the offset.
     * @param      s the sequence to be inserted
     * @return     a reference to this object.
     * @throws     IndexOutOfBoundsException  if the offset is invalid.
     */
    public AbstractStringBuilder insert(int dstOffset, CharSequence s) {
        if (s == null)
            s = "null";
        if (s instanceof String)
            return this.insert(dstOffset, (String)s);
        return this.insert(dstOffset, s, 0, s.length());
    }

    /**
1047
     * Inserts a subsequence of the specified {@code CharSequence} into
D
duke 已提交
1048 1049
     * this sequence.
     * <p>
1050 1051
     * The subsequence of the argument {@code s} specified by
     * {@code start} and {@code end} are inserted,
D
duke 已提交
1052 1053
     * in order, into this sequence at the specified destination offset, moving
     * up any characters originally above that position. The length of this
1054
     * sequence is increased by {@code end - start}.
D
duke 已提交
1055 1056 1057 1058
     * <p>
     * The character at index <i>k</i> in this sequence becomes equal to:
     * <ul>
     * <li>the character at index <i>k</i> in this sequence, if
1059 1060 1061 1062 1063
     * <i>k</i> is less than {@code dstOffset}
     * <li>the character at index <i>k</i>{@code +start-dstOffset} in
     * the argument {@code s}, if <i>k</i> is greater than or equal to
     * {@code dstOffset} but is less than {@code dstOffset+end-start}
     * <li>the character at index <i>k</i>{@code -(end-start)} in this
D
duke 已提交
1064
     * sequence, if <i>k</i> is greater than or equal to
1065
     * {@code dstOffset+end-start}
D
duke 已提交
1066
     * </ul><p>
1067 1068 1069
     * The {@code dstOffset} argument must be greater than or equal to
     * {@code 0}, and less than or equal to the {@linkplain #length() length}
     * of this sequence.
D
duke 已提交
1070
     * <p>The start argument must be nonnegative, and not greater than
1071
     * {@code end}.
D
duke 已提交
1072
     * <p>The end argument must be greater than or equal to
1073
     * {@code start}, and less than or equal to the length of s.
D
duke 已提交
1074
     *
1075
     * <p>If {@code s} is {@code null}, then this method inserts
D
duke 已提交
1076
     * characters as if the s parameter was a sequence containing the four
1077
     * characters {@code "null"}.
D
duke 已提交
1078 1079 1080 1081 1082 1083
     *
     * @param      dstOffset   the offset in this sequence.
     * @param      s       the sequence to be inserted.
     * @param      start   the starting index of the subsequence to be inserted.
     * @param      end     the end index of the subsequence to be inserted.
     * @return     a reference to this object.
1084 1085 1086 1087 1088
     * @throws     IndexOutOfBoundsException  if {@code dstOffset}
     *             is negative or greater than {@code this.length()}, or
     *              {@code start} or {@code end} are negative, or
     *              {@code start} is greater than {@code end} or
     *              {@code end} is greater than {@code s.length()}
D
duke 已提交
1089 1090
     */
     public AbstractStringBuilder insert(int dstOffset, CharSequence s,
1091
                                         int start, int end) {
D
duke 已提交
1092 1093 1094 1095 1096 1097 1098 1099 1100
        if (s == null)
            s = "null";
        if ((dstOffset < 0) || (dstOffset > this.length()))
            throw new IndexOutOfBoundsException("dstOffset "+dstOffset);
        if ((start < 0) || (end < 0) || (start > end) || (end > s.length()))
            throw new IndexOutOfBoundsException(
                "start " + start + ", end " + end + ", s.length() "
                + s.length());
        int len = end - start;
1101
        ensureCapacityInternal(count + len);
D
duke 已提交
1102 1103 1104 1105
        System.arraycopy(value, dstOffset, value, dstOffset + len,
                         count - dstOffset);
        for (int i=start; i<end; i++)
            value[dstOffset++] = s.charAt(i);
1106
        count += len;
D
duke 已提交
1107 1108 1109 1110
        return this;
    }

    /**
1111
     * Inserts the string representation of the {@code boolean}
D
duke 已提交
1112 1113
     * argument into this sequence.
     * <p>
1114 1115 1116 1117 1118
     * The overall effect is exactly as if the second argument were
     * converted to a string by the method {@link String#valueOf(boolean)},
     * and the characters of that string were then
     * {@link #insert(int,String) inserted} into this character
     * sequence at the indicated offset.
D
duke 已提交
1119
     * <p>
1120 1121 1122
     * The {@code offset} argument must be greater than or equal to
     * {@code 0}, and less than or equal to the {@linkplain #length() length}
     * of this sequence.
D
duke 已提交
1123 1124
     *
     * @param      offset   the offset.
1125
     * @param      b        a {@code boolean}.
D
duke 已提交
1126 1127 1128 1129 1130 1131 1132 1133
     * @return     a reference to this object.
     * @throws     StringIndexOutOfBoundsException  if the offset is invalid.
     */
    public AbstractStringBuilder insert(int offset, boolean b) {
        return insert(offset, String.valueOf(b));
    }

    /**
1134
     * Inserts the string representation of the {@code char}
D
duke 已提交
1135 1136
     * argument into this sequence.
     * <p>
1137 1138 1139 1140 1141
     * The overall effect is exactly as if the second argument were
     * converted to a string by the method {@link String#valueOf(char)},
     * and the character in that string were then
     * {@link #insert(int,String) inserted} into this character
     * sequence at the indicated offset.
D
duke 已提交
1142
     * <p>
1143 1144 1145
     * The {@code offset} argument must be greater than or equal to
     * {@code 0}, and less than or equal to the {@linkplain #length() length}
     * of this sequence.
D
duke 已提交
1146 1147
     *
     * @param      offset   the offset.
1148
     * @param      c        a {@code char}.
D
duke 已提交
1149 1150 1151 1152
     * @return     a reference to this object.
     * @throws     IndexOutOfBoundsException  if the offset is invalid.
     */
    public AbstractStringBuilder insert(int offset, char c) {
1153
        ensureCapacityInternal(count + 1);
D
duke 已提交
1154 1155
        System.arraycopy(value, offset, value, offset + 1, count - offset);
        value[offset] = c;
1156
        count += 1;
D
duke 已提交
1157 1158 1159 1160
        return this;
    }

    /**
1161
     * Inserts the string representation of the second {@code int}
D
duke 已提交
1162 1163
     * argument into this sequence.
     * <p>
1164 1165 1166 1167 1168
     * The overall effect is exactly as if the second argument were
     * converted to a string by the method {@link String#valueOf(int)},
     * and the characters of that string were then
     * {@link #insert(int,String) inserted} into this character
     * sequence at the indicated offset.
D
duke 已提交
1169
     * <p>
1170 1171 1172
     * The {@code offset} argument must be greater than or equal to
     * {@code 0}, and less than or equal to the {@linkplain #length() length}
     * of this sequence.
D
duke 已提交
1173 1174
     *
     * @param      offset   the offset.
1175
     * @param      i        an {@code int}.
D
duke 已提交
1176 1177 1178 1179 1180 1181 1182 1183
     * @return     a reference to this object.
     * @throws     StringIndexOutOfBoundsException  if the offset is invalid.
     */
    public AbstractStringBuilder insert(int offset, int i) {
        return insert(offset, String.valueOf(i));
    }

    /**
1184
     * Inserts the string representation of the {@code long}
D
duke 已提交
1185 1186
     * argument into this sequence.
     * <p>
1187 1188 1189 1190 1191
     * The overall effect is exactly as if the second argument were
     * converted to a string by the method {@link String#valueOf(long)},
     * and the characters of that string were then
     * {@link #insert(int,String) inserted} into this character
     * sequence at the indicated offset.
D
duke 已提交
1192
     * <p>
1193 1194 1195
     * The {@code offset} argument must be greater than or equal to
     * {@code 0}, and less than or equal to the {@linkplain #length() length}
     * of this sequence.
D
duke 已提交
1196 1197
     *
     * @param      offset   the offset.
1198
     * @param      l        a {@code long}.
D
duke 已提交
1199 1200 1201 1202 1203 1204 1205 1206
     * @return     a reference to this object.
     * @throws     StringIndexOutOfBoundsException  if the offset is invalid.
     */
    public AbstractStringBuilder insert(int offset, long l) {
        return insert(offset, String.valueOf(l));
    }

    /**
1207
     * Inserts the string representation of the {@code float}
D
duke 已提交
1208 1209
     * argument into this sequence.
     * <p>
1210 1211 1212 1213 1214
     * The overall effect is exactly as if the second argument were
     * converted to a string by the method {@link String#valueOf(float)},
     * and the characters of that string were then
     * {@link #insert(int,String) inserted} into this character
     * sequence at the indicated offset.
D
duke 已提交
1215
     * <p>
1216 1217 1218
     * The {@code offset} argument must be greater than or equal to
     * {@code 0}, and less than or equal to the {@linkplain #length() length}
     * of this sequence.
D
duke 已提交
1219 1220
     *
     * @param      offset   the offset.
1221
     * @param      f        a {@code float}.
D
duke 已提交
1222 1223 1224 1225 1226 1227 1228 1229
     * @return     a reference to this object.
     * @throws     StringIndexOutOfBoundsException  if the offset is invalid.
     */
    public AbstractStringBuilder insert(int offset, float f) {
        return insert(offset, String.valueOf(f));
    }

    /**
1230
     * Inserts the string representation of the {@code double}
D
duke 已提交
1231 1232
     * argument into this sequence.
     * <p>
1233 1234 1235 1236 1237
     * The overall effect is exactly as if the second argument were
     * converted to a string by the method {@link String#valueOf(double)},
     * and the characters of that string were then
     * {@link #insert(int,String) inserted} into this character
     * sequence at the indicated offset.
D
duke 已提交
1238
     * <p>
1239 1240 1241
     * The {@code offset} argument must be greater than or equal to
     * {@code 0}, and less than or equal to the {@linkplain #length() length}
     * of this sequence.
D
duke 已提交
1242 1243
     *
     * @param      offset   the offset.
1244
     * @param      d        a {@code double}.
D
duke 已提交
1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258
     * @return     a reference to this object.
     * @throws     StringIndexOutOfBoundsException  if the offset is invalid.
     */
    public AbstractStringBuilder insert(int offset, double d) {
        return insert(offset, String.valueOf(d));
    }

    /**
     * Returns the index within this string of the first occurrence of the
     * specified substring. The integer returned is the smallest value
     * <i>k</i> such that:
     * <blockquote><pre>
     * this.toString().startsWith(str, <i>k</i>)
     * </pre></blockquote>
1259
     * is {@code true}.
D
duke 已提交
1260 1261 1262 1263 1264
     *
     * @param   str   any string.
     * @return  if the string argument occurs as a substring within this
     *          object, then the index of the first character of the first
     *          such substring is returned; if it does not occur as a
1265 1266 1267
     *          substring, {@code -1} is returned.
     * @throws  java.lang.NullPointerException if {@code str} is
     *          {@code null}.
D
duke 已提交
1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286
     */
    public int indexOf(String str) {
        return indexOf(str, 0);
    }

    /**
     * Returns the index within this string of the first occurrence of the
     * specified substring, starting at the specified index.  The integer
     * returned is the smallest value <tt>k</tt> for which:
     * <blockquote><pre>
     *     k >= Math.min(fromIndex, str.length()) &&
     *                   this.toString().startsWith(str, k)
     * </pre></blockquote>
     * If no such value of <i>k</i> exists, then -1 is returned.
     *
     * @param   str         the substring for which to search.
     * @param   fromIndex   the index from which to start the search.
     * @return  the index within this string of the first occurrence of the
     *          specified substring, starting at the specified index.
1287 1288
     * @throws  java.lang.NullPointerException if {@code str} is
     *            {@code null}.
D
duke 已提交
1289 1290 1291 1292 1293 1294 1295 1296 1297
     */
    public int indexOf(String str, int fromIndex) {
        return String.indexOf(value, 0, count,
                              str.toCharArray(), 0, str.length(), fromIndex);
    }

    /**
     * Returns the index within this string of the rightmost occurrence
     * of the specified substring.  The rightmost empty string "" is
1298
     * considered to occur at the index value {@code this.length()}.
D
duke 已提交
1299 1300 1301 1302 1303 1304 1305 1306 1307 1308
     * The returned index is the largest value <i>k</i> such that
     * <blockquote><pre>
     * this.toString().startsWith(str, k)
     * </pre></blockquote>
     * is true.
     *
     * @param   str   the substring to search for.
     * @return  if the string argument occurs one or more times as a substring
     *          within this object, then the index of the first character of
     *          the last such substring is returned. If it does not occur as
1309 1310 1311
     *          a substring, {@code -1} is returned.
     * @throws  java.lang.NullPointerException  if {@code str} is
     *          {@code null}.
D
duke 已提交
1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330
     */
    public int lastIndexOf(String str) {
        return lastIndexOf(str, count);
    }

    /**
     * Returns the index within this string of the last occurrence of the
     * specified substring. The integer returned is the largest value <i>k</i>
     * such that:
     * <blockquote><pre>
     *     k <= Math.min(fromIndex, str.length()) &&
     *                   this.toString().startsWith(str, k)
     * </pre></blockquote>
     * If no such value of <i>k</i> exists, then -1 is returned.
     *
     * @param   str         the substring to search for.
     * @param   fromIndex   the index to start the search from.
     * @return  the index within this sequence of the last occurrence of the
     *          specified substring.
1331 1332
     * @throws  java.lang.NullPointerException if {@code str} is
     *          {@code null}.
D
duke 已提交
1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346
     */
    public int lastIndexOf(String str, int fromIndex) {
        return String.lastIndexOf(value, 0, count,
                              str.toCharArray(), 0, str.length(), fromIndex);
    }

    /**
     * Causes this character sequence to be replaced by the reverse of
     * the sequence. If there are any surrogate pairs included in the
     * sequence, these are treated as single characters for the
     * reverse operation. Thus, the order of the high-low surrogates
     * is never reversed.
     *
     * Let <i>n</i> be the character length of this character sequence
1347 1348
     * (not the length in {@code char} values) just prior to
     * execution of the {@code reverse} method. Then the
D
duke 已提交
1349 1350 1351 1352 1353 1354 1355
     * character at index <i>k</i> in the new character sequence is
     * equal to the character at index <i>n-k-1</i> in the old
     * character sequence.
     *
     * <p>Note that the reverse operation may result in producing
     * surrogate pairs that were unpaired low-surrogates and
     * high-surrogates before the operation. For example, reversing
1356
     * "\u005CuDC00\u005CuD800" produces "\u005CuD800\u005CuDC00" which is
D
duke 已提交
1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391
     * a valid surrogate pair.
     *
     * @return  a reference to this object.
     */
    public AbstractStringBuilder reverse() {
        boolean hasSurrogate = false;
        int n = count - 1;
        for (int j = (n-1) >> 1; j >= 0; --j) {
            char temp = value[j];
            char temp2 = value[n - j];
            if (!hasSurrogate) {
                hasSurrogate = (temp >= Character.MIN_SURROGATE && temp <= Character.MAX_SURROGATE)
                    || (temp2 >= Character.MIN_SURROGATE && temp2 <= Character.MAX_SURROGATE);
            }
            value[j] = temp2;
            value[n - j] = temp;
        }
        if (hasSurrogate) {
            // Reverse back all valid surrogate pairs
            for (int i = 0; i < count - 1; i++) {
                char c2 = value[i];
                if (Character.isLowSurrogate(c2)) {
                    char c1 = value[i + 1];
                    if (Character.isHighSurrogate(c1)) {
                        value[i++] = c1;
                        value[i] = c2;
                    }
                }
            }
        }
        return this;
    }

    /**
     * Returns a string representing the data in this sequence.
1392
     * A new {@code String} object is allocated and initialized to
D
duke 已提交
1393
     * contain the character sequence currently represented by this
1394
     * object. This {@code String} is then returned. Subsequent
D
duke 已提交
1395
     * changes to this sequence do not affect the contents of the
1396
     * {@code String}.
D
duke 已提交
1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409
     *
     * @return  a string representation of this sequence of characters.
     */
    public abstract String toString();

    /**
     * Needed by <tt>String</tt> for the contentEquals method.
     */
    final char[] getValue() {
        return value;
    }

}