rev 6546 : 7197183: Alternate implementation of String.subSequence which uses shared backing array.
Reviewed-by: duke
1 /*
2 * Copyright (c) 2003, 2012, 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 sun.misc.FloatingDecimal;
29 import java.util.Arrays;
30
31 /**
32 * A mutable sequence of characters.
33 * <p>
34 * Implements a modifiable string. At any point in time it contains some
35 * particular sequence of characters, but the length and content of the
36 * sequence can be changed through certain method calls.
37 *
38 * <p>Unless otherwise noted, passing a {@code null} argument to a constructor
39 * or method in this class will cause a {@link NullPointerException} to be
40 * thrown.
41 *
42 * @author Michael McCloskey
43 * @author Martin Buchholz
44 * @author Ulf Zibis
45 * @since 1.5
46 */
47 abstract class AbstractStringBuilder implements Appendable, CharSequence {
48 /**
49 * The value is used for character storage.
50 */
51 char[] value;
52
53 /**
54 * The count is the number of characters used.
55 */
56 int count;
57
58 /**
59 * This no-arg constructor is necessary for serialization of subclasses.
60 */
61 AbstractStringBuilder() {
62 }
63
64 /**
65 * Creates an AbstractStringBuilder of the specified capacity.
66 */
67 AbstractStringBuilder(int capacity) {
68 value = new char[capacity];
69 }
70
71 /**
72 * Returns the length (character count).
73 *
74 * @return the length of the sequence of characters currently
75 * represented by this object
76 */
77 @Override
78 public int length() {
79 return count;
80 }
81
82 /**
83 * Returns the current capacity. The capacity is the amount of storage
84 * available for newly inserted characters, beyond which an allocation
85 * will occur.
86 *
87 * @return the current capacity
88 */
89 public int capacity() {
90 return value.length;
91 }
92
93 /**
94 * Ensures that the capacity is at least equal to the specified minimum.
95 * If the current capacity is less than the argument, then a new internal
96 * array is allocated with greater capacity. The new capacity is the
97 * larger of:
98 * <ul>
99 * <li>The {@code minimumCapacity} argument.
100 * <li>Twice the old capacity, plus {@code 2}.
101 * </ul>
102 * If the {@code minimumCapacity} argument is nonpositive, this
103 * method takes no action and simply returns.
104 * Note that subsequent operations on this object can reduce the
105 * actual capacity below that requested here.
106 *
107 * @param minimumCapacity the minimum desired capacity.
108 */
109 public void ensureCapacity(int minimumCapacity) {
110 if (minimumCapacity > 0)
111 ensureCapacityInternal(minimumCapacity);
112 }
113
114 /**
115 * This method has the same contract as ensureCapacity, but is
116 * never synchronized.
117 */
118 private void ensureCapacityInternal(int minimumCapacity) {
119 // overflow-conscious code
120 if (minimumCapacity - value.length > 0)
121 expandCapacity(minimumCapacity);
122 }
123
124 /**
125 * This implements the expansion semantics of ensureCapacity with no
126 * size check or synchronization.
127 */
128 void expandCapacity(int minimumCapacity) {
129 int newCapacity = value.length * 2 + 2;
130 if (newCapacity - minimumCapacity < 0)
131 newCapacity = minimumCapacity;
132 if (newCapacity < 0) {
133 if (minimumCapacity < 0) // overflow
134 throw new OutOfMemoryError();
135 newCapacity = Integer.MAX_VALUE;
136 }
137 value = Arrays.copyOf(value, newCapacity);
138 }
139
140 /**
141 * Attempts to reduce storage used for the character sequence.
142 * If the buffer is larger than necessary to hold its current sequence of
143 * characters, then it may be resized to become more space efficient.
144 * Calling this method may, but is not required to, affect the value
145 * returned by a subsequent call to the {@link #capacity()} method.
146 */
147 public void trimToSize() {
148 if (count < value.length) {
149 value = Arrays.copyOf(value, count);
150 }
151 }
152
153 /**
154 * Sets the length of the character sequence.
155 * The sequence is changed to a new character sequence
156 * whose length is specified by the argument. For every nonnegative
157 * index <i>k</i> less than {@code newLength}, the character at
158 * index <i>k</i> in the new character sequence is the same as the
159 * character at index <i>k</i> in the old sequence if <i>k</i> is less
160 * than the length of the old character sequence; otherwise, it is the
161 * null character {@code '\u005Cu0000'}.
162 *
163 * In other words, if the {@code newLength} argument is less than
164 * the current length, the length is changed to the specified length.
165 * <p>
166 * If the {@code newLength} argument is greater than or equal
167 * to the current length, sufficient null characters
168 * ({@code '\u005Cu0000'}) are appended so that
169 * length becomes the {@code newLength} argument.
170 * <p>
171 * The {@code newLength} argument must be greater than or equal
172 * to {@code 0}.
173 *
174 * @param newLength the new length
175 * @throws IndexOutOfBoundsException if the
176 * {@code newLength} argument is negative.
177 */
178 public void setLength(int newLength) {
179 if (newLength < 0)
180 throw new StringIndexOutOfBoundsException(newLength);
181 ensureCapacityInternal(newLength);
182
183 if (count < newLength) {
184 Arrays.fill(value, count, newLength, '\0');
185 }
186
187 count = newLength;
188 }
189
190 /**
191 * Returns the {@code char} value in this sequence at the specified index.
192 * The first {@code char} value is at index {@code 0}, the next at index
193 * {@code 1}, and so on, as in array indexing.
194 * <p>
195 * The index argument must be greater than or equal to
196 * {@code 0}, and less than the length of this sequence.
197 *
198 * <p>If the {@code char} value specified by the index is a
199 * <a href="Character.html#unicode">surrogate</a>, the surrogate
200 * value is returned.
201 *
202 * @param index the index of the desired {@code char} value.
203 * @return the {@code char} value at the specified index.
204 * @throws IndexOutOfBoundsException if {@code index} is
205 * negative or greater than or equal to {@code length()}.
206 */
207 @Override
208 public char charAt(int index) {
209 if ((index < 0) || (index >= count))
210 throw new StringIndexOutOfBoundsException(index);
211 return value[index];
212 }
213
214 /**
215 * Returns the character (Unicode code point) at the specified
216 * index. The index refers to {@code char} values
217 * (Unicode code units) and ranges from {@code 0} to
218 * {@link #length()}{@code - 1}.
219 *
220 * <p> If the {@code char} value specified at the given index
221 * is in the high-surrogate range, the following index is less
222 * than the length of this sequence, and the
223 * {@code char} value at the following index is in the
224 * low-surrogate range, then the supplementary code point
225 * corresponding to this surrogate pair is returned. Otherwise,
226 * the {@code char} value at the given index is returned.
227 *
228 * @param index the index to the {@code char} values
229 * @return the code point value of the character at the
230 * {@code index}
231 * @exception IndexOutOfBoundsException if the {@code index}
232 * argument is negative or not less than the length of this
233 * sequence.
234 */
235 public int codePointAt(int index) {
236 if ((index < 0) || (index >= count)) {
237 throw new StringIndexOutOfBoundsException(index);
238 }
239 return Character.codePointAt(value, index);
240 }
241
242 /**
243 * Returns the character (Unicode code point) before the specified
244 * index. The index refers to {@code char} values
245 * (Unicode code units) and ranges from {@code 1} to {@link
246 * #length()}.
247 *
248 * <p> If the {@code char} value at {@code (index - 1)}
249 * is in the low-surrogate range, {@code (index - 2)} is not
250 * negative, and the {@code char} value at {@code (index -
251 * 2)} is in the high-surrogate range, then the
252 * supplementary code point value of the surrogate pair is
253 * returned. If the {@code char} value at {@code index -
254 * 1} is an unpaired low-surrogate or a high-surrogate, the
255 * surrogate value is returned.
256 *
257 * @param index the index following the code point that should be returned
258 * @return the Unicode code point value before the given index.
259 * @exception IndexOutOfBoundsException if the {@code index}
260 * argument is less than 1 or greater than the length
261 * of this sequence.
262 */
263 public int codePointBefore(int index) {
264 int i = index - 1;
265 if ((i < 0) || (i >= count)) {
266 throw new StringIndexOutOfBoundsException(index);
267 }
268 return Character.codePointBefore(value, index);
269 }
270
271 /**
272 * Returns the number of Unicode code points in the specified text
273 * range of this sequence. The text range begins at the specified
274 * {@code beginIndex} and extends to the {@code char} at
275 * index {@code endIndex - 1}. Thus the length (in
276 * {@code char}s) of the text range is
277 * {@code endIndex-beginIndex}. Unpaired surrogates within
278 * this sequence count as one code point each.
279 *
280 * @param beginIndex the index to the first {@code char} of
281 * the text range.
282 * @param endIndex the index after the last {@code char} of
283 * the text range.
284 * @return the number of Unicode code points in the specified text
285 * range
286 * @exception IndexOutOfBoundsException if the
287 * {@code beginIndex} is negative, or {@code endIndex}
288 * is larger than the length of this sequence, or
289 * {@code beginIndex} is larger than {@code endIndex}.
290 */
291 public int codePointCount(int beginIndex, int endIndex) {
292 if (beginIndex < 0 || endIndex > count || beginIndex > endIndex) {
293 throw new IndexOutOfBoundsException();
294 }
295 return Character.codePointCountImpl(value, beginIndex, endIndex-beginIndex);
296 }
297
298 /**
299 * Returns the index within this sequence that is offset from the
300 * given {@code index} by {@code codePointOffset} code
301 * points. Unpaired surrogates within the text range given by
302 * {@code index} and {@code codePointOffset} count as
303 * one code point each.
304 *
305 * @param index the index to be offset
306 * @param codePointOffset the offset in code points
307 * @return the index within this sequence
308 * @exception IndexOutOfBoundsException if {@code index}
309 * is negative or larger then the length of this sequence,
310 * or if {@code codePointOffset} is positive and the subsequence
311 * starting with {@code index} has fewer than
312 * {@code codePointOffset} code points,
313 * or if {@code codePointOffset} is negative and the subsequence
314 * before {@code index} has fewer than the absolute value of
315 * {@code codePointOffset} code points.
316 */
317 public int offsetByCodePoints(int index, int codePointOffset) {
318 if (index < 0 || index > count) {
319 throw new IndexOutOfBoundsException();
320 }
321 return Character.offsetByCodePointsImpl(value, 0, count,
322 index, codePointOffset);
323 }
324
325 /**
326 * Characters are copied from this sequence into the
327 * destination character array {@code dst}. The first character to
328 * be copied is at index {@code srcBegin}; the last character to
329 * be copied is at index {@code srcEnd-1}. The total number of
330 * characters to be copied is {@code srcEnd-srcBegin}. The
331 * characters are copied into the subarray of {@code dst} starting
332 * at index {@code dstBegin} and ending at index:
333 * <p><blockquote><pre>
334 * dstbegin + (srcEnd-srcBegin) - 1
335 * </pre></blockquote>
336 *
337 * @param srcBegin start copying at this offset.
338 * @param srcEnd stop copying at this offset.
339 * @param dst the array to copy the data into.
340 * @param dstBegin offset into {@code dst}.
341 * @throws IndexOutOfBoundsException if any of the following is true:
342 * <ul>
343 * <li>{@code srcBegin} is negative
344 * <li>{@code dstBegin} is negative
345 * <li>the {@code srcBegin} argument is greater than
346 * the {@code srcEnd} argument.
347 * <li>{@code srcEnd} is greater than
348 * {@code this.length()}.
349 * <li>{@code dstBegin+srcEnd-srcBegin} is greater than
350 * {@code dst.length}
351 * </ul>
352 */
353 public void getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)
354 {
355 if (srcBegin < 0)
356 throw new StringIndexOutOfBoundsException(srcBegin);
357 if ((srcEnd < 0) || (srcEnd > count))
358 throw new StringIndexOutOfBoundsException(srcEnd);
359 if (srcBegin > srcEnd)
360 throw new StringIndexOutOfBoundsException("srcBegin > srcEnd");
361 System.arraycopy(value, srcBegin, dst, dstBegin, srcEnd - srcBegin);
362 }
363
364 /**
365 * The character at the specified index is set to {@code ch}. This
366 * sequence is altered to represent a new character sequence that is
367 * identical to the old character sequence, except that it contains the
368 * character {@code ch} at position {@code index}.
369 * <p>
370 * The index argument must be greater than or equal to
371 * {@code 0}, and less than the length of this sequence.
372 *
373 * @param index the index of the character to modify.
374 * @param ch the new character.
375 * @throws IndexOutOfBoundsException if {@code index} is
376 * negative or greater than or equal to {@code length()}.
377 */
378 public void setCharAt(int index, char ch) {
379 if ((index < 0) || (index >= count))
380 throw new StringIndexOutOfBoundsException(index);
381 value[index] = ch;
382 }
383
384 /**
385 * Appends the string representation of the {@code Object} argument.
386 * <p>
387 * The overall effect is exactly as if the argument were converted
388 * to a string by the method {@link String#valueOf(Object)},
389 * and the characters of that string were then
390 * {@link #append(String) appended} to this character sequence.
391 *
392 * @param obj an {@code Object}.
393 * @return a reference to this object.
394 */
395 public AbstractStringBuilder append(Object obj) {
396 return append(String.valueOf(obj));
397 }
398
399 /**
400 * Appends the specified string to this character sequence.
401 * <p>
402 * The characters of the {@code String} argument are appended, in
403 * order, increasing the length of this sequence by the length of the
404 * argument. If {@code str} is {@code null}, then the four
405 * characters {@code "null"} are appended.
406 * <p>
407 * Let <i>n</i> be the length of this character sequence just prior to
408 * execution of the {@code append} method. Then the character at
409 * index <i>k</i> in the new character sequence is equal to the character
410 * at index <i>k</i> in the old character sequence, if <i>k</i> is less
411 * than <i>n</i>; otherwise, it is equal to the character at index
412 * <i>k-n</i> in the argument {@code str}.
413 *
414 * @param str a string.
415 * @return a reference to this object.
416 */
417 public AbstractStringBuilder append(String str) {
418 if (str == null) str = "null";
419 int len = str.length();
420 ensureCapacityInternal(count + len);
421 str.getChars(0, len, value, count);
422 count += len;
423 return this;
424 }
425
426 // Documentation in subclasses because of synchro difference
427 public AbstractStringBuilder append(StringBuffer sb) {
428 if (sb == null)
429 return append("null");
430 int len = sb.length();
431 ensureCapacityInternal(count + len);
432 sb.getChars(0, len, value, count);
433 count += len;
434 return this;
435 }
436
437 /**
438 * @since 1.8
439 */
440 AbstractStringBuilder append(AbstractStringBuilder asb) {
441 if (asb == null)
442 return append("null");
443 int len = asb.length();
444 ensureCapacityInternal(count + len);
445 asb.getChars(0, len, value, count);
446 count += len;
447 return this;
448 }
449
450 // Documentation in subclasses because of synchro difference
451 @Override
452 public AbstractStringBuilder append(CharSequence s) {
453 if (s == null)
454 s = "null";
455 if (s instanceof String)
456 return this.append((String)s);
457 if (s instanceof AbstractStringBuilder)
458 return this.append((AbstractStringBuilder)s);
459
460 return this.append(s, 0, s.length());
461 }
462
463 /**
464 * Appends a subsequence of the specified {@code CharSequence} to this
465 * sequence.
466 * <p>
467 * Characters of the argument {@code s}, starting at
468 * index {@code start}, are appended, in order, to the contents of
469 * this sequence up to the (exclusive) index {@code end}. The length
470 * of this sequence is increased by the value of {@code end - start}.
471 * <p>
472 * Let <i>n</i> be the length of this character sequence just prior to
473 * execution of the {@code append} method. Then the character at
474 * index <i>k</i> in this character sequence becomes equal to the
475 * character at index <i>k</i> in this sequence, if <i>k</i> is less than
476 * <i>n</i>; otherwise, it is equal to the character at index
477 * <i>k+start-n</i> in the argument {@code s}.
478 * <p>
479 * If {@code s} is {@code null}, then this method appends
480 * characters as if the s parameter was a sequence containing the four
481 * characters {@code "null"}.
482 *
483 * @param s the sequence to append.
484 * @param start the starting index of the subsequence to be appended.
485 * @param end the end index of the subsequence to be appended.
486 * @return a reference to this object.
487 * @throws IndexOutOfBoundsException if
488 * {@code start} is negative, or
489 * {@code start} is greater than {@code end} or
490 * {@code end} is greater than {@code s.length()}
491 */
492 @Override
493 public AbstractStringBuilder append(CharSequence s, int start, int end) {
494 if (s == null)
495 s = "null";
496 if ((start < 0) || (start > end) || (end > s.length()))
497 throw new IndexOutOfBoundsException(
498 "start " + start + ", end " + end + ", s.length() "
499 + s.length());
500 int len = end - start;
501 ensureCapacityInternal(count + len);
502 if (s instanceof String) {
503 System.arraycopy(((String)s).value, start, value, count, len);
504 } else if ((s instanceof StringBuilder) || (s instanceof StringBuffer)) {
505 // two instanceof on leaf class is faster than instanceof check on AbstractStringBuilder.
506 System.arraycopy(((AbstractStringBuilder)s).value, start, value, count, len);
507 } else {
508 // unspecialized path
509 for (int i = start, j = count; i < end; i++, j++) {
510 value[j] = s.charAt(i);
511 }
512 }
513 count += len;
514 return this;
515 }
516
517 /**
518 * Appends the string representation of the {@code char} array
519 * argument to this sequence.
520 * <p>
521 * The characters of the array argument are appended, in order, to
522 * the contents of this sequence. The length of this sequence
523 * increases by the length of the argument.
524 * <p>
525 * The overall effect is exactly as if the argument were converted
526 * to a string by the method {@link String#valueOf(char[])},
527 * and the characters of that string were then
528 * {@link #append(String) appended} to this character sequence.
529 *
530 * @param str the characters to be appended.
531 * @return a reference to this object.
532 */
533 public AbstractStringBuilder append(char[] str) {
534 int len = str.length;
535 ensureCapacityInternal(count + len);
536 System.arraycopy(str, 0, value, count, len);
537 count += len;
538 return this;
539 }
540
541 /**
542 * Appends the string representation of a subarray of the
543 * {@code char} array argument to this sequence.
544 * <p>
545 * Characters of the {@code char} array {@code str}, starting at
546 * index {@code offset}, are appended, in order, to the contents
547 * of this sequence. The length of this sequence increases
548 * by the value of {@code len}.
549 * <p>
550 * The overall effect is exactly as if the arguments were converted
551 * to a string by the method {@link String#valueOf(char[],int,int)},
552 * and the characters of that string were then
553 * {@link #append(String) appended} to this character sequence.
554 *
555 * @param str the characters to be appended.
556 * @param offset the index of the first {@code char} to append.
557 * @param len the number of {@code char}s to append.
558 * @return a reference to this object.
559 * @throws IndexOutOfBoundsException
560 * if {@code offset < 0} or {@code len < 0}
561 * or {@code offset+len > str.length}
562 */
563 public AbstractStringBuilder append(char str[], int offset, int len) {
564 if (len > 0) // let arraycopy report AIOOBE for len < 0
565 ensureCapacityInternal(count + len);
566 System.arraycopy(str, offset, value, count, len);
567 count += len;
568 return this;
569 }
570
571 /**
572 * Appends the string representation of the {@code boolean}
573 * argument to the sequence.
574 * <p>
575 * The overall effect is exactly as if the argument were converted
576 * to a string by the method {@link String#valueOf(boolean)},
577 * and the characters of that string were then
578 * {@link #append(String) appended} to this character sequence.
579 *
580 * @param b a {@code boolean}.
581 * @return a reference to this object.
582 */
583 public AbstractStringBuilder append(boolean b) {
584 if (b) {
585 ensureCapacityInternal(count + 4);
586 value[count++] = 't';
587 value[count++] = 'r';
588 value[count++] = 'u';
589 value[count++] = 'e';
590 } else {
591 ensureCapacityInternal(count + 5);
592 value[count++] = 'f';
593 value[count++] = 'a';
594 value[count++] = 'l';
595 value[count++] = 's';
596 value[count++] = 'e';
597 }
598 return this;
599 }
600
601 /**
602 * Appends the string representation of the {@code char}
603 * argument to this sequence.
604 * <p>
605 * The argument is appended to the contents of this sequence.
606 * The length of this sequence increases by {@code 1}.
607 * <p>
608 * The overall effect is exactly as if the argument were converted
609 * to a string by the method {@link String#valueOf(char)},
610 * and the character in that string were then
611 * {@link #append(String) appended} to this character sequence.
612 *
613 * @param c a {@code char}.
614 * @return a reference to this object.
615 */
616 @Override
617 public AbstractStringBuilder append(char c) {
618 ensureCapacityInternal(count + 1);
619 value[count++] = c;
620 return this;
621 }
622
623 /**
624 * Appends the string representation of the {@code int}
625 * argument to this sequence.
626 * <p>
627 * The overall effect is exactly as if the argument were converted
628 * to a string by the method {@link String#valueOf(int)},
629 * and the characters of that string were then
630 * {@link #append(String) appended} to this character sequence.
631 *
632 * @param i an {@code int}.
633 * @return a reference to this object.
634 */
635 public AbstractStringBuilder append(int i) {
636 if (i == Integer.MIN_VALUE) {
637 append("-2147483648");
638 return this;
639 }
640 int appendedLength = (i < 0) ? Integer.stringSize(-i) + 1
641 : Integer.stringSize(i);
642 int spaceNeeded = count + appendedLength;
643 ensureCapacityInternal(spaceNeeded);
644 Integer.getChars(i, spaceNeeded, value);
645 count = spaceNeeded;
646 return this;
647 }
648
649 /**
650 * Appends the string representation of the {@code long}
651 * argument to this sequence.
652 * <p>
653 * The overall effect is exactly as if the argument were converted
654 * to a string by the method {@link String#valueOf(long)},
655 * and the characters of that string were then
656 * {@link #append(String) appended} to this character sequence.
657 *
658 * @param l a {@code long}.
659 * @return a reference to this object.
660 */
661 public AbstractStringBuilder append(long l) {
662 if (l == Long.MIN_VALUE) {
663 append("-9223372036854775808");
664 return this;
665 }
666 int appendedLength = (l < 0) ? Long.stringSize(-l) + 1
667 : Long.stringSize(l);
668 int spaceNeeded = count + appendedLength;
669 ensureCapacityInternal(spaceNeeded);
670 Long.getChars(l, spaceNeeded, value);
671 count = spaceNeeded;
672 return this;
673 }
674
675 /**
676 * Appends the string representation of the {@code float}
677 * argument to this sequence.
678 * <p>
679 * The overall effect is exactly as if the argument were converted
680 * to a string by the method {@link String#valueOf(float)},
681 * and the characters of that string were then
682 * {@link #append(String) appended} to this character sequence.
683 *
684 * @param f a {@code float}.
685 * @return a reference to this object.
686 */
687 public AbstractStringBuilder append(float f) {
688 new FloatingDecimal(f).appendTo(this);
689 return this;
690 }
691
692 /**
693 * Appends the string representation of the {@code double}
694 * argument to this sequence.
695 * <p>
696 * The overall effect is exactly as if the argument were converted
697 * to a string by the method {@link String#valueOf(double)},
698 * and the characters of that string were then
699 * {@link #append(String) appended} to this character sequence.
700 *
701 * @param d a {@code double}.
702 * @return a reference to this object.
703 */
704 public AbstractStringBuilder append(double d) {
705 new FloatingDecimal(d).appendTo(this);
706 return this;
707 }
708
709 /**
710 * Removes the characters in a substring of this sequence.
711 * The substring begins at the specified {@code start} and extends to
712 * the character at index {@code end - 1} or to the end of the
713 * sequence if no such character exists. If
714 * {@code start} is equal to {@code end}, no changes are made.
715 *
716 * @param start The beginning index, inclusive.
717 * @param end The ending index, exclusive.
718 * @return This object.
719 * @throws StringIndexOutOfBoundsException if {@code start}
720 * is negative, greater than {@code length()}, or
721 * greater than {@code end}.
722 */
723 public AbstractStringBuilder delete(int start, int end) {
724 if (start < 0)
725 throw new StringIndexOutOfBoundsException(start);
726 if (end > count)
727 end = count;
728 if (start > end)
729 throw new StringIndexOutOfBoundsException();
730 int len = end - start;
731 if (len > 0) {
732 System.arraycopy(value, start+len, value, start, count-end);
733 count -= len;
734 }
735 return this;
736 }
737
738 /**
739 * Appends the string representation of the {@code codePoint}
740 * argument to this sequence.
741 *
742 * <p> The argument is appended to the contents of this sequence.
743 * The length of this sequence increases by
744 * {@link Character#charCount(int) Character.charCount(codePoint)}.
745 *
746 * <p> The overall effect is exactly as if the argument were
747 * converted to a {@code char} array by the method
748 * {@link Character#toChars(int)} and the character in that array
749 * were then {@link #append(char[]) appended} to this character
750 * sequence.
751 *
752 * @param codePoint a Unicode code point
753 * @return a reference to this object.
754 * @exception IllegalArgumentException if the specified
755 * {@code codePoint} isn't a valid Unicode code point
756 */
757 public AbstractStringBuilder appendCodePoint(int codePoint) {
758 final int count = this.count;
759
760 if (Character.isBmpCodePoint(codePoint)) {
761 ensureCapacityInternal(count + 1);
762 value[count] = (char) codePoint;
763 this.count = count + 1;
764 } else if (Character.isValidCodePoint(codePoint)) {
765 ensureCapacityInternal(count + 2);
766 Character.toSurrogates(codePoint, value, count);
767 this.count = count + 2;
768 } else {
769 throw new IllegalArgumentException();
770 }
771 return this;
772 }
773
774 /**
775 * Removes the {@code char} at the specified position in this
776 * sequence. This sequence is shortened by one {@code char}.
777 *
778 * <p>Note: If the character at the given index is a supplementary
779 * character, this method does not remove the entire character. If
780 * correct handling of supplementary characters is required,
781 * determine the number of {@code char}s to remove by calling
782 * {@code Character.charCount(thisSequence.codePointAt(index))},
783 * where {@code thisSequence} is this sequence.
784 *
785 * @param index Index of {@code char} to remove
786 * @return This object.
787 * @throws StringIndexOutOfBoundsException if the {@code index}
788 * is negative or greater than or equal to
789 * {@code length()}.
790 */
791 public AbstractStringBuilder deleteCharAt(int index) {
792 if ((index < 0) || (index >= count))
793 throw new StringIndexOutOfBoundsException(index);
794 System.arraycopy(value, index+1, value, index, count-index-1);
795 count--;
796 return this;
797 }
798
799 /**
800 * Replaces the characters in a substring of this sequence
801 * with characters in the specified {@code String}. The substring
802 * begins at the specified {@code start} and extends to the character
803 * at index {@code end - 1} or to the end of the
804 * sequence if no such character exists. First the
805 * characters in the substring are removed and then the specified
806 * {@code String} is inserted at {@code start}. (This
807 * sequence will be lengthened to accommodate the
808 * specified String if necessary.)
809 *
810 * @param start The beginning index, inclusive.
811 * @param end The ending index, exclusive.
812 * @param str String that will replace previous contents.
813 * @return This object.
814 * @throws StringIndexOutOfBoundsException if {@code start}
815 * is negative, greater than {@code length()}, or
816 * greater than {@code end}.
817 */
818 public AbstractStringBuilder replace(int start, int end, String str) {
819 if (start < 0)
820 throw new StringIndexOutOfBoundsException(start);
821 if (start > count)
822 throw new StringIndexOutOfBoundsException("start > length()");
823 if (start > end)
824 throw new StringIndexOutOfBoundsException("start > end");
825
826 if (end > count)
827 end = count;
828 int len = str.length();
829 int newCount = count + len - (end - start);
830 ensureCapacityInternal(newCount);
831
832 System.arraycopy(value, end, value, start + len, count - end);
833 str.getChars(value, start);
834 count = newCount;
835 return this;
836 }
837
838 /**
839 * Returns a new {@code String} that contains a subsequence of
840 * characters currently contained in this character sequence. The
841 * substring begins at the specified index and extends to the end of
842 * this sequence.
843 *
844 * @param start The beginning index, inclusive.
845 * @return The new string.
846 * @throws StringIndexOutOfBoundsException if {@code start} is
847 * less than zero, or greater than the length of this object.
848 */
849 public String substring(int start) {
850 return substring(start, count);
851 }
852
853 /**
854 * Returns a new character sequence that is a subsequence of this sequence.
855 *
856 * <p> An invocation of this method of the form
857 *
858 * <blockquote><pre>
859 * sb.subSequence(begin, end)</pre></blockquote>
860 *
861 * behaves in exactly the same way as the invocation
862 *
863 * <blockquote><pre>
864 * sb.substring(begin, end)</pre></blockquote>
865 *
866 * This method is provided so that this class can
867 * implement the {@link CharSequence} interface. </p>
868 *
869 * @param start the start index, inclusive.
870 * @param end the end index, exclusive.
871 * @return the specified subsequence.
872 *
873 * @throws IndexOutOfBoundsException
874 * if {@code start} or {@code end} are negative,
875 * if {@code end} is greater than {@code length()},
876 * or if {@code start} is greater than {@code end}
877 * @spec JSR-51
878 */
879 @Override
880 public CharSequence subSequence(int start, int end) {
881 return substring(start, end);
882 }
883
884 /**
885 * Returns a new {@code String} that contains a subsequence of
886 * characters currently contained in this sequence. The
887 * substring begins at the specified {@code start} and
888 * extends to the character at index {@code end - 1}.
889 *
890 * @param start The beginning index, inclusive.
891 * @param end The ending index, exclusive.
892 * @return The new string.
893 * @throws StringIndexOutOfBoundsException if {@code start}
894 * or {@code end} are negative or greater than
895 * {@code length()}, or {@code start} is
896 * greater than {@code end}.
897 */
898 public String substring(int start, int end) {
899 if (start < 0)
900 throw new StringIndexOutOfBoundsException(start);
901 if (end > count)
902 throw new StringIndexOutOfBoundsException(end);
903 if (start > end)
904 throw new StringIndexOutOfBoundsException(end - start);
905 return new String(value, start, end - start);
906 }
907
908 /**
909 * Inserts the string representation of a subarray of the {@code str}
910 * array argument into this sequence. The subarray begins at the
911 * specified {@code offset} and extends {@code len} {@code char}s.
912 * The characters of the subarray are inserted into this sequence at
913 * the position indicated by {@code index}. The length of this
914 * sequence increases by {@code len} {@code char}s.
915 *
916 * @param index position at which to insert subarray.
917 * @param str A {@code char} array.
918 * @param offset the index of the first {@code char} in subarray to
919 * be inserted.
920 * @param len the number of {@code char}s in the subarray to
921 * be inserted.
922 * @return This object
923 * @throws StringIndexOutOfBoundsException if {@code index}
924 * is negative or greater than {@code length()}, or
925 * {@code offset} or {@code len} are negative, or
926 * {@code (offset+len)} is greater than
927 * {@code str.length}.
928 */
929 public AbstractStringBuilder insert(int index, char[] str, int offset,
930 int len)
931 {
932 if ((index < 0) || (index > length()))
933 throw new StringIndexOutOfBoundsException(index);
934 if ((offset < 0) || (len < 0) || (offset > str.length - len))
935 throw new StringIndexOutOfBoundsException(
936 "offset " + offset + ", len " + len + ", str.length "
937 + str.length);
938 ensureCapacityInternal(count + len);
939 System.arraycopy(value, index, value, index + len, count - index);
940 System.arraycopy(str, offset, value, index, len);
941 count += len;
942 return this;
943 }
944
945 /**
946 * Inserts the string representation of the {@code Object}
947 * argument into this character sequence.
948 * <p>
949 * The overall effect is exactly as if the second argument were
950 * converted to a string by the method {@link String#valueOf(Object)},
951 * and the characters of that string were then
952 * {@link #insert(int,String) inserted} into this character
953 * sequence at the indicated offset.
954 * <p>
955 * The {@code offset} argument must be greater than or equal to
956 * {@code 0}, and less than or equal to the {@linkplain #length() length}
957 * of this sequence.
958 *
959 * @param offset the offset.
960 * @param obj an {@code Object}.
961 * @return a reference to this object.
962 * @throws StringIndexOutOfBoundsException if the offset is invalid.
963 */
964 public AbstractStringBuilder insert(int offset, Object obj) {
965 return insert(offset, String.valueOf(obj));
966 }
967
968 /**
969 * Inserts the string into this character sequence.
970 * <p>
971 * The characters of the {@code String} argument are inserted, in
972 * order, into this sequence at the indicated offset, moving up any
973 * characters originally above that position and increasing the length
974 * of this sequence by the length of the argument. If
975 * {@code str} is {@code null}, then the four characters
976 * {@code "null"} are inserted into this sequence.
977 * <p>
978 * The character at index <i>k</i> in the new character sequence is
979 * equal to:
980 * <ul>
981 * <li>the character at index <i>k</i> in the old character sequence, if
982 * <i>k</i> is less than {@code offset}
983 * <li>the character at index <i>k</i>{@code -offset} in the
984 * argument {@code str}, if <i>k</i> is not less than
985 * {@code offset} but is less than {@code offset+str.length()}
986 * <li>the character at index <i>k</i>{@code -str.length()} in the
987 * old character sequence, if <i>k</i> is not less than
988 * {@code offset+str.length()}
989 * </ul><p>
990 * The {@code offset} argument must be greater than or equal to
991 * {@code 0}, and less than or equal to the {@linkplain #length() length}
992 * of this sequence.
993 *
994 * @param offset the offset.
995 * @param str a string.
996 * @return a reference to this object.
997 * @throws StringIndexOutOfBoundsException if the offset is invalid.
998 */
999 public AbstractStringBuilder insert(int offset, String str) {
1000 if ((offset < 0) || (offset > length()))
1001 throw new StringIndexOutOfBoundsException(offset);
1002 if (str == null)
1003 str = "null";
1004 int len = str.length();
1005 ensureCapacityInternal(count + len);
1006 System.arraycopy(value, offset, value, offset + len, count - offset);
1007 str.getChars(value, offset);
1008 count += len;
1009 return this;
1010 }
1011
1012 /**
1013 * Inserts the string representation of the {@code char} array
1014 * argument into this sequence.
1015 * <p>
1016 * The characters of the array argument are inserted into the
1017 * contents of this sequence at the position indicated by
1018 * {@code offset}. The length of this sequence increases by
1019 * the length of the argument.
1020 * <p>
1021 * The overall effect is exactly as if the second argument were
1022 * converted to a string by the method {@link String#valueOf(char[])},
1023 * and the characters of that string were then
1024 * {@link #insert(int,String) inserted} into this character
1025 * sequence at the indicated offset.
1026 * <p>
1027 * The {@code offset} argument must be greater than or equal to
1028 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1029 * of this sequence.
1030 *
1031 * @param offset the offset.
1032 * @param str a character array.
1033 * @return a reference to this object.
1034 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1035 */
1036 public AbstractStringBuilder insert(int offset, char[] str) {
1037 if ((offset < 0) || (offset > length()))
1038 throw new StringIndexOutOfBoundsException(offset);
1039 int len = str.length;
1040 ensureCapacityInternal(count + len);
1041 System.arraycopy(value, offset, value, offset + len, count - offset);
1042 System.arraycopy(str, 0, value, offset, len);
1043 count += len;
1044 return this;
1045 }
1046
1047 /**
1048 * Inserts the specified {@code CharSequence} into this sequence.
1049 * <p>
1050 * The characters of the {@code CharSequence} argument are inserted,
1051 * in order, into this sequence at the indicated offset, moving up
1052 * any characters originally above that position and increasing the length
1053 * of this sequence by the length of the argument s.
1054 * <p>
1055 * The result of this method is exactly the same as if it were an
1056 * invocation of this object's
1057 * {@link #insert(int,CharSequence,int,int) insert}(dstOffset, s, 0, s.length())
1058 * method.
1059 *
1060 * <p>If {@code s} is {@code null}, then the four characters
1061 * {@code "null"} are inserted into this sequence.
1062 *
1063 * @param dstOffset the offset.
1064 * @param s the sequence to be inserted
1065 * @return a reference to this object.
1066 * @throws IndexOutOfBoundsException if the offset is invalid.
1067 */
1068 public AbstractStringBuilder insert(int dstOffset, CharSequence s) {
1069 if (s == null)
1070 s = "null";
1071 if (s instanceof String)
1072 return this.insert(dstOffset, (String)s);
1073 return this.insert(dstOffset, s, 0, s.length());
1074 }
1075
1076 /**
1077 * Inserts a subsequence of the specified {@code CharSequence} into
1078 * this sequence.
1079 * <p>
1080 * The subsequence of the argument {@code s} specified by
1081 * {@code start} and {@code end} are inserted,
1082 * in order, into this sequence at the specified destination offset, moving
1083 * up any characters originally above that position. The length of this
1084 * sequence is increased by {@code end - start}.
1085 * <p>
1086 * The character at index <i>k</i> in this sequence becomes equal to:
1087 * <ul>
1088 * <li>the character at index <i>k</i> in this sequence, if
1089 * <i>k</i> is less than {@code dstOffset}
1090 * <li>the character at index <i>k</i>{@code +start-dstOffset} in
1091 * the argument {@code s}, if <i>k</i> is greater than or equal to
1092 * {@code dstOffset} but is less than {@code dstOffset+end-start}
1093 * <li>the character at index <i>k</i>{@code -(end-start)} in this
1094 * sequence, if <i>k</i> is greater than or equal to
1095 * {@code dstOffset+end-start}
1096 * </ul><p>
1097 * The {@code dstOffset} argument must be greater than or equal to
1098 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1099 * of this sequence.
1100 * <p>The start argument must be nonnegative, and not greater than
1101 * {@code end}.
1102 * <p>The end argument must be greater than or equal to
1103 * {@code start}, and less than or equal to the length of s.
1104 *
1105 * <p>If {@code s} is {@code null}, then this method inserts
1106 * characters as if the s parameter was a sequence containing the four
1107 * characters {@code "null"}.
1108 *
1109 * @param dstOffset the offset in this sequence.
1110 * @param s the sequence to be inserted.
1111 * @param start the starting index of the subsequence to be inserted.
1112 * @param end the end index of the subsequence to be inserted.
1113 * @return a reference to this object.
1114 * @throws IndexOutOfBoundsException if {@code dstOffset}
1115 * is negative or greater than {@code this.length()}, or
1116 * {@code start} or {@code end} are negative, or
1117 * {@code start} is greater than {@code end} or
1118 * {@code end} is greater than {@code s.length()}
1119 */
1120 public AbstractStringBuilder insert(int dstOffset, CharSequence s,
1121 int start, int end) {
1122 if (s == null)
1123 s = "null";
1124 if ((dstOffset < 0) || (dstOffset > this.length()))
1125 throw new IndexOutOfBoundsException("dstOffset "+dstOffset);
1126 if ((start < 0) || (end < 0) || (start > end) || (end > s.length()))
1127 throw new IndexOutOfBoundsException(
1128 "start " + start + ", end " + end + ", s.length() "
1129 + s.length());
1130 int len = end - start;
1131 ensureCapacityInternal(count + len);
1132 System.arraycopy(value, dstOffset, value, dstOffset + len,
1133 count - dstOffset);
1134 if (s instanceof String) {
1135 System.arraycopy(((String)s).value, start, value, dstOffset, len);
1136 } else if ((s instanceof StringBuilder) || (s instanceof StringBuffer)) {
1137 // two instanceof on leaf class is faster than instanceof check on AbstractStringBuilder.
1138 System.arraycopy(((AbstractStringBuilder)s).value, start, value, dstOffset, len);
1139 } else {
1140 // unspecialized path
1141 for (int i=start; i<end; i++)
1142 value[dstOffset++] = s.charAt(i);
1143 }
1144 count += len;
1145 return this;
1146 }
1147
1148 /**
1149 * Inserts the string representation of the {@code boolean}
1150 * argument into this sequence.
1151 * <p>
1152 * The overall effect is exactly as if the second argument were
1153 * converted to a string by the method {@link String#valueOf(boolean)},
1154 * and the characters of that string were then
1155 * {@link #insert(int,String) inserted} into this character
1156 * sequence at the indicated offset.
1157 * <p>
1158 * The {@code offset} argument must be greater than or equal to
1159 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1160 * of this sequence.
1161 *
1162 * @param offset the offset.
1163 * @param b a {@code boolean}.
1164 * @return a reference to this object.
1165 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1166 */
1167 public AbstractStringBuilder insert(int offset, boolean b) {
1168 return insert(offset, String.valueOf(b));
1169 }
1170
1171 /**
1172 * Inserts the string representation of the {@code char}
1173 * argument into this sequence.
1174 * <p>
1175 * The overall effect is exactly as if the second argument were
1176 * converted to a string by the method {@link String#valueOf(char)},
1177 * and the character in that string were then
1178 * {@link #insert(int,String) inserted} into this character
1179 * sequence at the indicated offset.
1180 * <p>
1181 * The {@code offset} argument must be greater than or equal to
1182 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1183 * of this sequence.
1184 *
1185 * @param offset the offset.
1186 * @param c a {@code char}.
1187 * @return a reference to this object.
1188 * @throws IndexOutOfBoundsException if the offset is invalid.
1189 */
1190 public AbstractStringBuilder insert(int offset, char c) {
1191 ensureCapacityInternal(count + 1);
1192 System.arraycopy(value, offset, value, offset + 1, count - offset);
1193 value[offset] = c;
1194 count += 1;
1195 return this;
1196 }
1197
1198 /**
1199 * Inserts the string representation of the second {@code int}
1200 * argument into this sequence.
1201 * <p>
1202 * The overall effect is exactly as if the second argument were
1203 * converted to a string by the method {@link String#valueOf(int)},
1204 * and the characters of that string were then
1205 * {@link #insert(int,String) inserted} into this character
1206 * sequence at the indicated offset.
1207 * <p>
1208 * The {@code offset} argument must be greater than or equal to
1209 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1210 * of this sequence.
1211 *
1212 * @param offset the offset.
1213 * @param i an {@code int}.
1214 * @return a reference to this object.
1215 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1216 */
1217 public AbstractStringBuilder insert(int offset, int i) {
1218 return insert(offset, String.valueOf(i));
1219 }
1220
1221 /**
1222 * Inserts the string representation of the {@code long}
1223 * argument into this sequence.
1224 * <p>
1225 * The overall effect is exactly as if the second argument were
1226 * converted to a string by the method {@link String#valueOf(long)},
1227 * and the characters of that string were then
1228 * {@link #insert(int,String) inserted} into this character
1229 * sequence at the indicated offset.
1230 * <p>
1231 * The {@code offset} argument must be greater than or equal to
1232 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1233 * of this sequence.
1234 *
1235 * @param offset the offset.
1236 * @param l a {@code long}.
1237 * @return a reference to this object.
1238 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1239 */
1240 public AbstractStringBuilder insert(int offset, long l) {
1241 return insert(offset, String.valueOf(l));
1242 }
1243
1244 /**
1245 * Inserts the string representation of the {@code float}
1246 * argument into this sequence.
1247 * <p>
1248 * The overall effect is exactly as if the second argument were
1249 * converted to a string by the method {@link String#valueOf(float)},
1250 * and the characters of that string were then
1251 * {@link #insert(int,String) inserted} into this character
1252 * sequence at the indicated offset.
1253 * <p>
1254 * The {@code offset} argument must be greater than or equal to
1255 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1256 * of this sequence.
1257 *
1258 * @param offset the offset.
1259 * @param f a {@code float}.
1260 * @return a reference to this object.
1261 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1262 */
1263 public AbstractStringBuilder insert(int offset, float f) {
1264 return insert(offset, String.valueOf(f));
1265 }
1266
1267 /**
1268 * Inserts the string representation of the {@code double}
1269 * argument into this sequence.
1270 * <p>
1271 * The overall effect is exactly as if the second argument were
1272 * converted to a string by the method {@link String#valueOf(double)},
1273 * and the characters of that string were then
1274 * {@link #insert(int,String) inserted} into this character
1275 * sequence at the indicated offset.
1276 * <p>
1277 * The {@code offset} argument must be greater than or equal to
1278 * {@code 0}, and less than or equal to the {@linkplain #length() length}
1279 * of this sequence.
1280 *
1281 * @param offset the offset.
1282 * @param d a {@code double}.
1283 * @return a reference to this object.
1284 * @throws StringIndexOutOfBoundsException if the offset is invalid.
1285 */
1286 public AbstractStringBuilder insert(int offset, double d) {
1287 return insert(offset, String.valueOf(d));
1288 }
1289
1290 /**
1291 * Returns the index within this string of the first occurrence of the
1292 * specified substring. The integer returned is the smallest value
1293 * <i>k</i> such that:
1294 * <blockquote><pre>
1295 * this.toString().startsWith(str, <i>k</i>)
1296 * </pre></blockquote>
1297 * is {@code true}.
1298 *
1299 * @param str any string.
1300 * @return if the string argument occurs as a substring within this
1301 * object, then the index of the first character of the first
1302 * such substring is returned; if it does not occur as a
1303 * substring, {@code -1} is returned.
1304 */
1305 public int indexOf(String str) {
1306 return indexOf(str, 0);
1307 }
1308
1309 /**
1310 * Returns the index within this string of the first occurrence of the
1311 * specified substring, starting at the specified index. The integer
1312 * returned is the smallest value {@code k} for which:
1313 * <blockquote><pre>
1314 * k >= Math.min(fromIndex, str.length()) &&
1315 * this.toString().startsWith(str, k)
1316 * </pre></blockquote>
1317 * If no such value of <i>k</i> exists, then -1 is returned.
1318 *
1319 * @param str the substring for which to search.
1320 * @param fromIndex the index from which to start the search.
1321 * @return the index within this string of the first occurrence of the
1322 * specified substring, starting at the specified index.
1323 */
1324 public int indexOf(String str, int fromIndex) {
1325 return String.indexOf(value, 0, count, str, fromIndex);
1326 }
1327
1328 /**
1329 * Returns the index within this string of the rightmost occurrence
1330 * of the specified substring. The rightmost empty string "" is
1331 * considered to occur at the index value {@code this.length()}.
1332 * The returned index is the largest value <i>k</i> such that
1333 * <blockquote><pre>
1334 * this.toString().startsWith(str, k)
1335 * </pre></blockquote>
1336 * is true.
1337 *
1338 * @param str the substring to search for.
1339 * @return if the string argument occurs one or more times as a substring
1340 * within this object, then the index of the first character of
1341 * the last such substring is returned. If it does not occur as
1342 * a substring, {@code -1} is returned.
1343 */
1344 public int lastIndexOf(String str) {
1345 return lastIndexOf(str, count);
1346 }
1347
1348 /**
1349 * Returns the index within this string of the last occurrence of the
1350 * specified substring. The integer returned is the largest value <i>k</i>
1351 * such that:
1352 * <blockquote><pre>
1353 * k <= Math.min(fromIndex, str.length()) &&
1354 * this.toString().startsWith(str, k)
1355 * </pre></blockquote>
1356 * If no such value of <i>k</i> exists, then -1 is returned.
1357 *
1358 * @param str the substring to search for.
1359 * @param fromIndex the index to start the search from.
1360 * @return the index within this sequence of the last occurrence of the
1361 * specified substring.
1362 */
1363 public int lastIndexOf(String str, int fromIndex) {
1364 return String.lastIndexOf(value, 0, count, str, fromIndex);
1365 }
1366
1367 /**
1368 * Causes this character sequence to be replaced by the reverse of
1369 * the sequence. If there are any surrogate pairs included in the
1370 * sequence, these are treated as single characters for the
1371 * reverse operation. Thus, the order of the high-low surrogates
1372 * is never reversed.
1373 *
1374 * Let <i>n</i> be the character length of this character sequence
1375 * (not the length in {@code char} values) just prior to
1376 * execution of the {@code reverse} method. Then the
1377 * character at index <i>k</i> in the new character sequence is
1378 * equal to the character at index <i>n-k-1</i> in the old
1379 * character sequence.
1380 *
1381 * <p>Note that the reverse operation may result in producing
1382 * surrogate pairs that were unpaired low-surrogates and
1383 * high-surrogates before the operation. For example, reversing
1384 * "\u005CuDC00\u005CuD800" produces "\u005CuD800\u005CuDC00" which is
1385 * a valid surrogate pair.
1386 *
1387 * @return a reference to this object.
1388 */
1389 public AbstractStringBuilder reverse() {
1390 boolean hasSurrogate = false;
1391 int n = count - 1;
1392 for (int j = (n-1) >> 1; j >= 0; --j) {
1393 char temp = value[j];
1394 char temp2 = value[n - j];
1395 if (!hasSurrogate) {
1396 hasSurrogate = (temp >= Character.MIN_SURROGATE && temp <= Character.MAX_SURROGATE)
1397 || (temp2 >= Character.MIN_SURROGATE && temp2 <= Character.MAX_SURROGATE);
1398 }
1399 value[j] = temp2;
1400 value[n - j] = temp;
1401 }
1402 if (hasSurrogate) {
1403 // Reverse back all valid surrogate pairs
1404 for (int i = 0; i < count - 1; i++) {
1405 char c2 = value[i];
1406 if (Character.isLowSurrogate(c2)) {
1407 char c1 = value[i + 1];
1408 if (Character.isHighSurrogate(c1)) {
1409 value[i++] = c1;
1410 value[i] = c2;
1411 }
1412 }
1413 }
1414 }
1415 return this;
1416 }
1417
1418 /**
1419 * Returns a string representing the data in this sequence.
1420 * A new {@code String} object is allocated and initialized to
1421 * contain the character sequence currently represented by this
1422 * object. This {@code String} is then returned. Subsequent
1423 * changes to this sequence do not affect the contents of the
1424 * {@code String}.
1425 *
1426 * @return a string representation of this sequence of characters.
1427 */
1428 @Override
1429 public abstract String toString();
1430
1431 /**
1432 * Needed by {@code String} for the contentEquals method.
1433 */
1434 final char[] getValue() {
1435 return value;
1436 }
1437
1438 }
--- EOF ---