1 /*
2 * Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27
28 import java.util.Arrays;
29 import jdk.internal.HotSpotIntrinsicCandidate;
30
31 /**
32 * A thread-safe, mutable sequence of characters.
33 * A string buffer is like a {@link String}, but can be modified. At any
34 * point in time it contains some particular sequence of characters, but
35 * the length and content of the sequence can be changed through certain
36 * method calls.
37 * <p>
38 * String buffers are safe for use by multiple threads. The methods
39 * are synchronized where necessary so that all the operations on any
40 * particular instance behave as if they occur in some serial order
41 * that is consistent with the order of the method calls made by each of
42 * the individual threads involved.
43 * <p>
44 * The principal operations on a {@code StringBuffer} are the
45 * {@code append} and {@code insert} methods, which are
46 * overloaded so as to accept data of any type. Each effectively
47 * converts a given datum to a string and then appends or inserts the
48 * characters of that string to the string buffer. The
49 * {@code append} method always adds these characters at the end
50 * of the buffer; the {@code insert} method adds the characters at
51 * a specified point.
52 * <p>
53 * For example, if {@code z} refers to a string buffer object
54 * whose current contents are {@code "start"}, then
55 * the method call {@code z.append("le")} would cause the string
56 * buffer to contain {@code "startle"}, whereas
57 * {@code z.insert(4, "le")} would alter the string buffer to
58 * contain {@code "starlet"}.
59 * <p>
60 * In general, if sb refers to an instance of a {@code StringBuffer},
61 * then {@code sb.append(x)} has the same effect as
62 * {@code sb.insert(sb.length(), x)}.
63 * <p>
64 * Whenever an operation occurs involving a source sequence (such as
65 * appending or inserting from a source sequence), this class synchronizes
66 * only on the string buffer performing the operation, not on the source.
67 * Note that while {@code StringBuffer} is designed to be safe to use
68 * concurrently from multiple threads, if the constructor or the
69 * {@code append} or {@code insert} operation is passed a source sequence
70 * that is shared across threads, the calling code must ensure
71 * that the operation has a consistent and unchanging view of the source
72 * sequence for the duration of the operation.
73 * This could be satisfied by the caller holding a lock during the
74 * operation's call, by using an immutable source sequence, or by not
75 * sharing the source sequence across threads.
76 * <p>
77 * Every string buffer has a capacity. As long as the length of the
78 * character sequence contained in the string buffer does not exceed
79 * the capacity, it is not necessary to allocate a new internal
80 * buffer array. If the internal buffer overflows, it is
81 * automatically made larger.
82 * <p>
83 * Unless otherwise noted, passing a {@code null} argument to a constructor
84 * or method in this class will cause a {@link NullPointerException} to be
85 * thrown.
86 * <p>
87 * As of release JDK 5, this class has been supplemented with an equivalent
88 * class designed for use by a single thread, {@link StringBuilder}. The
89 * {@code StringBuilder} class should generally be used in preference to
90 * this one, as it supports all of the same operations but it is faster, as
91 * it performs no synchronization.
92 *
93 * @apiNote
94 * {@code StringBuffer} implements {@code Comparable} but does not override
95 * {@link Object#equals equals}. Thus, the natural ordering of {@code StringBuffer}
96 * is inconsistent with equals. Care should be exercised if {@code StringBuffer}
97 * objects are used as keys in a {@code SortedMap} or elements in a {@code SortedSet}.
98 * See {@link Comparable}, {@link java.util.SortedMap SortedMap}, or
99 * {@link java.util.SortedSet SortedSet} for more information.
100 *
101 * @author Arthur van Hoff
102 * @see java.lang.StringBuilder
103 * @see java.lang.String
104 * @since 1.0
105 */
106 public final class StringBuffer
107 extends AbstractStringBuilder
108 implements java.io.Serializable, Comparable<StringBuffer>, CharSequence
109 {
110
111 /**
112 * A cache of the last value returned by toString. Cleared
113 * whenever the StringBuffer is modified.
114 */
115 private transient String toStringCache;
116
117 /** use serialVersionUID from JDK 1.0.2 for interoperability */
118 static final long serialVersionUID = 3388685877147921107L;
119
120 /**
121 * Constructs a string buffer with no characters in it and an
122 * initial capacity of 16 characters.
123 */
124 @HotSpotIntrinsicCandidate
125 public StringBuffer() {
126 super(16);
127 }
128
129 /**
130 * Constructs a string buffer with no characters in it and
131 * the specified initial capacity.
132 *
133 * @param capacity the initial capacity.
134 * @throws NegativeArraySizeException if the {@code capacity}
135 * argument is less than {@code 0}.
136 */
137 @HotSpotIntrinsicCandidate
138 public StringBuffer(int capacity) {
139 super(capacity);
140 }
141
142 /**
143 * Constructs a string buffer initialized to the contents of the
144 * specified string. The initial capacity of the string buffer is
145 * {@code 16} plus the length of the string argument.
146 *
147 * @param str the initial contents of the buffer.
148 */
149 @HotSpotIntrinsicCandidate
150 public StringBuffer(String str) {
151 super(str.coder(), str.length(), 16);
152 append(str);
153 }
154
155 /**
156 * Constructs a string buffer that contains the same characters
157 * as the specified {@code CharSequence}. The initial capacity of
158 * the string buffer is {@code 16} plus the length of the
159 * {@code CharSequence} argument.
160 *
161 * @param seq the sequence to copy.
162 * @since 1.5
163 */
164 public StringBuffer(CharSequence seq) {
165 super(getCharSequenceCoderHint(seq), seq.length(), 16);
166 append(seq);
167 }
168
169 /**
170 * Compares two {@code StringBuffer} instances lexicographically. This method
171 * follows the same rules for lexicographical comparison as defined in the
172 * {@linkplain java.lang.CharSequence#compare(java.lang.CharSequence,
173 * java.lang.CharSequence) CharSequence.compare(this, another)} method.
174 *
175 * <p>
176 * For finer-grained, locale-sensitive String comparison, refer to
177 * {@link java.text.Collator}.
178 *
179 * @implNote
180 * This method synchronizes on {@code this}, the current object, but not
181 * {@code StringBuffer another} with which {@code this StringBuffer} is compared.
182 *
183 * @param another the {@code StringBuffer} to be compared with
184 *
185 * @return the value {@code 0} if this {@code StringBuffer} contains the same
186 * character sequence as that of the argument {@code StringBuffer}; a negative integer
187 * if this {@code StringBuffer} is lexicographically less than the
188 * {@code StringBuffer} argument; or a positive integer if this {@code StringBuffer}
189 * is lexicographically greater than the {@code StringBuffer} argument.
190 *
191 * @since 11
192 */
193 @Override
194 public synchronized int compareTo(StringBuffer another) {
195 return super.compareTo(another);
196 }
197
198 @Override
199 public synchronized int length() {
200 return count;
201 }
202
203 @Override
204 public synchronized int capacity() {
205 return super.capacity();
206 }
207
208
209 @Override
210 public synchronized void ensureCapacity(int minimumCapacity) {
211 super.ensureCapacity(minimumCapacity);
212 }
213
214 /**
215 * @since 1.5
216 */
217 @Override
218 public synchronized void trimToSize() {
219 super.trimToSize();
220 }
221
222 /**
223 * @throws IndexOutOfBoundsException {@inheritDoc}
224 * @see #length()
225 */
226 @Override
227 public synchronized void setLength(int newLength) {
228 toStringCache = null;
229 super.setLength(newLength);
230 }
231
232 /**
233 * @throws IndexOutOfBoundsException {@inheritDoc}
234 * @see #length()
235 */
236 @Override
237 public synchronized char charAt(int index) {
238 return super.charAt(index);
239 }
240
241 /**
242 * @throws IndexOutOfBoundsException {@inheritDoc}
243 * @since 1.5
244 */
245 @Override
246 public synchronized int codePointAt(int index) {
247 return super.codePointAt(index);
248 }
249
250 /**
251 * @throws IndexOutOfBoundsException {@inheritDoc}
252 * @since 1.5
253 */
254 @Override
255 public synchronized int codePointBefore(int index) {
256 return super.codePointBefore(index);
257 }
258
259 /**
260 * @throws IndexOutOfBoundsException {@inheritDoc}
261 * @since 1.5
262 */
263 @Override
264 public synchronized int codePointCount(int beginIndex, int endIndex) {
265 return super.codePointCount(beginIndex, endIndex);
266 }
267
268 /**
269 * @throws IndexOutOfBoundsException {@inheritDoc}
270 * @since 1.5
271 */
272 @Override
273 public synchronized int offsetByCodePoints(int index, int codePointOffset) {
274 return super.offsetByCodePoints(index, codePointOffset);
275 }
276
277 /**
278 * @throws IndexOutOfBoundsException {@inheritDoc}
279 */
280 @Override
281 public synchronized void getChars(int srcBegin, int srcEnd, char[] dst,
282 int dstBegin)
283 {
284 super.getChars(srcBegin, srcEnd, dst, dstBegin);
285 }
286
287 /**
288 * @throws IndexOutOfBoundsException {@inheritDoc}
289 * @see #length()
290 */
291 @Override
292 public synchronized void setCharAt(int index, char ch) {
293 toStringCache = null;
294 super.setCharAt(index, ch);
295 }
296
297 @Override
298 public synchronized StringBuffer append(Object obj) {
299 toStringCache = null;
300 super.append(String.valueOf(obj));
301 return this;
302 }
303
304 @Override
305 @HotSpotIntrinsicCandidate
306 public synchronized StringBuffer append(String str) {
307 toStringCache = null;
308 super.append(str);
309 return this;
310 }
311
312 /**
313 * Appends the specified {@code StringBuffer} to this sequence.
314 * <p>
315 * The characters of the {@code StringBuffer} argument are appended,
316 * in order, to the contents of this {@code StringBuffer}, increasing the
317 * length of this {@code StringBuffer} by the length of the argument.
318 * If {@code sb} is {@code null}, then the four characters
319 * {@code "null"} are appended to this {@code StringBuffer}.
320 * <p>
321 * Let <i>n</i> be the length of the old character sequence, the one
322 * contained in the {@code StringBuffer} just prior to execution of the
323 * {@code append} method. Then the character at index <i>k</i> in
324 * the new character sequence is equal to the character at index <i>k</i>
325 * in the old character sequence, if <i>k</i> is less than <i>n</i>;
326 * otherwise, it is equal to the character at index <i>k-n</i> in the
327 * argument {@code sb}.
328 * <p>
329 * This method synchronizes on {@code this}, the destination
330 * object, but does not synchronize on the source ({@code sb}).
331 *
332 * @param sb the {@code StringBuffer} to append.
333 * @return a reference to this object.
334 * @since 1.4
335 */
336 public synchronized StringBuffer append(StringBuffer sb) {
337 toStringCache = null;
338 super.append(sb);
339 return this;
340 }
341
342 /**
343 * @since 1.8
344 */
345 @Override
346 synchronized StringBuffer append(AbstractStringBuilder asb) {
347 toStringCache = null;
348 super.append(asb);
349 return this;
350 }
351
352 /**
353 * Appends the specified {@code CharSequence} to this
354 * sequence.
355 * <p>
356 * The characters of the {@code CharSequence} argument are appended,
357 * in order, increasing the length of this sequence by the length of the
358 * argument.
359 *
360 * <p>The result of this method is exactly the same as if it were an
361 * invocation of this.append(s, 0, s.length());
362 *
363 * <p>This method synchronizes on {@code this}, the destination
364 * object, but does not synchronize on the source ({@code s}).
365 *
366 * <p>If {@code s} is {@code null}, then the four characters
367 * {@code "null"} are appended.
368 *
369 * @param s the {@code CharSequence} to append.
370 * @return a reference to this object.
371 * @since 1.5
372 */
373 @Override
374 public synchronized StringBuffer append(CharSequence s) {
375 toStringCache = null;
376 super.append(s);
377 return this;
378 }
379
380 /**
381 * @throws IndexOutOfBoundsException {@inheritDoc}
382 * @since 1.5
383 */
384 @Override
385 public synchronized StringBuffer append(CharSequence s, int start, int end)
386 {
387 toStringCache = null;
388 super.append(s, start, end);
389 return this;
390 }
391
392 @Override
393 public synchronized StringBuffer append(char[] str) {
394 toStringCache = null;
395 super.append(str);
396 return this;
397 }
398
399 /**
400 * @throws IndexOutOfBoundsException {@inheritDoc}
401 */
402 @Override
403 public synchronized StringBuffer append(char[] str, int offset, int len) {
404 toStringCache = null;
405 super.append(str, offset, len);
406 return this;
407 }
408
409 @Override
410 public synchronized StringBuffer append(boolean b) {
411 toStringCache = null;
412 super.append(b);
413 return this;
414 }
415
416 @Override
417 @HotSpotIntrinsicCandidate
418 public synchronized StringBuffer append(char c) {
419 toStringCache = null;
420 super.append(c);
421 return this;
422 }
423
424 @Override
425 @HotSpotIntrinsicCandidate
426 public synchronized StringBuffer append(int i) {
427 toStringCache = null;
428 super.append(i);
429 return this;
430 }
431
432 /**
433 * @since 1.5
434 */
435 @Override
436 public synchronized StringBuffer appendCodePoint(int codePoint) {
437 toStringCache = null;
438 super.appendCodePoint(codePoint);
439 return this;
440 }
441
442 @Override
443 public synchronized StringBuffer append(long lng) {
444 toStringCache = null;
445 super.append(lng);
446 return this;
447 }
448
449 @Override
450 public synchronized StringBuffer append(float f) {
451 toStringCache = null;
452 super.append(f);
453 return this;
454 }
455
456 @Override
457 public synchronized StringBuffer append(double d) {
458 toStringCache = null;
459 super.append(d);
460 return this;
461 }
462
463 /**
464 * @throws StringIndexOutOfBoundsException {@inheritDoc}
465 * @since 1.2
466 */
467 @Override
468 public synchronized StringBuffer delete(int start, int end) {
469 toStringCache = null;
470 super.delete(start, end);
471 return this;
472 }
473
474 /**
475 * @throws StringIndexOutOfBoundsException {@inheritDoc}
476 * @since 1.2
477 */
478 @Override
479 public synchronized StringBuffer deleteCharAt(int index) {
480 toStringCache = null;
481 super.deleteCharAt(index);
482 return this;
483 }
484
485 /**
486 * @throws StringIndexOutOfBoundsException {@inheritDoc}
487 * @since 1.2
488 */
489 @Override
490 public synchronized StringBuffer replace(int start, int end, String str) {
491 toStringCache = null;
492 super.replace(start, end, str);
493 return this;
494 }
495
496 /**
497 * @throws StringIndexOutOfBoundsException {@inheritDoc}
498 * @since 1.2
499 */
500 @Override
501 public synchronized String substring(int start) {
502 return substring(start, count);
503 }
504
505 /**
506 * @throws IndexOutOfBoundsException {@inheritDoc}
507 * @since 1.4
508 */
509 @Override
510 public synchronized CharSequence subSequence(int start, int end) {
511 return super.substring(start, end);
512 }
513
514 /**
515 * @throws StringIndexOutOfBoundsException {@inheritDoc}
516 * @since 1.2
517 */
518 @Override
519 public synchronized String substring(int start, int end) {
520 return super.substring(start, end);
521 }
522
523 /**
524 * @throws StringIndexOutOfBoundsException {@inheritDoc}
525 * @since 1.2
526 */
527 @Override
528 public synchronized StringBuffer insert(int index, char[] str, int offset,
529 int len)
530 {
531 toStringCache = null;
532 super.insert(index, str, offset, len);
533 return this;
534 }
535
536 /**
537 * @throws StringIndexOutOfBoundsException {@inheritDoc}
538 */
539 @Override
540 public synchronized StringBuffer insert(int offset, Object obj) {
541 toStringCache = null;
542 super.insert(offset, String.valueOf(obj));
543 return this;
544 }
545
546 /**
547 * @throws StringIndexOutOfBoundsException {@inheritDoc}
548 */
549 @Override
550 public synchronized StringBuffer insert(int offset, String str) {
551 toStringCache = null;
552 super.insert(offset, str);
553 return this;
554 }
555
556 /**
557 * @throws StringIndexOutOfBoundsException {@inheritDoc}
558 */
559 @Override
560 public synchronized StringBuffer insert(int offset, char[] str) {
561 toStringCache = null;
562 super.insert(offset, str);
563 return this;
564 }
565
566 /**
567 * @throws IndexOutOfBoundsException {@inheritDoc}
568 * @since 1.5
569 */
570 @Override
571 public StringBuffer insert(int dstOffset, CharSequence s) {
572 // Note, synchronization achieved via invocations of other StringBuffer methods
573 // after narrowing of s to specific type
574 // Ditto for toStringCache clearing
575 super.insert(dstOffset, s);
576 return this;
577 }
578
579 /**
580 * @throws IndexOutOfBoundsException {@inheritDoc}
581 * @since 1.5
582 */
583 @Override
584 public synchronized StringBuffer insert(int dstOffset, CharSequence s,
585 int start, int end)
586 {
587 toStringCache = null;
588 super.insert(dstOffset, s, start, end);
589 return this;
590 }
591
592 /**
593 * @throws StringIndexOutOfBoundsException {@inheritDoc}
594 */
595 @Override
596 public StringBuffer insert(int offset, boolean b) {
597 // Note, synchronization achieved via invocation of StringBuffer insert(int, String)
598 // after conversion of b to String by super class method
599 // Ditto for toStringCache clearing
600 super.insert(offset, b);
601 return this;
602 }
603
604 /**
605 * @throws IndexOutOfBoundsException {@inheritDoc}
606 */
607 @Override
608 public synchronized StringBuffer insert(int offset, char c) {
609 toStringCache = null;
610 super.insert(offset, c);
611 return this;
612 }
613
614 /**
615 * @throws StringIndexOutOfBoundsException {@inheritDoc}
616 */
617 @Override
618 public StringBuffer insert(int offset, int i) {
619 // Note, synchronization achieved via invocation of StringBuffer insert(int, String)
620 // after conversion of i to String by super class method
621 // Ditto for toStringCache clearing
622 super.insert(offset, i);
623 return this;
624 }
625
626 /**
627 * @throws StringIndexOutOfBoundsException {@inheritDoc}
628 */
629 @Override
630 public StringBuffer insert(int offset, long l) {
631 // Note, synchronization achieved via invocation of StringBuffer insert(int, String)
632 // after conversion of l to String by super class method
633 // Ditto for toStringCache clearing
634 super.insert(offset, l);
635 return this;
636 }
637
638 /**
639 * @throws StringIndexOutOfBoundsException {@inheritDoc}
640 */
641 @Override
642 public StringBuffer insert(int offset, float f) {
643 // Note, synchronization achieved via invocation of StringBuffer insert(int, String)
644 // after conversion of f to String by super class method
645 // Ditto for toStringCache clearing
646 super.insert(offset, f);
647 return this;
648 }
649
650 /**
651 * @throws StringIndexOutOfBoundsException {@inheritDoc}
652 */
653 @Override
654 public StringBuffer insert(int offset, double d) {
655 // Note, synchronization achieved via invocation of StringBuffer insert(int, String)
656 // after conversion of d to String by super class method
657 // Ditto for toStringCache clearing
658 super.insert(offset, d);
659 return this;
660 }
661
662 /**
663 * @since 1.4
664 */
665 @Override
666 public int indexOf(String str) {
667 // Note, synchronization achieved via invocations of other StringBuffer methods
668 return super.indexOf(str);
669 }
670
671 /**
672 * @since 1.4
673 */
674 @Override
675 public synchronized int indexOf(String str, int fromIndex) {
676 return super.indexOf(str, fromIndex);
677 }
678
679 /**
680 * @since 1.4
681 */
682 @Override
683 public int lastIndexOf(String str) {
684 // Note, synchronization achieved via invocations of other StringBuffer methods
685 return lastIndexOf(str, count);
686 }
687
688 /**
689 * @since 1.4
690 */
691 @Override
692 public synchronized int lastIndexOf(String str, int fromIndex) {
693 return super.lastIndexOf(str, fromIndex);
694 }
695
696 /**
697 * @since 1.0.2
698 */
699 @Override
700 public synchronized StringBuffer reverse() {
701 toStringCache = null;
702 super.reverse();
703 return this;
704 }
705
706 @Override
707 @HotSpotIntrinsicCandidate
708 public synchronized String toString() {
709 if (toStringCache == null) {
710 return toStringCache =
711 isLatin1() ? StringLatin1.newString(value, 0, count)
712 : StringUTF16.newString(value, 0, count);
713 }
714 return new String(toStringCache);
715 }
716
717 /**
718 * Serializable fields for StringBuffer.
719 *
720 * @serialField value char[]
721 * The backing character array of this StringBuffer.
722 * @serialField count int
723 * The number of characters in this StringBuffer.
724 * @serialField shared boolean
725 * A flag indicating whether the backing array is shared.
726 * The value is ignored upon deserialization.
727 */
728 private static final java.io.ObjectStreamField[] serialPersistentFields =
729 {
730 new java.io.ObjectStreamField("value", char[].class),
731 new java.io.ObjectStreamField("count", Integer.TYPE),
732 new java.io.ObjectStreamField("shared", Boolean.TYPE),
733 };
734
735 /**
736 * readObject is called to restore the state of the StringBuffer from
737 * a stream.
738 */
739 private synchronized void writeObject(java.io.ObjectOutputStream s)
740 throws java.io.IOException {
741 java.io.ObjectOutputStream.PutField fields = s.putFields();
742 char[] val = new char[capacity()];
743 if (isLatin1()) {
744 StringLatin1.getChars(value, 0, count, val, 0);
745 } else {
746 StringUTF16.getChars(value, 0, count, val, 0);
747 }
748 fields.put("value", val);
749 fields.put("count", count);
750 fields.put("shared", false);
751 s.writeFields();
752 }
753
754 /**
755 * readObject is called to restore the state of the StringBuffer from
756 * a stream.
757 */
758 private void readObject(java.io.ObjectInputStream s)
759 throws java.io.IOException, ClassNotFoundException {
760 java.io.ObjectInputStream.GetField fields = s.readFields();
761 char[] val = (char[])fields.get("value", null);
762 initBytes(val, 0, val.length);
763 count = fields.get("count", 0);
764 }
765
766 synchronized void getBytes(byte dst[], int dstBegin, byte coder) {
767 super.getBytes(dst, dstBegin, coder);
768 }
769 }