1 /*
2 * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27
28 import jdk.internal.math.FloatingDecimal;
29 import java.util.Arrays;
30 import java.util.Spliterator;
31 import java.util.stream.IntStream;
32 import java.util.stream.StreamSupport;
33
34 import static java.lang.String.COMPACT_STRINGS;
35 import static java.lang.String.UTF16;
36 import static java.lang.String.LATIN1;
37 import static java.lang.String.checkIndex;
38 import static java.lang.String.checkOffset;
39
40 /**
41 * A mutable sequence of characters.
42 * <p>
43 * Implements a modifiable string. At any point in time it contains some
44 * particular sequence of characters, but the length and content of the
45 * sequence can be changed through certain method calls.
46 *
47 * <p>Unless otherwise noted, passing a {@code null} argument to a constructor
48 * or method in this class will cause a {@link NullPointerException} to be
49 * thrown.
50 *
51 * @author Michael McCloskey
52 * @author Martin Buchholz
53 * @author Ulf Zibis
54 * @since 1.5
55 */
56 abstract class AbstractStringBuilder implements Appendable, CharSequence {
57 /**
58 * The value is used for character storage.
59 */
60 byte[] value;
61
62 /**
63 * The id of the encoding used to encode the bytes in {@code value}.
64 */
65 byte coder;
66
67 /**
68 * The count is the number of characters used.
69 */
70 int count;
71
72 private static final byte[] EMPTYVALUE = new byte[0];
73
74 /**
75 * This no-arg constructor is necessary for serialization of subclasses.
76 */
77 AbstractStringBuilder() {
78 value = EMPTYVALUE;
79 }
80
81 /**
82 * Creates an AbstractStringBuilder of the specified capacity.
83 */
84 AbstractStringBuilder(int capacity) {
85 if (COMPACT_STRINGS) {
86 value = new byte[capacity];
87 coder = LATIN1;
88 } else {
89 value = StringUTF16.newBytesFor(capacity);
90 coder = UTF16;
91 }
92 }
93
94 /**
95 * Creates an AbstractStringBuilder with the specified coder
96 * (coderHint is used when compact strings are enabled) and with
97 * the initial capacity equal to the smaller of (length + addition)
98 * and Integer.MAX_VALUE.
99 */
100 AbstractStringBuilder(byte coderHint, int length, int addition) {
101 if (length < 0) {
102 throw new NegativeArraySizeException("Negative length: " + length);
103 }
104 int capacity = (length < Integer.MAX_VALUE - addition)
105 ? length + addition : Integer.MAX_VALUE;
106 if (COMPACT_STRINGS && coderHint == LATIN1) {
107 value = new byte[capacity];
108 coder = LATIN1;
109 } else {
110 value = StringUTF16.newBytesFor(capacity);
111 coder = UTF16;
112 }
113 }
114
115 /**
116 * Compares the objects of two AbstractStringBuilder implementations lexicographically.
117 *
118 * @since 11
119 */
120 int compareTo(AbstractStringBuilder another) {
121 if (this == another) {
122 return 0;
123 }
124
125 byte val1[] = value;
126 byte val2[] = another.value;
127 int count1 = this.count;
128 int count2 = another.count;
129
130 if (coder == another.coder) {
131 return isLatin1() ? StringLatin1.compareTo(val1, val2, count1, count2)
132 : StringUTF16.compareTo(val1, val2, count1, count2);
133 }
134 return isLatin1() ? StringLatin1.compareToUTF16(val1, val2, count1, count2)
135 : StringUTF16.compareToLatin1(val1, val2, count1, count2);
136 }
137
138 /**
139 * Returns the length (character count).
140 *
141 * @return the length of the sequence of characters currently
142 * represented by this object
143 */
144 @Override
145 public int length() {
146 return count;
147 }
148
149 /**
150 * Returns the current capacity. The capacity is the amount of storage
151 * available for newly inserted characters, beyond which an allocation
152 * will occur.
153 *
154 * @return the current capacity
155 */
156 public int capacity() {
157 return value.length >> coder;
158 }
159
160 /**
161 * Ensures that the capacity is at least equal to the specified minimum.
162 * If the current capacity is less than the argument, then a new internal
163 * array is allocated with greater capacity. The new capacity is the
164 * larger of:
165 * <ul>
166 * <li>The {@code minimumCapacity} argument.
167 * <li>Twice the old capacity, plus {@code 2}.
168 * </ul>
169 * If the {@code minimumCapacity} argument is nonpositive, this
170 * method takes no action and simply returns.
171 * Note that subsequent operations on this object can reduce the
172 * actual capacity below that requested here.
173 *
174 * @param minimumCapacity the minimum desired capacity.
175 */
176 public void ensureCapacity(int minimumCapacity) {
177 if (minimumCapacity > 0) {
178 ensureCapacityInternal(minimumCapacity);
179 }
180 }
181
182 /**
183 * For positive values of {@code minimumCapacity}, this method
184 * behaves like {@code ensureCapacity}, however it is never
185 * synchronized.
186 * If {@code minimumCapacity} is non positive due to numeric
187 * overflow, this method throws {@code OutOfMemoryError}.
188 */
189 private void ensureCapacityInternal(int minimumCapacity) {
190 // overflow-conscious code
191 int oldCapacity = value.length >> coder;
192 if (minimumCapacity - oldCapacity > 0) {
193 value = Arrays.copyOf(value,
194 newCapacity(minimumCapacity) << coder);
195 }
196 }
197
198 /**
199 * The maximum size of array to allocate (unless necessary).
200 * Some VMs reserve some header words in an array.
201 * Attempts to allocate larger arrays may result in
202 * OutOfMemoryError: Requested array size exceeds VM limit
203 */
204 private static final int MAX_ARRAY_SIZE = Integer.MAX_VALUE - 8;
205
206 /**
207 * Returns a capacity at least as large as the given minimum capacity.
208 * Returns the current capacity increased by the same amount + 2 if
209 * that suffices.
210 * Will not return a capacity greater than
211 * {@code (MAX_ARRAY_SIZE >> coder)} unless the given minimum capacity
212 * is greater than that.
213 *
214 * @param minCapacity the desired minimum capacity
215 * @throws OutOfMemoryError if minCapacity is less than zero or
216 * greater than (Integer.MAX_VALUE >> coder)
217 */
218 private int newCapacity(int minCapacity) {
219 // overflow-conscious code
220 int oldCapacity = value.length >> coder;
221 int newCapacity = (oldCapacity << 1) + 2;
222 if (newCapacity - minCapacity < 0) {
223 newCapacity = minCapacity;
224 }
225 int SAFE_BOUND = MAX_ARRAY_SIZE >> coder;
226 return (newCapacity <= 0 || SAFE_BOUND - newCapacity < 0)
227 ? hugeCapacity(minCapacity)
228 : newCapacity;
229 }
230
231 private int hugeCapacity(int minCapacity) {
232 int SAFE_BOUND = MAX_ARRAY_SIZE >> coder;
233 int UNSAFE_BOUND = Integer.MAX_VALUE >> coder;
234 if (UNSAFE_BOUND - minCapacity < 0) { // overflow
235 throw new OutOfMemoryError();
236 }
237 return (minCapacity > SAFE_BOUND)
238 ? minCapacity : SAFE_BOUND;
239 }
240
241 /**
242 * If the coder is "isLatin1", this inflates the internal 8-bit storage
243 * to 16-bit <hi=0, low> pair storage.
244 */
245 private void inflate() {
246 if (!isLatin1()) {
247 return;
248 }
249 byte[] buf = StringUTF16.newBytesFor(value.length);
250 StringLatin1.inflate(value, 0, buf, 0, count);
251 this.value = buf;
252 this.coder = UTF16;
253 }
254
255 /**
256 * Attempts to reduce storage used for the character sequence.
257 * If the buffer is larger than necessary to hold its current sequence of
258 * characters, then it may be resized to become more space efficient.
259 * Calling this method may, but is not required to, affect the value
260 * returned by a subsequent call to the {@link #capacity()} method.
261 */
262 public void trimToSize() {
263 int length = count << coder;
264 if (length < value.length) {
265 value = Arrays.copyOf(value, length);
266 }
267 }
268
269 /**
270 * Sets the length of the character sequence.
271 * The sequence is changed to a new character sequence
272 * whose length is specified by the argument. For every nonnegative
273 * index <i>k</i> less than {@code newLength}, the character at
274 * index <i>k</i> in the new character sequence is the same as the
275 * character at index <i>k</i> in the old sequence if <i>k</i> is less
276 * than the length of the old character sequence; otherwise, it is the
277 * null character {@code '\u005Cu0000'}.
278 *
279 * In other words, if the {@code newLength} argument is less than
280 * the current length, the length is changed to the specified length.
281 * <p>
282 * If the {@code newLength} argument is greater than or equal
283 * to the current length, sufficient null characters
284 * ({@code '\u005Cu0000'}) are appended so that
285 * length becomes the {@code newLength} argument.
286 * <p>
287 * The {@code newLength} argument must be greater than or equal
288 * to {@code 0}.
289 *
290 * @param newLength the new length
291 * @throws IndexOutOfBoundsException if the
292 * {@code newLength} argument is negative.
293 */
294 public void setLength(int newLength) {
295 if (newLength < 0) {
296 throw new StringIndexOutOfBoundsException(newLength);
297 }
298 ensureCapacityInternal(newLength);
299 if (count < newLength) {
300 if (isLatin1()) {
301 StringLatin1.fillNull(value, count, newLength);
302 } else {
303 StringUTF16.fillNull(value, count, newLength);
304 }
305 }
306 count = newLength;
307 }
308
309 /**
310 * Returns the {@code char} value in this sequence at the specified index.
311 * The first {@code char} value is at index {@code 0}, the next at index
312 * {@code 1}, and so on, as in array indexing.
313 * <p>
314 * The index argument must be greater than or equal to
315 * {@code 0}, and less than the length of this sequence.
316 *
317 * <p>If the {@code char} value specified by the index is a
318 * <a href="Character.html#unicode">surrogate</a>, the surrogate
319 * value is returned.
320 *
321 * @param index the index of the desired {@code char} value.
322 * @return the {@code char} value at the specified index.
323 * @throws IndexOutOfBoundsException if {@code index} is
324 * negative or greater than or equal to {@code length()}.
325 */
326 @Override
327 public char charAt(int index) {
328 checkIndex(index, count);
329 if (isLatin1()) {
330 return (char)(value[index] & 0xff);
331 }
332 return StringUTF16.charAt(value, index);
333 }
334
335 /**
336 * Returns the character (Unicode code point) at the specified
337 * index. The index refers to {@code char} values
338 * (Unicode code units) and ranges from {@code 0} to
339 * {@link #length()}{@code - 1}.
340 *
341 * <p> If the {@code char} value specified at the given index
342 * is in the high-surrogate range, the following index is less
343 * than the length of this sequence, and the
344 * {@code char} value at the following index is in the
345 * low-surrogate range, then the supplementary code point
346 * corresponding to this surrogate pair is returned. Otherwise,
347 * the {@code char} value at the given index is returned.
348 *
349 * @param index the index to the {@code char} values
350 * @return the code point value of the character at the
351 * {@code index}
352 * @throws IndexOutOfBoundsException if the {@code index}
353 * argument is negative or not less than the length of this
354 * sequence.
355 */
356 public int codePointAt(int index) {
357 int count = this.count;
358 byte[] value = this.value;
359 checkIndex(index, count);
360 if (isLatin1()) {
361 return value[index] & 0xff;
362 }
363 return StringUTF16.codePointAtSB(value, index, count);
364 }
365
366 /**
367 * Returns the character (Unicode code point) before the specified
368 * index. The index refers to {@code char} values
369 * (Unicode code units) and ranges from {@code 1} to {@link
370 * #length()}.
371 *
372 * <p> If the {@code char} value at {@code (index - 1)}
373 * is in the low-surrogate range, {@code (index - 2)} is not
374 * negative, and the {@code char} value at {@code (index -
375 * 2)} is in the high-surrogate range, then the
376 * supplementary code point value of the surrogate pair is
377 * returned. If the {@code char} value at {@code index -
378 * 1} is an unpaired low-surrogate or a high-surrogate, the
379 * surrogate value is returned.
380 *
381 * @param index the index following the code point that should be returned
382 * @return the Unicode code point value before the given index.
383 * @throws IndexOutOfBoundsException if the {@code index}
384 * argument is less than 1 or greater than the length
385 * of this sequence.
386 */
387 public int codePointBefore(int index) {
388 int i = index - 1;
389 if (i < 0 || i >= count) {
390 throw new StringIndexOutOfBoundsException(index);
391 }
392 if (isLatin1()) {
393 return value[i] & 0xff;
394 }
395 return StringUTF16.codePointBeforeSB(value, index);
396 }
397
398 /**
399 * Returns the number of Unicode code points in the specified text
400 * range of this sequence. The text range begins at the specified
401 * {@code beginIndex} and extends to the {@code char} at
402 * index {@code endIndex - 1}. Thus the length (in
403 * {@code char}s) of the text range is
404 * {@code endIndex-beginIndex}. Unpaired surrogates within
405 * this sequence count as one code point each.
406 *
407 * @param beginIndex the index to the first {@code char} of
408 * the text range.
409 * @param endIndex the index after the last {@code char} of
410 * the text range.
411 * @return the number of Unicode code points in the specified text
412 * range
413 * @throws IndexOutOfBoundsException if the
414 * {@code beginIndex} is negative, or {@code endIndex}
415 * is larger than the length of this sequence, or
416 * {@code beginIndex} is larger than {@code endIndex}.
417 */
418 public int codePointCount(int beginIndex, int endIndex) {
419 if (beginIndex < 0 || endIndex > count || beginIndex > endIndex) {
420 throw new IndexOutOfBoundsException();
421 }
422 if (isLatin1()) {
423 return endIndex - beginIndex;
424 }
425 return StringUTF16.codePointCountSB(value, beginIndex, endIndex);
426 }
427
428 /**
429 * Returns the index within this sequence that is offset from the
430 * given {@code index} by {@code codePointOffset} code
431 * points. Unpaired surrogates within the text range given by
432 * {@code index} and {@code codePointOffset} count as
433 * one code point each.
434 *
435 * @param index the index to be offset
436 * @param codePointOffset the offset in code points
437 * @return the index within this sequence
438 * @throws IndexOutOfBoundsException if {@code index}
439 * is negative or larger then the length of this sequence,
440 * or if {@code codePointOffset} is positive and the subsequence
441 * starting with {@code index} has fewer than
442 * {@code codePointOffset} code points,
443 * or if {@code codePointOffset} is negative and the subsequence
444 * before {@code index} has fewer than the absolute value of
445 * {@code codePointOffset} code points.
446 */
447 public int offsetByCodePoints(int index, int codePointOffset) {
448 if (index < 0 || index > count) {
449 throw new IndexOutOfBoundsException();
450 }
451 return Character.offsetByCodePoints(this,
452 index, codePointOffset);
453 }
454
455 /**
456 * Characters are copied from this sequence into the
457 * destination character array {@code dst}. The first character to
458 * be copied is at index {@code srcBegin}; the last character to
459 * be copied is at index {@code srcEnd-1}. The total number of
460 * characters to be copied is {@code srcEnd-srcBegin}. The
461 * characters are copied into the subarray of {@code dst} starting
462 * at index {@code dstBegin} and ending at index:
463 * <pre>{@code
464 * dstbegin + (srcEnd-srcBegin) - 1
465 * }</pre>
466 *
467 * @param srcBegin start copying at this offset.
468 * @param srcEnd stop copying at this offset.
469 * @param dst the array to copy the data into.
470 * @param dstBegin offset into {@code dst}.
471 * @throws IndexOutOfBoundsException if any of the following is true:
472 * <ul>
473 * <li>{@code srcBegin} is negative
474 * <li>{@code dstBegin} is negative
475 * <li>the {@code srcBegin} argument is greater than
476 * the {@code srcEnd} argument.
477 * <li>{@code srcEnd} is greater than
478 * {@code this.length()}.
479 * <li>{@code dstBegin+srcEnd-srcBegin} is greater than
480 * {@code dst.length}
481 * </ul>
482 */
483 public void getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)
484 {
485 checkRangeSIOOBE(srcBegin, srcEnd, count); // compatible to old version
486 int n = srcEnd - srcBegin;
487 checkRange(dstBegin, dstBegin + n, dst.length);
488 if (isLatin1()) {
489 StringLatin1.getChars(value, srcBegin, srcEnd, dst, dstBegin);
490 } else {
491 StringUTF16.getChars(value, srcBegin, srcEnd, dst, dstBegin);
492 }
493 }
494
495 /**
496 * The character at the specified index is set to {@code ch}. This
497 * sequence is altered to represent a new character sequence that is
498 * identical to the old character sequence, except that it contains the
499 * character {@code ch} at position {@code index}.
500 * <p>
501 * The index argument must be greater than or equal to
502 * {@code 0}, and less than the length of this sequence.
503 *
504 * @param index the index of the character to modify.
505 * @param ch the new character.
506 * @throws IndexOutOfBoundsException if {@code index} is
507 * negative or greater than or equal to {@code length()}.
508 */
509 public void setCharAt(int index, char ch) {
510 checkIndex(index, count);
511 if (isLatin1() && StringLatin1.canEncode(ch)) {
512 value[index] = (byte)ch;
513 } else {
514 if (isLatin1()) {
515 inflate();
516 }
517 StringUTF16.putCharSB(value, index, ch);
518 }
519 }
520
521 /**
522 * Appends the string representation of the {@code Object} argument.
523 * <p>
524 * The overall effect is exactly as if the argument were converted
525 * to a string by the method {@link String#valueOf(Object)},
526 * and the characters of that string were then
527 * {@link #append(String) appended} to this character sequence.
528 *
529 * @param obj an {@code Object}.
530 * @return a reference to this object.
531 */
532 public AbstractStringBuilder append(Object obj) {
533 return append(String.valueOf(obj));
534 }
535
536 /**
537 * Appends the specified string to this character sequence.
538 * <p>
539 * The characters of the {@code String} argument are appended, in
540 * order, increasing the length of this sequence by the length of the
541 * argument. If {@code str} is {@code null}, then the four
542 * characters {@code "null"} are appended.
543 * <p>
544 * Let <i>n</i> be the length of this character sequence just prior to
545 * execution of the {@code append} method. Then the character at
546 * index <i>k</i> in the new character sequence is equal to the character
547 * at index <i>k</i> in the old character sequence, if <i>k</i> is less
548 * than <i>n</i>; otherwise, it is equal to the character at index
549 * <i>k-n</i> in the argument {@code str}.
550 *
551 * @param str a string.
552 * @return a reference to this object.
553 */
554 public AbstractStringBuilder append(String str) {
555 if (str == null) {
556 return appendNull();
557 }
558 int len = str.length();
559 ensureCapacityInternal(count + len);
560 putStringAt(count, str);
561 count += len;
562 return this;
563 }
564
565 // Documentation in subclasses because of synchro difference
566 public AbstractStringBuilder append(StringBuffer sb) {
567 return this.append((AbstractStringBuilder)sb);
568 }
569
570 /**
571 * @since 1.8
572 */
573 AbstractStringBuilder append(AbstractStringBuilder asb) {
574 if (asb == null) {
575 return appendNull();
576 }
577 int len = asb.length();
578 ensureCapacityInternal(count + len);
579 if (getCoder() != asb.getCoder()) {
580 inflate();
581 }
582 asb.getBytes(value, count, coder);
583 count += len;
584 return this;
585 }
586
587 // Documentation in subclasses because of synchro difference
588 @Override
589 public AbstractStringBuilder append(CharSequence s) {
590 if (s == null) {
591 return appendNull();
592 }
593 if (s instanceof String) {
594 return this.append((String)s);
595 }
596 if (s instanceof AbstractStringBuilder) {
597 return this.append((AbstractStringBuilder)s);
598 }
599 return this.append(s, 0, s.length());
600 }
601
602 private AbstractStringBuilder appendNull() {
603 ensureCapacityInternal(count + 4);
604 int count = this.count;
605 byte[] val = this.value;
606 if (isLatin1()) {
607 val[count++] = 'n';
608 val[count++] = 'u';
609 val[count++] = 'l';
610 val[count++] = 'l';
611 } else {
612 count = StringUTF16.putCharsAt(val, count, 'n', 'u', 'l', 'l');
613 }
614 this.count = count;
615 return this;
616 }
617
618 /**
619 * Appends a subsequence of the specified {@code CharSequence} to this
620 * sequence.
621 * <p>
622 * Characters of the argument {@code s}, starting at
623 * index {@code start}, are appended, in order, to the contents of
624 * this sequence up to the (exclusive) index {@code end}. The length
625 * of this sequence is increased by the value of {@code end - start}.
626 * <p>
627 * Let <i>n</i> be the length of this character sequence just prior to
628 * execution of the {@code append} method. Then the character at
629 * index <i>k</i> in this character sequence becomes equal to the
630 * character at index <i>k</i> in this sequence, if <i>k</i> is less than
631 * <i>n</i>; otherwise, it is equal to the character at index
632 * <i>k+start-n</i> in the argument {@code s}.
633 * <p>
634 * If {@code s} is {@code null}, then this method appends
635 * characters as if the s parameter was a sequence containing the four
636 * characters {@code "null"}.
637 *
638 * @param s the sequence to append.
639 * @param start the starting index of the subsequence to be appended.
640 * @param end the end index of the subsequence to be appended.
641 * @return a reference to this object.
642 * @throws IndexOutOfBoundsException if
643 * {@code start} is negative, or
644 * {@code start} is greater than {@code end} or
645 * {@code end} is greater than {@code s.length()}
646 */
647 @Override
648 public AbstractStringBuilder append(CharSequence s, int start, int end) {
649 if (s == null) {
650 s = "null";
651 }
652 checkRange(start, end, s.length());
653 int len = end - start;
654 ensureCapacityInternal(count + len);
655 appendChars(s, start, end);
656 return this;
657 }
658
659 /**
660 * Appends the string representation of the {@code char} array
661 * argument to this sequence.
662 * <p>
663 * The characters of the array argument are appended, in order, to
664 * the contents of this sequence. The length of this sequence
665 * increases by the length of the argument.
666 * <p>
667 * The overall effect is exactly as if the argument were converted
668 * to a string by the method {@link String#valueOf(char[])},
669 * and the characters of that string were then
670 * {@link #append(String) appended} to this character sequence.
671 *
672 * @param str the characters to be appended.
673 * @return a reference to this object.
674 */
675 public AbstractStringBuilder append(char[] str) {
676 int len = str.length;
677 ensureCapacityInternal(count + len);
678 appendChars(str, 0, len);
679 return this;
680 }
681
682 /**
683 * Appends the string representation of a subarray of the
684 * {@code char} array argument to this sequence.
685 * <p>
686 * Characters of the {@code char} array {@code str}, starting at
687 * index {@code offset}, are appended, in order, to the contents
688 * of this sequence. The length of this sequence increases
689 * by the value of {@code len}.
690 * <p>
691 * The overall effect is exactly as if the arguments were converted
692 * to a string by the method {@link String#valueOf(char[],int,int)},
693 * and the characters of that string were then
694 * {@link #append(String) appended} to this character sequence.
695 *
696 * @param str the characters to be appended.
697 * @param offset the index of the first {@code char} to append.
698 * @param len the number of {@code char}s to append.
699 * @return a reference to this object.
700 * @throws IndexOutOfBoundsException
701 * if {@code offset < 0} or {@code len < 0}
702 * or {@code offset+len > str.length}
703 */
704 public AbstractStringBuilder append(char str[], int offset, int len) {
705 int end = offset + len;
706 checkRange(offset, end, str.length);
707 ensureCapacityInternal(count + len);
708 appendChars(str, offset, end);
709 return this;
710 }
711
712 /**
713 * Appends the string representation of the {@code boolean}
714 * argument to the sequence.
715 * <p>
716 * The overall effect is exactly as if the argument were converted
717 * to a string by the method {@link String#valueOf(boolean)},
718 * and the characters of that string were then
719 * {@link #append(String) appended} to this character sequence.
720 *
721 * @param b a {@code boolean}.
722 * @return a reference to this object.
723 */
724 public AbstractStringBuilder append(boolean b) {
725 ensureCapacityInternal(count + (b ? 4 : 5));
726 int count = this.count;
727 byte[] val = this.value;
728 if (isLatin1()) {
729 if (b) {
730 val[count++] = 't';
731 val[count++] = 'r';
732 val[count++] = 'u';
733 val[count++] = 'e';
734 } else {
735 val[count++] = 'f';
736 val[count++] = 'a';
737 val[count++] = 'l';
738 val[count++] = 's';
739 val[count++] = 'e';
740 }
741 } else {
742 if (b) {
743 count = StringUTF16.putCharsAt(val, count, 't', 'r', 'u', 'e');
744 } else {
745 count = StringUTF16.putCharsAt(val, count, 'f', 'a', 'l', 's', 'e');
746 }
747 }
748 this.count = count;
749 return this;
750 }
751
752 /**
753 * Appends the string representation of the {@code char}
754 * argument to this sequence.
755 * <p>
756 * The argument is appended to the contents of this sequence.
757 * The length of this sequence increases by {@code 1}.
758 * <p>
759 * The overall effect is exactly as if the argument were converted
760 * to a string by the method {@link String#valueOf(char)},
761 * and the character in that string were then
762 * {@link #append(String) appended} to this character sequence.
763 *
764 * @param c a {@code char}.
765 * @return a reference to this object.
766 */
767 @Override
768 public AbstractStringBuilder append(char c) {
769 ensureCapacityInternal(count + 1);
770 if (isLatin1() && StringLatin1.canEncode(c)) {
771 value[count++] = (byte)c;
772 } else {
773 if (isLatin1()) {
774 inflate();
775 }
776 StringUTF16.putCharSB(value, count++, c);
777 }
778 return this;
779 }
780
781 /**
782 * Appends the string representation of the {@code int}
783 * argument to this sequence.
784 * <p>
785 * The overall effect is exactly as if the argument were converted
786 * to a string by the method {@link String#valueOf(int)},
787 * and the characters of that string were then
788 * {@link #append(String) appended} to this character sequence.
789 *
790 * @param i an {@code int}.
791 * @return a reference to this object.
792 */
793 public AbstractStringBuilder append(int i) {
794 int count = this.count;
795 int spaceNeeded = count + Integer.stringSize(i);
796 ensureCapacityInternal(spaceNeeded);
797 if (isLatin1()) {
798 Integer.getChars(i, spaceNeeded, value);
799 } else {
800 StringUTF16.getChars(i, count, spaceNeeded, value);
801 }
802 this.count = spaceNeeded;
803 return this;
804 }
805
806 /**
807 * Appends the string representation of the {@code long}
808 * argument to this sequence.
809 * <p>
810 * The overall effect is exactly as if the argument were converted
811 * to a string by the method {@link String#valueOf(long)},
812 * and the characters of that string were then
813 * {@link #append(String) appended} to this character sequence.
814 *
815 * @param l a {@code long}.
816 * @return a reference to this object.
817 */
818 public AbstractStringBuilder append(long l) {
819 int count = this.count;
820 int spaceNeeded = count + Long.stringSize(l);
821 ensureCapacityInternal(spaceNeeded);
822 if (isLatin1()) {
823 Long.getChars(l, spaceNeeded, value);
824 } else {
825 StringUTF16.getChars(l, count, spaceNeeded, value);
826 }
827 this.count = spaceNeeded;
828 return this;
829 }
830
831 /**
832 * Appends the string representation of the {@code float}
833 * argument to this sequence.
834 * <p>
835 * The overall effect is exactly as if the argument were converted
836 * to a string by the method {@link String#valueOf(float)},
837 * and the characters of that string were then
838 * {@link #append(String) appended} to this character sequence.
839 *
840 * @param f a {@code float}.
841 * @return a reference to this object.
842 */
843 public AbstractStringBuilder append(float f) {
844 FloatingDecimal.appendTo(f,this);
845 return this;
846 }
847
848 /**
849 * Appends the string representation of the {@code double}
850 * argument to this sequence.
851 * <p>
852 * The overall effect is exactly as if the argument were converted
853 * to a string by the method {@link String#valueOf(double)},
854 * and the characters of that string were then
855 * {@link #append(String) appended} to this character sequence.
856 *
857 * @param d a {@code double}.
858 * @return a reference to this object.
859 */
860 public AbstractStringBuilder append(double d) {
861 FloatingDecimal.appendTo(d,this);
862 return this;
863 }
864
865 /**
866 * Removes the characters in a substring of this sequence.
867 * The substring begins at the specified {@code start} and extends to
868 * the character at index {@code end - 1} or to the end of the
869 * sequence if no such character exists. If
870 * {@code start} is equal to {@code end}, no changes are made.
871 *
872 * @param start The beginning index, inclusive.
873 * @param end The ending index, exclusive.
874 * @return This object.
875 * @throws StringIndexOutOfBoundsException if {@code start}
876 * is negative, greater than {@code length()}, or
877 * greater than {@code end}.
878 */
879 public AbstractStringBuilder delete(int start, int end) {
880 int count = this.count;
881 if (end > count) {
882 end = count;
883 }
884 checkRangeSIOOBE(start, end, count);
885 int len = end - start;
886 if (len > 0) {
887 shift(end, -len);
888 this.count = count - len;
889 }
890 return this;
891 }
892
893 /**
894 * Appends the string representation of the {@code codePoint}
895 * argument to this sequence.
896 *
897 * <p> The argument is appended to the contents of this sequence.
898 * The length of this sequence increases by
899 * {@link Character#charCount(int) Character.charCount(codePoint)}.
900 *
901 * <p> The overall effect is exactly as if the argument were
902 * converted to a {@code char} array by the method
903 * {@link Character#toChars(int)} and the character in that array
904 * were then {@link #append(char[]) appended} to this character
905 * sequence.
906 *
907 * @param codePoint a Unicode code point
908 * @return a reference to this object.
909 * @throws IllegalArgumentException if the specified
910 * {@code codePoint} isn't a valid Unicode code point
911 */
912 public AbstractStringBuilder appendCodePoint(int codePoint) {
913 if (Character.isBmpCodePoint(codePoint)) {
914 return append((char)codePoint);
915 }
916 return append(Character.toChars(codePoint));
917 }
918
919 /**
920 * Removes the {@code char} at the specified position in this
921 * sequence. This sequence is shortened by one {@code char}.
922 *
923 * <p>Note: If the character at the given index is a supplementary
924 * character, this method does not remove the entire character. If
925 * correct handling of supplementary characters is required,
926 * determine the number of {@code char}s to remove by calling
927 * {@code Character.charCount(thisSequence.codePointAt(index))},
928 * where {@code thisSequence} is this sequence.
929 *
930 * @param index Index of {@code char} to remove
931 * @return This object.
932 * @throws StringIndexOutOfBoundsException if the {@code index}
933 * is negative or greater than or equal to
934 * {@code length()}.
935 */
936 public AbstractStringBuilder deleteCharAt(int index) {
937 checkIndex(index, count);
938 shift(index + 1, -1);
939 count--;
940 return this;
941 }
942
943 /**
944 * Replaces the characters in a substring of this sequence
945 * with characters in the specified {@code String}. The substring
946 * begins at the specified {@code start} and extends to the character
947 * at index {@code end - 1} or to the end of the
948 * sequence if no such character exists. First the
949 * characters in the substring are removed and then the specified
950 * {@code String} is inserted at {@code start}. (This
951 * sequence will be lengthened to accommodate the
952 * specified String if necessary.)
953 *
954 * @param start The beginning index, inclusive.
955 * @param end The ending index, exclusive.
956 * @param str String that will replace previous contents.
957 * @return This object.
958 * @throws StringIndexOutOfBoundsException if {@code start}
959 * is negative, greater than {@code length()}, or
960 * greater than {@code end}.
961 */
962 public AbstractStringBuilder replace(int start, int end, String str) {
963 int count = this.count;
964 if (end > count) {
965 end = count;
966 }
967 checkRangeSIOOBE(start, end, count);
968 int len = str.length();
969 int newCount = count + len - (end - start);
970 ensureCapacityInternal(newCount);
971 shift(end, newCount - count);
972 this.count = newCount;
973 putStringAt(start, str);
974 return this;
975 }
976
977 /**
978 * Returns a new {@code String} that contains a subsequence of
979 * characters currently contained in this character sequence. The
980 * substring begins at the specified index and extends to the end of
981 * this sequence.
982 *
983 * @param start The beginning index, inclusive.
984 * @return The new string.
985 * @throws StringIndexOutOfBoundsException if {@code start} is
986 * less than zero, or greater than the length of this object.
987 */
988 public String substring(int start) {
989 return substring(start, count);
990 }
991
992 /**
993 * Returns a new character sequence that is a subsequence of this sequence.
994 *
995 * <p> An invocation of this method of the form
996 *
997 * <pre>{@code
998 * sb.subSequence(begin, end)}</pre>
999 *
1000 * behaves in exactly the same way as the invocation
1001 *
1002 * <pre>{@code
1003 * sb.substring(begin, end)}</pre>
1004 *
1005 * This method is provided so that this class can
1006 * implement the {@link CharSequence} interface.
1007 *
1008 * @param start the start index, inclusive.
1009 * @param end the end index, exclusive.
1010 * @return the specified subsequence.
1011 *
1012 * @throws IndexOutOfBoundsException
1013 * if {@code start} or {@code end} are negative,
1014 * if {@code end} is greater than {@code length()},
1015 * or if {@code start} is greater than {@code end}
1016 * @spec JSR-51
1017 */
1018 @Override
1019 public CharSequence subSequence(int start, int end) {
1020 return substring(start, end);
1021 }
1022
1023 /**
1024 * Returns a new {@code String} that contains a subsequence of
1025 * characters currently contained in this sequence. The
1026 * substring begins at the specified {@code start} and
1027 * extends to the character at index {@code end - 1}.
1028 *
1029 * @param start The beginning index, inclusive.
1030 * @param end The ending index, exclusive.
1031 * @return The new string.
1032 * @throws StringIndexOutOfBoundsException if {@code start}
1033 * or {@code end} are negative or greater than
1034 * {@code length()}, or {@code start} is
1035 * greater than {@code end}.
1036 */
1037 public String substring(int start, int end) {
1038 checkRangeSIOOBE(start, end, count);
1039 if (isLatin1()) {
1040 return StringLatin1.newString(value, start, end - start);
1041 }
1042 return StringUTF16.newString(value, start, end - start);
1043 }
1044
1045 private void shift(int offset, int n) {
1046 System.arraycopy(value, offset << coder,
1047 value, (offset + n) << coder, (count - offset) << coder);
1048 }
1049
1050 /**
1051 * Inserts the string representation of a subarray of the {@code str}
1052 * array argument into this sequence. The subarray begins at the
1053 * specified {@code offset} and extends {@code len} {@code char}s.
1054 * The characters of the subarray are inserted into this sequence at
1055 * the position indicated by {@code index}. The length of this
1056 * sequence increases by {@code len} {@code char}s.
1057 *
1058 * @param index position at which to insert subarray.
1059 * @param str A {@code char} array.
1060 * @param offset the index of the first {@code char} in subarray to
1061 * be inserted.
1062 * @param len the number of {@code char}s in the subarray to
1063 * be inserted.
1064 * @return This object
1065 * @throws StringIndexOutOfBoundsException if {@code index}
1066 * is negative or greater than {@code length()}, or
1067 * {@code offset} or {@code len} are negative, or
1068 * {@code (offset+len)} is greater than
1069 * {@code str.length}.
1070 */
1071 public AbstractStringBuilder insert(int index, char[] str, int offset,
1072 int len)
1073 {
1074 checkOffset(index, count);
1075 checkRangeSIOOBE(offset, offset + len, str.length);
1076 ensureCapacityInternal(count + len);
1077 shift(index, len);
1078 count += len;
1079 putCharsAt(index, str, offset, offset + len);
1080 return this;
1081 }
1082
1083 /**
1084 * Inserts the string representation of the {@code Object}
1085 * argument into this character sequence.
1086 * <p>
1087 * The overall effect is exactly as if the second argument were
1088 * converted to a string by the method {@link String#valueOf(Object)},
1089 * and the characters of that string were then
1090 * {@link #insert(int,String) inserted} into this character
1091 * sequence at the indicated offset.
1092 * <p>
1093 * The {@code offset} argument must be greater than or equal to
1094 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1095 * of this sequence.
1096 *
1097 * @param offset the offset.
1098 * @param obj an {@code Object}.
1099 * @return a reference to this object.
1100 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1101 */
1102 public AbstractStringBuilder insert(int offset, Object obj) {
1103 return insert(offset, String.valueOf(obj));
1104 }
1105
1106 /**
1107 * Inserts the string into this character sequence.
1108 * <p>
1109 * The characters of the {@code String} argument are inserted, in
1110 * order, into this sequence at the indicated offset, moving up any
1111 * characters originally above that position and increasing the length
1112 * of this sequence by the length of the argument. If
1113 * {@code str} is {@code null}, then the four characters
1114 * {@code "null"} are inserted into this sequence.
1115 * <p>
1116 * The character at index <i>k</i> in the new character sequence is
1117 * equal to:
1118 * <ul>
1119 * <li>the character at index <i>k</i> in the old character sequence, if
1120 * <i>k</i> is less than {@code offset}
1121 * <li>the character at index <i>k</i>{@code -offset} in the
1122 * argument {@code str}, if <i>k</i> is not less than
1123 * {@code offset} but is less than {@code offset+str.length()}
1124 * <li>the character at index <i>k</i>{@code -str.length()} in the
1125 * old character sequence, if <i>k</i> is not less than
1126 * {@code offset+str.length()}
1127 * </ul><p>
1128 * The {@code offset} argument must be greater than or equal to
1129 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1130 * of this sequence.
1131 *
1132 * @param offset the offset.
1133 * @param str a string.
1134 * @return a reference to this object.
1135 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1136 */
1137 public AbstractStringBuilder insert(int offset, String str) {
1138 checkOffset(offset, count);
1139 if (str == null) {
1140 str = "null";
1141 }
1142 int len = str.length();
1143 ensureCapacityInternal(count + len);
1144 shift(offset, len);
1145 count += len;
1146 putStringAt(offset, str);
1147 return this;
1148 }
1149
1150 /**
1151 * Inserts the string representation of the {@code char} array
1152 * argument into this sequence.
1153 * <p>
1154 * The characters of the array argument are inserted into the
1155 * contents of this sequence at the position indicated by
1156 * {@code offset}. The length of this sequence increases by
1157 * the length of the argument.
1158 * <p>
1159 * The overall effect is exactly as if the second argument were
1160 * converted to a string by the method {@link String#valueOf(char[])},
1161 * and the characters of that string were then
1162 * {@link #insert(int,String) inserted} into this character
1163 * sequence at the indicated offset.
1164 * <p>
1165 * The {@code offset} argument must be greater than or equal to
1166 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1167 * of this sequence.
1168 *
1169 * @param offset the offset.
1170 * @param str a character array.
1171 * @return a reference to this object.
1172 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1173 */
1174 public AbstractStringBuilder insert(int offset, char[] str) {
1175 checkOffset(offset, count);
1176 int len = str.length;
1177 ensureCapacityInternal(count + len);
1178 shift(offset, len);
1179 count += len;
1180 putCharsAt(offset, str, 0, len);
1181 return this;
1182 }
1183
1184 /**
1185 * Inserts the specified {@code CharSequence} into this sequence.
1186 * <p>
1187 * The characters of the {@code CharSequence} argument are inserted,
1188 * in order, into this sequence at the indicated offset, moving up
1189 * any characters originally above that position and increasing the length
1190 * of this sequence by the length of the argument s.
1191 * <p>
1192 * The result of this method is exactly the same as if it were an
1193 * invocation of this object's
1194 * {@link #insert(int,CharSequence,int,int) insert}(dstOffset, s, 0, s.length())
1195 * method.
1196 *
1197 * <p>If {@code s} is {@code null}, then the four characters
1198 * {@code "null"} are inserted into this sequence.
1199 *
1200 * @param dstOffset the offset.
1201 * @param s the sequence to be inserted
1202 * @return a reference to this object.
1203 * @throws IndexOutOfBoundsException if the offset is invalid.
1204 */
1205 public AbstractStringBuilder insert(int dstOffset, CharSequence s) {
1206 if (s == null) {
1207 s = "null";
1208 }
1209 if (s instanceof String) {
1210 return this.insert(dstOffset, (String)s);
1211 }
1212 return this.insert(dstOffset, s, 0, s.length());
1213 }
1214
1215 /**
1216 * Inserts a subsequence of the specified {@code CharSequence} into
1217 * this sequence.
1218 * <p>
1219 * The subsequence of the argument {@code s} specified by
1220 * {@code start} and {@code end} are inserted,
1221 * in order, into this sequence at the specified destination offset, moving
1222 * up any characters originally above that position. The length of this
1223 * sequence is increased by {@code end - start}.
1224 * <p>
1225 * The character at index <i>k</i> in this sequence becomes equal to:
1226 * <ul>
1227 * <li>the character at index <i>k</i> in this sequence, if
1228 * <i>k</i> is less than {@code dstOffset}
1229 * <li>the character at index <i>k</i>{@code +start-dstOffset} in
1230 * the argument {@code s}, if <i>k</i> is greater than or equal to
1231 * {@code dstOffset} but is less than {@code dstOffset+end-start}
1232 * <li>the character at index <i>k</i>{@code -(end-start)} in this
1233 * sequence, if <i>k</i> is greater than or equal to
1234 * {@code dstOffset+end-start}
1235 * </ul><p>
1236 * The {@code dstOffset} argument must be greater than or equal to
1237 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1238 * of this sequence.
1239 * <p>The start argument must be nonnegative, and not greater than
1240 * {@code end}.
1241 * <p>The end argument must be greater than or equal to
1242 * {@code start}, and less than or equal to the length of s.
1243 *
1244 * <p>If {@code s} is {@code null}, then this method inserts
1245 * characters as if the s parameter was a sequence containing the four
1246 * characters {@code "null"}.
1247 *
1248 * @param dstOffset the offset in this sequence.
1249 * @param s the sequence to be inserted.
1250 * @param start the starting index of the subsequence to be inserted.
1251 * @param end the end index of the subsequence to be inserted.
1252 * @return a reference to this object.
1253 * @throws IndexOutOfBoundsException if {@code dstOffset}
1254 * is negative or greater than {@code this.length()}, or
1255 * {@code start} or {@code end} are negative, or
1256 * {@code start} is greater than {@code end} or
1257 * {@code end} is greater than {@code s.length()}
1258 */
1259 public AbstractStringBuilder insert(int dstOffset, CharSequence s,
1260 int start, int end)
1261 {
1262 if (s == null) {
1263 s = "null";
1264 }
1265 checkOffset(dstOffset, count);
1266 checkRange(start, end, s.length());
1267 int len = end - start;
1268 ensureCapacityInternal(count + len);
1269 shift(dstOffset, len);
1270 count += len;
1271 putCharsAt(dstOffset, s, start, end);
1272 return this;
1273 }
1274
1275 /**
1276 * Inserts the string representation of the {@code boolean}
1277 * argument into this sequence.
1278 * <p>
1279 * The overall effect is exactly as if the second argument were
1280 * converted to a string by the method {@link String#valueOf(boolean)},
1281 * and the characters of that string were then
1282 * {@link #insert(int,String) inserted} into this character
1283 * sequence at the indicated offset.
1284 * <p>
1285 * The {@code offset} argument must be greater than or equal to
1286 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1287 * of this sequence.
1288 *
1289 * @param offset the offset.
1290 * @param b a {@code boolean}.
1291 * @return a reference to this object.
1292 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1293 */
1294 public AbstractStringBuilder insert(int offset, boolean b) {
1295 return insert(offset, String.valueOf(b));
1296 }
1297
1298 /**
1299 * Inserts the string representation of the {@code char}
1300 * argument into this sequence.
1301 * <p>
1302 * The overall effect is exactly as if the second argument were
1303 * converted to a string by the method {@link String#valueOf(char)},
1304 * and the character in that string were then
1305 * {@link #insert(int,String) inserted} into this character
1306 * sequence at the indicated offset.
1307 * <p>
1308 * The {@code offset} argument must be greater than or equal to
1309 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1310 * of this sequence.
1311 *
1312 * @param offset the offset.
1313 * @param c a {@code char}.
1314 * @return a reference to this object.
1315 * @throws IndexOutOfBoundsException if the offset is invalid.
1316 */
1317 public AbstractStringBuilder insert(int offset, char c) {
1318 checkOffset(offset, count);
1319 ensureCapacityInternal(count + 1);
1320 shift(offset, 1);
1321 count += 1;
1322 if (isLatin1() && StringLatin1.canEncode(c)) {
1323 value[offset] = (byte)c;
1324 } else {
1325 if (isLatin1()) {
1326 inflate();
1327 }
1328 StringUTF16.putCharSB(value, offset, c);
1329 }
1330 return this;
1331 }
1332
1333 /**
1334 * Inserts the string representation of the second {@code int}
1335 * argument into this sequence.
1336 * <p>
1337 * The overall effect is exactly as if the second argument were
1338 * converted to a string by the method {@link String#valueOf(int)},
1339 * and the characters of that string were then
1340 * {@link #insert(int,String) inserted} into this character
1341 * sequence at the indicated offset.
1342 * <p>
1343 * The {@code offset} argument must be greater than or equal to
1344 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1345 * of this sequence.
1346 *
1347 * @param offset the offset.
1348 * @param i an {@code int}.
1349 * @return a reference to this object.
1350 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1351 */
1352 public AbstractStringBuilder insert(int offset, int i) {
1353 return insert(offset, String.valueOf(i));
1354 }
1355
1356 /**
1357 * Inserts the string representation of the {@code long}
1358 * argument into this sequence.
1359 * <p>
1360 * The overall effect is exactly as if the second argument were
1361 * converted to a string by the method {@link String#valueOf(long)},
1362 * and the characters of that string were then
1363 * {@link #insert(int,String) inserted} into this character
1364 * sequence at the indicated offset.
1365 * <p>
1366 * The {@code offset} argument must be greater than or equal to
1367 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1368 * of this sequence.
1369 *
1370 * @param offset the offset.
1371 * @param l a {@code long}.
1372 * @return a reference to this object.
1373 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1374 */
1375 public AbstractStringBuilder insert(int offset, long l) {
1376 return insert(offset, String.valueOf(l));
1377 }
1378
1379 /**
1380 * Inserts the string representation of the {@code float}
1381 * argument into this sequence.
1382 * <p>
1383 * The overall effect is exactly as if the second argument were
1384 * converted to a string by the method {@link String#valueOf(float)},
1385 * and the characters of that string were then
1386 * {@link #insert(int,String) inserted} into this character
1387 * sequence at the indicated offset.
1388 * <p>
1389 * The {@code offset} argument must be greater than or equal to
1390 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1391 * of this sequence.
1392 *
1393 * @param offset the offset.
1394 * @param f a {@code float}.
1395 * @return a reference to this object.
1396 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1397 */
1398 public AbstractStringBuilder insert(int offset, float f) {
1399 return insert(offset, String.valueOf(f));
1400 }
1401
1402 /**
1403 * Inserts the string representation of the {@code double}
1404 * argument into this sequence.
1405 * <p>
1406 * The overall effect is exactly as if the second argument were
1407 * converted to a string by the method {@link String#valueOf(double)},
1408 * and the characters of that string were then
1409 * {@link #insert(int,String) inserted} into this character
1410 * sequence at the indicated offset.
1411 * <p>
1412 * The {@code offset} argument must be greater than or equal to
1413 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1414 * of this sequence.
1415 *
1416 * @param offset the offset.
1417 * @param d a {@code double}.
1418 * @return a reference to this object.
1419 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1420 */
1421 public AbstractStringBuilder insert(int offset, double d) {
1422 return insert(offset, String.valueOf(d));
1423 }
1424
1425 /**
1426 * Returns the index within this string of the first occurrence of the
1427 * specified substring.
1428 *
1429 * <p>The returned index is the smallest value {@code k} for which:
1430 * <pre>{@code
1431 * this.toString().startsWith(str, k)
1432 * }</pre>
1433 * If no such value of {@code k} exists, then {@code -1} is returned.
1434 *
1435 * @param str the substring to search for.
1436 * @return the index of the first occurrence of the specified substring,
1437 * or {@code -1} if there is no such occurrence.
1438 */
1439 public int indexOf(String str) {
1440 return indexOf(str, 0);
1441 }
1442
1443 /**
1444 * Returns the index within this string of the first occurrence of the
1445 * specified substring, starting at the specified index.
1446 *
1447 * <p>The returned index is the smallest value {@code k} for which:
1448 * <pre>{@code
1449 * k >= Math.min(fromIndex, this.length()) &&
1450 * this.toString().startsWith(str, k)
1451 * }</pre>
1452 * If no such value of {@code k} exists, then {@code -1} is returned.
1453 *
1454 * @param str the substring to search for.
1455 * @param fromIndex the index from which to start the search.
1456 * @return the index of the first occurrence of the specified substring,
1457 * starting at the specified index,
1458 * or {@code -1} if there is no such occurrence.
1459 */
1460 public int indexOf(String str, int fromIndex) {
1461 return String.indexOf(value, coder, count, str, fromIndex);
1462 }
1463
1464 /**
1465 * Returns the index within this string of the last occurrence of the
1466 * specified substring. The last occurrence of the empty string "" is
1467 * considered to occur at the index value {@code this.length()}.
1468 *
1469 * <p>The returned index is the largest value {@code k} for which:
1470 * <pre>{@code
1471 * this.toString().startsWith(str, k)
1472 * }</pre>
1473 * If no such value of {@code k} exists, then {@code -1} is returned.
1474 *
1475 * @param str the substring to search for.
1476 * @return the index of the last occurrence of the specified substring,
1477 * or {@code -1} if there is no such occurrence.
1478 */
1479 public int lastIndexOf(String str) {
1480 return lastIndexOf(str, count);
1481 }
1482
1483 /**
1484 * Returns the index within this string of the last occurrence of the
1485 * specified substring, searching backward starting at the specified index.
1486 *
1487 * <p>The returned index is the largest value {@code k} for which:
1488 * <pre>{@code
1489 * k <= Math.min(fromIndex, this.length()) &&
1490 * this.toString().startsWith(str, k)
1491 * }</pre>
1492 * If no such value of {@code k} exists, then {@code -1} is returned.
1493 *
1494 * @param str the substring to search for.
1495 * @param fromIndex the index to start the search from.
1496 * @return the index of the last occurrence of the specified substring,
1497 * searching backward from the specified index,
1498 * or {@code -1} if there is no such occurrence.
1499 */
1500 public int lastIndexOf(String str, int fromIndex) {
1501 return String.lastIndexOf(value, coder, count, str, fromIndex);
1502 }
1503
1504 /**
1505 * Causes this character sequence to be replaced by the reverse of
1506 * the sequence. If there are any surrogate pairs included in the
1507 * sequence, these are treated as single characters for the
1508 * reverse operation. Thus, the order of the high-low surrogates
1509 * is never reversed.
1510 *
1511 * Let <i>n</i> be the character length of this character sequence
1512 * (not the length in {@code char} values) just prior to
1513 * execution of the {@code reverse} method. Then the
1514 * character at index <i>k</i> in the new character sequence is
1515 * equal to the character at index <i>n-k-1</i> in the old
1516 * character sequence.
1517 *
1518 * <p>Note that the reverse operation may result in producing
1519 * surrogate pairs that were unpaired low-surrogates and
1520 * high-surrogates before the operation. For example, reversing
1521 * "\u005CuDC00\u005CuD800" produces "\u005CuD800\u005CuDC00" which is
1522 * a valid surrogate pair.
1523 *
1524 * @return a reference to this object.
1525 */
1526 public AbstractStringBuilder reverse() {
1527 byte[] val = this.value;
1528 int count = this.count;
1529 int coder = this.coder;
1530 int n = count - 1;
1531 if (COMPACT_STRINGS && coder == LATIN1) {
1532 for (int j = (n-1) >> 1; j >= 0; j--) {
1533 int k = n - j;
1534 byte cj = val[j];
1535 val[j] = val[k];
1536 val[k] = cj;
1537 }
1538 } else {
1539 StringUTF16.reverse(val, count);
1540 }
1541 return this;
1542 }
1543
1544 /**
1545 * Returns a string representing the data in this sequence.
1546 * A new {@code String} object is allocated and initialized to
1547 * contain the character sequence currently represented by this
1548 * object. This {@code String} is then returned. Subsequent
1549 * changes to this sequence do not affect the contents of the
1550 * {@code String}.
1551 *
1552 * @return a string representation of this sequence of characters.
1553 */
1554 @Override
1555 public abstract String toString();
1556
1557 /**
1558 * {@inheritDoc}
1559 * @since 9
1560 */
1561 @Override
1562 public IntStream chars() {
1563 // Reuse String-based spliterator. This requires a supplier to
1564 // capture the value and count when the terminal operation is executed
1565 return StreamSupport.intStream(
1566 () -> {
1567 // The combined set of field reads are not atomic and thread
1568 // safe but bounds checks will ensure no unsafe reads from
1569 // the byte array
1570 byte[] val = this.value;
1571 int count = this.count;
1572 byte coder = this.coder;
1573 return coder == LATIN1
1574 ? new StringLatin1.CharsSpliterator(val, 0, count, 0)
1575 : new StringUTF16.CharsSpliterator(val, 0, count, 0);
1576 },
1577 Spliterator.ORDERED | Spliterator.SIZED | Spliterator.SUBSIZED,
1578 false);
1579 }
1580
1581 /**
1582 * {@inheritDoc}
1583 * @since 9
1584 */
1585 @Override
1586 public IntStream codePoints() {
1587 // Reuse String-based spliterator. This requires a supplier to
1588 // capture the value and count when the terminal operation is executed
1589 return StreamSupport.intStream(
1590 () -> {
1591 // The combined set of field reads are not atomic and thread
1592 // safe but bounds checks will ensure no unsafe reads from
1593 // the byte array
1594 byte[] val = this.value;
1595 int count = this.count;
1596 byte coder = this.coder;
1597 return coder == LATIN1
1598 ? new StringLatin1.CharsSpliterator(val, 0, count, 0)
1599 : new StringUTF16.CodePointsSpliterator(val, 0, count, 0);
1600 },
1601 Spliterator.ORDERED,
1602 false);
1603 }
1604
1605 /**
1606 * Needed by {@code String} for the contentEquals method.
1607 */
1608 final byte[] getValue() {
1609 return value;
1610 }
1611
1612 /*
1613 * Invoker guarantees it is in UTF16 (inflate itself for asb), if two
1614 * coders are different and the dstBegin has enough space
1615 *
1616 * @param dstBegin the char index, not offset of byte[]
1617 * @param coder the coder of dst[]
1618 */
1619 void getBytes(byte dst[], int dstBegin, byte coder) {
1620 if (this.coder == coder) {
1621 System.arraycopy(value, 0, dst, dstBegin << coder, count << coder);
1622 } else { // this.coder == LATIN && coder == UTF16
1623 StringLatin1.inflate(value, 0, dst, dstBegin, count);
1624 }
1625 }
1626
1627 /* for readObject() */
1628 void initBytes(char[] value, int off, int len) {
1629 if (String.COMPACT_STRINGS) {
1630 this.value = StringUTF16.compress(value, off, len);
1631 if (this.value != null) {
1632 this.coder = LATIN1;
1633 return;
1634 }
1635 }
1636 this.coder = UTF16;
1637 this.value = StringUTF16.toBytes(value, off, len);
1638 }
1639
1640 final byte getCoder() {
1641 return COMPACT_STRINGS ? coder : UTF16;
1642 }
1643
1644 final boolean isLatin1() {
1645 return COMPACT_STRINGS && coder == LATIN1;
1646 }
1647
1648 private final void putCharsAt(int index, char[] s, int off, int end) {
1649 if (isLatin1()) {
1650 byte[] val = this.value;
1651 for (int i = off, j = index; i < end; i++) {
1652 char c = s[i];
1653 if (StringLatin1.canEncode(c)) {
1654 val[j++] = (byte)c;
1655 } else {
1656 inflate();
1657 StringUTF16.putCharsSB(this.value, j, s, i, end);
1658 return;
1659 }
1660 }
1661 } else {
1662 StringUTF16.putCharsSB(this.value, index, s, off, end);
1663 }
1664 }
1665
1666 private final void putCharsAt(int index, CharSequence s, int off, int end) {
1667 if (isLatin1()) {
1668 byte[] val = this.value;
1669 for (int i = off, j = index; i < end; i++) {
1670 char c = s.charAt(i);
1671 if (StringLatin1.canEncode(c)) {
1672 val[j++] = (byte)c;
1673 } else {
1674 inflate();
1675 StringUTF16.putCharsSB(this.value, j, s, i, end);
1676 return;
1677 }
1678 }
1679 } else {
1680 StringUTF16.putCharsSB(this.value, index, s, off, end);
1681 }
1682 }
1683
1684 private final void putStringAt(int index, String str) {
1685 if (getCoder() != str.coder()) {
1686 inflate();
1687 }
1688 str.getBytes(value, index, coder);
1689 }
1690
1691 private final void appendChars(char[] s, int off, int end) {
1692 int count = this.count;
1693 if (isLatin1()) {
1694 byte[] val = this.value;
1695 for (int i = off, j = count; i < end; i++) {
1696 char c = s[i];
1697 if (StringLatin1.canEncode(c)) {
1698 val[j++] = (byte)c;
1699 } else {
1700 this.count = count = j;
1701 inflate();
1702 StringUTF16.putCharsSB(this.value, j, s, i, end);
1703 this.count = count + end - i;
1704 return;
1705 }
1706 }
1707 } else {
1708 StringUTF16.putCharsSB(this.value, count, s, off, end);
1709 }
1710 this.count = count + end - off;
1711 }
1712
1713 private final void appendChars(CharSequence s, int off, int end) {
1714 if (isLatin1()) {
1715 byte[] val = this.value;
1716 for (int i = off, j = count; i < end; i++) {
1717 char c = s.charAt(i);
1718 if (StringLatin1.canEncode(c)) {
1719 val[j++] = (byte)c;
1720 } else {
1721 count = j;
1722 inflate();
1723 StringUTF16.putCharsSB(this.value, j, s, i, end);
1724 count += end - i;
1725 return;
1726 }
1727 }
1728 } else {
1729 StringUTF16.putCharsSB(this.value, count, s, off, end);
1730 }
1731 count += end - off;
1732 }
1733
1734 /* IndexOutOfBoundsException, if out of bounds */
1735 private static void checkRange(int start, int end, int len) {
1736 if (start < 0 || start > end || end > len) {
1737 throw new IndexOutOfBoundsException(
1738 "start " + start + ", end " + end + ", length " + len);
1739 }
1740 }
1741
1742 /* StringIndexOutOfBoundsException, if out of bounds */
1743 private static void checkRangeSIOOBE(int start, int end, int len) {
1744 if (start < 0 || start > end || end > len) {
1745 throw new StringIndexOutOfBoundsException(
1746 "start " + start + ", end " + end + ", length " + len);
1747 }
1748 }
1749
1750 /**
1751 * Determines the "coder" of the given CharSequence.
1752 * If the coder cannot be determined, returns LATIN1.
1753 */
1754 static byte getCharSequenceCoderHint(CharSequence seq) {
1755 if (seq instanceof String) {
1756 return ((String)seq).coder();
1757 } else if (seq instanceof AbstractStringBuilder) {
1758 return ((AbstractStringBuilder)seq).getCoder();
1759 } else {
1760 return LATIN1;
1761 }
1762 }
1763 }