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