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