1 /*
2 * Copyright (c) 1994, 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 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.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 * <p>
161 * If the length of the specified {@code CharSequence} is
162 * less than or equal to zero, then an empty buffer of capacity
163 * {@code 16} is returned.
164 *
165 * @param seq the sequence to copy.
166 * @since 1.5
167 */
168 public StringBuffer(CharSequence seq) {
169 this(seq.length() + 16);
170 append(seq);
171 }
172
173 /**
174 * Compares two {@code StringBuffer} instances lexicographically. This method
175 * follows the same rules for lexicographical comparison as defined in the
176 * {@linkplain java.lang.CharSequence#compare(java.lang.CharSequence,
177 * java.lang.CharSequence) CharSequence.compare(this, another)} method.
178 *
179 * <p>
180 * For finer-grained, locale-sensitive String comparison, refer to
181 * {@link java.text.Collator}.
182 *
183 * @implNote
184 * This method synchronizes on {@code this}, the current object, but not
185 * {@code StringBuffer another} with which {@code this StringBuffer} is compared.
186 *
187 * @param another the {@code StringBuffer} to be compared with
188 *
189 * @return the value {@code 0} if this {@code StringBuffer} contains the same
190 * character sequence as that of the argument {@code StringBuffer}; a negative integer
191 * if this {@code StringBuffer} is lexicographically less than the
192 * {@code StringBuffer} argument; or a positive integer if this {@code StringBuffer}
193 * is lexicographically greater than the {@code StringBuffer} argument.
194 *
195 * @since 11
196 */
197 @Override
198 public synchronized int compareTo(StringBuffer another) {
199 return super.compareTo(another);
200 }
201
202 @Override
203 public synchronized int length() {
204 return count;
205 }
206
207 @Override
208 public synchronized int capacity() {
209 return super.capacity();
210 }
211
212
213 @Override
214 public synchronized void ensureCapacity(int minimumCapacity) {
215 super.ensureCapacity(minimumCapacity);
216 }
217
218 /**
219 * @since 1.5
220 */
221 @Override
222 public synchronized void trimToSize() {
223 super.trimToSize();
224 }
225
226 /**
227 * @throws IndexOutOfBoundsException {@inheritDoc}
228 * @see #length()
229 */
230 @Override
231 public synchronized void setLength(int newLength) {
232 toStringCache = null;
233 super.setLength(newLength);
234 }
235
236 /**
237 * @throws IndexOutOfBoundsException {@inheritDoc}
238 * @see #length()
239 */
240 @Override
241 public synchronized char charAt(int index) {
242 return super.charAt(index);
243 }
244
245 /**
246 * @throws IndexOutOfBoundsException {@inheritDoc}
247 * @since 1.5
248 */
249 @Override
250 public synchronized int codePointAt(int index) {
251 return super.codePointAt(index);
252 }
253
254 /**
255 * @throws IndexOutOfBoundsException {@inheritDoc}
256 * @since 1.5
257 */
258 @Override
259 public synchronized int codePointBefore(int index) {
260 return super.codePointBefore(index);
261 }
262
263 /**
264 * @throws IndexOutOfBoundsException {@inheritDoc}
265 * @since 1.5
266 */
267 @Override
268 public synchronized int codePointCount(int beginIndex, int endIndex) {
269 return super.codePointCount(beginIndex, endIndex);
270 }
271
272 /**
273 * @throws IndexOutOfBoundsException {@inheritDoc}
274 * @since 1.5
275 */
276 @Override
277 public synchronized int offsetByCodePoints(int index, int codePointOffset) {
278 return super.offsetByCodePoints(index, codePointOffset);
279 }
280
281 /**
282 * @throws IndexOutOfBoundsException {@inheritDoc}
283 */
284 @Override
285 public synchronized void getChars(int srcBegin, int srcEnd, char[] dst,
286 int dstBegin)
287 {
288 super.getChars(srcBegin, srcEnd, dst, dstBegin);
289 }
290
291 /**
292 * @throws IndexOutOfBoundsException {@inheritDoc}
293 * @see #length()
294 */
295 @Override
296 public synchronized void setCharAt(int index, char ch) {
297 toStringCache = null;
298 super.setCharAt(index, ch);
299 }
300
301 @Override
302 public synchronized StringBuffer append(Object obj) {
303 toStringCache = null;
304 super.append(String.valueOf(obj));
305 return this;
306 }
307
308 @Override
309 @HotSpotIntrinsicCandidate
310 public synchronized StringBuffer append(String str) {
311 toStringCache = null;
312 super.append(str);
313 return this;
314 }
315
316 /**
317 * Appends the specified {@code StringBuffer} to this sequence.
318 * <p>
319 * The characters of the {@code StringBuffer} argument are appended,
320 * in order, to the contents of this {@code StringBuffer}, increasing the
321 * length of this {@code StringBuffer} by the length of the argument.
322 * If {@code sb} is {@code null}, then the four characters
323 * {@code "null"} are appended to this {@code StringBuffer}.
324 * <p>
325 * Let <i>n</i> be the length of the old character sequence, the one
326 * contained in the {@code StringBuffer} just prior to execution of the
327 * {@code append} method. Then the character at index <i>k</i> in
328 * the new character sequence is equal to the character at index <i>k</i>
329 * in the old character sequence, if <i>k</i> is less than <i>n</i>;
330 * otherwise, it is equal to the character at index <i>k-n</i> in the
331 * argument {@code sb}.
332 * <p>
333 * This method synchronizes on {@code this}, the destination
334 * object, but does not synchronize on the source ({@code sb}).
335 *
336 * @param sb the {@code StringBuffer} to append.
337 * @return a reference to this object.
338 * @since 1.4
339 */
340 public synchronized StringBuffer append(StringBuffer sb) {
341 toStringCache = null;
342 super.append(sb);
343 return this;
344 }
345
346 /**
347 * @since 1.8
348 */
349 @Override
350 synchronized StringBuffer append(AbstractStringBuilder asb) {
351 toStringCache = null;
352 super.append(asb);
353 return this;
354 }
355
356 /**
357 * Appends the specified {@code CharSequence} to this
358 * sequence.
359 * <p>
360 * The characters of the {@code CharSequence} argument are appended,
361 * in order, increasing the length of this sequence by the length of the
362 * argument.
363 *
364 * <p>The result of this method is exactly the same as if it were an
365 * invocation of this.append(s, 0, s.length());
366 *
367 * <p>This method synchronizes on {@code this}, the destination
368 * object, but does not synchronize on the source ({@code s}).
369 *
370 * <p>If {@code s} is {@code null}, then the four characters
371 * {@code "null"} are appended.
372 *
373 * @param s the {@code CharSequence} to append.
374 * @return a reference to this object.
375 * @since 1.5
376 */
377 @Override
378 public synchronized StringBuffer append(CharSequence s) {
379 toStringCache = null;
380 super.append(s);
381 return this;
382 }
383
384 /**
385 * @throws IndexOutOfBoundsException {@inheritDoc}
386 * @since 1.5
387 */
388 @Override
389 public synchronized StringBuffer append(CharSequence s, int start, int end)
390 {
391 toStringCache = null;
392 super.append(s, start, end);
393 return this;
394 }
395
396 @Override
397 public synchronized StringBuffer append(char[] str) {
398 toStringCache = null;
399 super.append(str);
400 return this;
401 }
402
403 /**
404 * @throws IndexOutOfBoundsException {@inheritDoc}
405 */
406 @Override
407 public synchronized StringBuffer append(char[] str, int offset, int len) {
408 toStringCache = null;
409 super.append(str, offset, len);
410 return this;
411 }
412
413 @Override
414 public synchronized StringBuffer append(boolean b) {
415 toStringCache = null;
416 super.append(b);
417 return this;
418 }
419
420 @Override
421 @HotSpotIntrinsicCandidate
422 public synchronized StringBuffer append(char c) {
423 toStringCache = null;
424 super.append(c);
425 return this;
426 }
427
428 @Override
429 @HotSpotIntrinsicCandidate
430 public synchronized StringBuffer append(int i) {
431 toStringCache = null;
432 super.append(i);
433 return this;
434 }
435
436 /**
437 * @since 1.5
438 */
439 @Override
440 public synchronized StringBuffer appendCodePoint(int codePoint) {
441 toStringCache = null;
442 super.appendCodePoint(codePoint);
443 return this;
444 }
445
446 @Override
447 public synchronized StringBuffer append(long lng) {
448 toStringCache = null;
449 super.append(lng);
450 return this;
451 }
452
453 @Override
454 public synchronized StringBuffer append(float f) {
455 toStringCache = null;
456 super.append(f);
457 return this;
458 }
459
460 @Override
461 public synchronized StringBuffer append(double d) {
462 toStringCache = null;
463 super.append(d);
464 return this;
465 }
466
467 /**
468 * @throws StringIndexOutOfBoundsException {@inheritDoc}
469 * @since 1.2
470 */
471 @Override
472 public synchronized StringBuffer delete(int start, int end) {
473 toStringCache = null;
474 super.delete(start, end);
475 return this;
476 }
477
478 /**
479 * @throws StringIndexOutOfBoundsException {@inheritDoc}
480 * @since 1.2
481 */
482 @Override
483 public synchronized StringBuffer deleteCharAt(int index) {
484 toStringCache = null;
485 super.deleteCharAt(index);
486 return this;
487 }
488
489 /**
490 * @throws StringIndexOutOfBoundsException {@inheritDoc}
491 * @since 1.2
492 */
493 @Override
494 public synchronized StringBuffer replace(int start, int end, String str) {
495 toStringCache = null;
496 super.replace(start, end, str);
497 return this;
498 }
499
500 /**
501 * @throws StringIndexOutOfBoundsException {@inheritDoc}
502 * @since 1.2
503 */
504 @Override
505 public synchronized String substring(int start) {
506 return substring(start, count);
507 }
508
509 /**
510 * @throws IndexOutOfBoundsException {@inheritDoc}
511 * @since 1.4
512 */
513 @Override
514 public synchronized CharSequence subSequence(int start, int end) {
515 return super.substring(start, end);
516 }
517
518 /**
519 * @throws StringIndexOutOfBoundsException {@inheritDoc}
520 * @since 1.2
521 */
522 @Override
523 public synchronized String substring(int start, int end) {
524 return super.substring(start, end);
525 }
526
527 /**
528 * @throws StringIndexOutOfBoundsException {@inheritDoc}
529 * @since 1.2
530 */
531 @Override
532 public synchronized StringBuffer insert(int index, char[] str, int offset,
533 int len)
534 {
535 toStringCache = null;
536 super.insert(index, str, offset, len);
537 return this;
538 }
539
540 /**
541 * @throws StringIndexOutOfBoundsException {@inheritDoc}
542 */
543 @Override
544 public synchronized StringBuffer insert(int offset, Object obj) {
545 toStringCache = null;
546 super.insert(offset, String.valueOf(obj));
547 return this;
548 }
549
550 /**
551 * @throws StringIndexOutOfBoundsException {@inheritDoc}
552 */
553 @Override
554 public synchronized StringBuffer insert(int offset, String str) {
555 toStringCache = null;
556 super.insert(offset, str);
557 return this;
558 }
559
560 /**
561 * @throws StringIndexOutOfBoundsException {@inheritDoc}
562 */
563 @Override
564 public synchronized StringBuffer insert(int offset, char[] str) {
565 toStringCache = null;
566 super.insert(offset, str);
567 return this;
568 }
569
570 /**
571 * @throws IndexOutOfBoundsException {@inheritDoc}
572 * @since 1.5
573 */
574 @Override
575 public StringBuffer insert(int dstOffset, CharSequence s) {
576 // Note, synchronization achieved via invocations of other StringBuffer methods
577 // after narrowing of s to specific type
578 // Ditto for toStringCache clearing
579 super.insert(dstOffset, s);
580 return this;
581 }
582
583 /**
584 * @throws IndexOutOfBoundsException {@inheritDoc}
585 * @since 1.5
586 */
587 @Override
588 public synchronized StringBuffer insert(int dstOffset, CharSequence s,
589 int start, int end)
590 {
591 toStringCache = null;
592 super.insert(dstOffset, s, start, end);
593 return this;
594 }
595
596 /**
597 * @throws StringIndexOutOfBoundsException {@inheritDoc}
598 */
599 @Override
600 public StringBuffer insert(int offset, boolean b) {
601 // Note, synchronization achieved via invocation of StringBuffer insert(int, String)
602 // after conversion of b to String by super class method
603 // Ditto for toStringCache clearing
604 super.insert(offset, b);
605 return this;
606 }
607
608 /**
609 * @throws IndexOutOfBoundsException {@inheritDoc}
610 */
611 @Override
612 public synchronized StringBuffer insert(int offset, char c) {
613 toStringCache = null;
614 super.insert(offset, c);
615 return this;
616 }
617
618 /**
619 * @throws StringIndexOutOfBoundsException {@inheritDoc}
620 */
621 @Override
622 public StringBuffer insert(int offset, int i) {
623 // Note, synchronization achieved via invocation of StringBuffer insert(int, String)
624 // after conversion of i to String by super class method
625 // Ditto for toStringCache clearing
626 super.insert(offset, i);
627 return this;
628 }
629
630 /**
631 * @throws StringIndexOutOfBoundsException {@inheritDoc}
632 */
633 @Override
634 public StringBuffer insert(int offset, long l) {
635 // Note, synchronization achieved via invocation of StringBuffer insert(int, String)
636 // after conversion of l to String by super class method
637 // Ditto for toStringCache clearing
638 super.insert(offset, l);
639 return this;
640 }
641
642 /**
643 * @throws StringIndexOutOfBoundsException {@inheritDoc}
644 */
645 @Override
646 public StringBuffer insert(int offset, float f) {
647 // Note, synchronization achieved via invocation of StringBuffer insert(int, String)
648 // after conversion of f to String by super class method
649 // Ditto for toStringCache clearing
650 super.insert(offset, f);
651 return this;
652 }
653
654 /**
655 * @throws StringIndexOutOfBoundsException {@inheritDoc}
656 */
657 @Override
658 public StringBuffer insert(int offset, double d) {
659 // Note, synchronization achieved via invocation of StringBuffer insert(int, String)
660 // after conversion of d to String by super class method
661 // Ditto for toStringCache clearing
662 super.insert(offset, d);
663 return this;
664 }
665
666 /**
667 * @since 1.4
668 */
669 @Override
670 public int indexOf(String str) {
671 // Note, synchronization achieved via invocations of other StringBuffer methods
672 return super.indexOf(str);
673 }
674
675 /**
676 * @since 1.4
677 */
678 @Override
679 public synchronized int indexOf(String str, int fromIndex) {
680 return super.indexOf(str, fromIndex);
681 }
682
683 /**
684 * @since 1.4
685 */
686 @Override
687 public int lastIndexOf(String str) {
688 // Note, synchronization achieved via invocations of other StringBuffer methods
689 return lastIndexOf(str, count);
690 }
691
692 /**
693 * @since 1.4
694 */
695 @Override
696 public synchronized int lastIndexOf(String str, int fromIndex) {
697 return super.lastIndexOf(str, fromIndex);
698 }
699
700 /**
701 * @since 1.0.2
702 */
703 @Override
704 public synchronized StringBuffer reverse() {
705 toStringCache = null;
706 super.reverse();
707 return this;
708 }
709
710 @Override
711 @HotSpotIntrinsicCandidate
712 public synchronized String toString() {
713 if (toStringCache == null) {
714 return toStringCache =
715 isLatin1() ? StringLatin1.newString(value, 0, count)
716 : StringUTF16.newString(value, 0, count);
717 }
718 return new String(toStringCache);
719 }
720
721 /**
722 * Serializable fields for StringBuffer.
723 *
724 * @serialField value char[]
725 * The backing character array of this StringBuffer.
726 * @serialField count int
727 * The number of characters in this StringBuffer.
728 * @serialField shared boolean
729 * A flag indicating whether the backing array is shared.
730 * The value is ignored upon deserialization.
731 */
732 private static final java.io.ObjectStreamField[] serialPersistentFields =
733 {
734 new java.io.ObjectStreamField("value", char[].class),
735 new java.io.ObjectStreamField("count", Integer.TYPE),
736 new java.io.ObjectStreamField("shared", Boolean.TYPE),
737 };
738
739 /**
740 * readObject is called to restore the state of the StringBuffer from
741 * a stream.
742 */
743 private synchronized void writeObject(java.io.ObjectOutputStream s)
744 throws java.io.IOException {
745 java.io.ObjectOutputStream.PutField fields = s.putFields();
746 char[] val = new char[capacity()];
747 if (isLatin1()) {
748 StringLatin1.getChars(value, 0, count, val, 0);
749 } else {
750 StringUTF16.getChars(value, 0, count, val, 0);
751 }
752 fields.put("value", val);
753 fields.put("count", count);
754 fields.put("shared", false);
755 s.writeFields();
756 }
757
758 /**
759 * readObject is called to restore the state of the StringBuffer from
760 * a stream.
761 */
762 private void readObject(java.io.ObjectInputStream s)
763 throws java.io.IOException, ClassNotFoundException {
764 java.io.ObjectInputStream.GetField fields = s.readFields();
765 char[] val = (char[])fields.get("value", null);
766 initBytes(val, 0, val.length);
767 count = fields.get("count", 0);
768 }
769
770 synchronized void getBytes(byte dst[], int dstBegin, byte coder) {
771 super.getBytes(dst, dstBegin, coder);
772 }
773 }
774