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
30 /**
31 * A thread-safe, mutable sequence of characters.
32 * A string buffer is like a {@link String}, but can be modified. At any
33 * point in time it contains some particular sequence of characters, but
34 * the length and content of the sequence can be changed through certain
35 * method calls.
36 * <p>
37 * String buffers are safe for use by multiple threads. The methods
38 * are synchronized where necessary so that all the operations on any
39 * particular instance behave as if they occur in some serial order
40 * that is consistent with the order of the method calls made by each of
41 * the individual threads involved.
42 * <p>
43 * The principal operations on a {@code StringBuffer} are the
44 * {@code append} and {@code insert} methods, which are
45 * overloaded so as to accept data of any type. Each effectively
46 * converts a given datum to a string and then appends or inserts the
47 * characters of that string to the string buffer. The
48 * {@code append} method always adds these characters at the end
95 * @since 1.0
96 */
97 public final class StringBuffer
98 extends AbstractStringBuilder
99 implements java.io.Serializable, CharSequence
100 {
101
102 /**
103 * A cache of the last value returned by toString. Cleared
104 * whenever the StringBuffer is modified.
105 */
106 private transient char[] toStringCache;
107
108 /** use serialVersionUID from JDK 1.0.2 for interoperability */
109 static final long serialVersionUID = 3388685877147921107L;
110
111 /**
112 * Constructs a string buffer with no characters in it and an
113 * initial capacity of 16 characters.
114 */
115 public StringBuffer() {
116 super(16);
117 }
118
119 /**
120 * Constructs a string buffer with no characters in it and
121 * the specified initial capacity.
122 *
123 * @param capacity the initial capacity.
124 * @exception NegativeArraySizeException if the {@code capacity}
125 * argument is less than {@code 0}.
126 */
127 public StringBuffer(int capacity) {
128 super(capacity);
129 }
130
131 /**
132 * Constructs a string buffer initialized to the contents of the
133 * specified string. The initial capacity of the string buffer is
134 * {@code 16} plus the length of the string argument.
135 *
136 * @param str the initial contents of the buffer.
137 */
138 public StringBuffer(String str) {
139 super(str.length() + 16);
140 append(str);
141 }
142
143 /**
144 * Constructs a string buffer that contains the same characters
145 * as the specified {@code CharSequence}. The initial capacity of
146 * the string buffer is {@code 16} plus the length of the
147 * {@code CharSequence} argument.
148 * <p>
149 * If the length of the specified {@code CharSequence} is
150 * less than or equal to zero, then an empty buffer of capacity
151 * {@code 16} is returned.
152 *
153 * @param seq the sequence to copy.
154 * @since 1.5
155 */
156 public StringBuffer(CharSequence seq) {
157 this(seq.length() + 16);
254 /**
255 * @throws IndexOutOfBoundsException {@inheritDoc}
256 * @see #length()
257 */
258 @Override
259 public synchronized void setCharAt(int index, char ch) {
260 if ((index < 0) || (index >= count))
261 throw new StringIndexOutOfBoundsException(index);
262 toStringCache = null;
263 value[index] = ch;
264 }
265
266 @Override
267 public synchronized StringBuffer append(Object obj) {
268 toStringCache = null;
269 super.append(String.valueOf(obj));
270 return this;
271 }
272
273 @Override
274 public synchronized StringBuffer append(String str) {
275 toStringCache = null;
276 super.append(str);
277 return this;
278 }
279
280 /**
281 * Appends the specified {@code StringBuffer} to this sequence.
282 * <p>
283 * The characters of the {@code StringBuffer} argument are appended,
284 * in order, to the contents of this {@code StringBuffer}, increasing the
285 * length of this {@code StringBuffer} by the length of the argument.
286 * If {@code sb} is {@code null}, then the four characters
287 * {@code "null"} are appended to this {@code StringBuffer}.
288 * <p>
289 * Let <i>n</i> be the length of the old character sequence, the one
290 * contained in the {@code StringBuffer} just prior to execution of the
291 * {@code append} method. Then the character at index <i>k</i> in
292 * the new character sequence is equal to the character at index <i>k</i>
293 * in the old character sequence, if <i>k</i> is less than <i>n</i>;
365 }
366
367 /**
368 * @throws IndexOutOfBoundsException {@inheritDoc}
369 */
370 @Override
371 public synchronized StringBuffer append(char[] str, int offset, int len) {
372 toStringCache = null;
373 super.append(str, offset, len);
374 return this;
375 }
376
377 @Override
378 public synchronized StringBuffer append(boolean b) {
379 toStringCache = null;
380 super.append(b);
381 return this;
382 }
383
384 @Override
385 public synchronized StringBuffer append(char c) {
386 toStringCache = null;
387 super.append(c);
388 return this;
389 }
390
391 @Override
392 public synchronized StringBuffer append(int i) {
393 toStringCache = null;
394 super.append(i);
395 return this;
396 }
397
398 /**
399 * @since 1.5
400 */
401 @Override
402 public synchronized StringBuffer appendCodePoint(int codePoint) {
403 toStringCache = null;
404 super.appendCodePoint(codePoint);
405 return this;
406 }
407
408 @Override
409 public synchronized StringBuffer append(long lng) {
410 toStringCache = null;
411 super.append(lng);
653
654 /**
655 * @since 1.4
656 */
657 @Override
658 public synchronized int lastIndexOf(String str, int fromIndex) {
659 return super.lastIndexOf(str, fromIndex);
660 }
661
662 /**
663 * @since 1.0.2
664 */
665 @Override
666 public synchronized StringBuffer reverse() {
667 toStringCache = null;
668 super.reverse();
669 return this;
670 }
671
672 @Override
673 public synchronized String toString() {
674 if (toStringCache == null) {
675 toStringCache = Arrays.copyOfRange(value, 0, count);
676 }
677 return new String(toStringCache, true);
678 }
679
680 /**
681 * Serializable fields for StringBuffer.
682 *
683 * @serialField value char[]
684 * The backing character array of this StringBuffer.
685 * @serialField count int
686 * The number of characters in this StringBuffer.
687 * @serialField shared boolean
688 * A flag indicating whether the backing array is shared.
689 * The value is ignored upon deserialization.
690 */
691 private static final java.io.ObjectStreamField[] serialPersistentFields =
692 {
|
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
96 * @since 1.0
97 */
98 public final class StringBuffer
99 extends AbstractStringBuilder
100 implements java.io.Serializable, CharSequence
101 {
102
103 /**
104 * A cache of the last value returned by toString. Cleared
105 * whenever the StringBuffer is modified.
106 */
107 private transient char[] toStringCache;
108
109 /** use serialVersionUID from JDK 1.0.2 for interoperability */
110 static final long serialVersionUID = 3388685877147921107L;
111
112 /**
113 * Constructs a string buffer with no characters in it and an
114 * initial capacity of 16 characters.
115 */
116 @HotSpotIntrinsicCandidate
117 public StringBuffer() {
118 super(16);
119 }
120
121 /**
122 * Constructs a string buffer with no characters in it and
123 * the specified initial capacity.
124 *
125 * @param capacity the initial capacity.
126 * @exception NegativeArraySizeException if the {@code capacity}
127 * argument is less than {@code 0}.
128 */
129 @HotSpotIntrinsicCandidate
130 public StringBuffer(int capacity) {
131 super(capacity);
132 }
133
134 /**
135 * Constructs a string buffer initialized to the contents of the
136 * specified string. The initial capacity of the string buffer is
137 * {@code 16} plus the length of the string argument.
138 *
139 * @param str the initial contents of the buffer.
140 */
141 @HotSpotIntrinsicCandidate
142 public StringBuffer(String str) {
143 super(str.length() + 16);
144 append(str);
145 }
146
147 /**
148 * Constructs a string buffer that contains the same characters
149 * as the specified {@code CharSequence}. The initial capacity of
150 * the string buffer is {@code 16} plus the length of the
151 * {@code CharSequence} argument.
152 * <p>
153 * If the length of the specified {@code CharSequence} is
154 * less than or equal to zero, then an empty buffer of capacity
155 * {@code 16} is returned.
156 *
157 * @param seq the sequence to copy.
158 * @since 1.5
159 */
160 public StringBuffer(CharSequence seq) {
161 this(seq.length() + 16);
258 /**
259 * @throws IndexOutOfBoundsException {@inheritDoc}
260 * @see #length()
261 */
262 @Override
263 public synchronized void setCharAt(int index, char ch) {
264 if ((index < 0) || (index >= count))
265 throw new StringIndexOutOfBoundsException(index);
266 toStringCache = null;
267 value[index] = ch;
268 }
269
270 @Override
271 public synchronized StringBuffer append(Object obj) {
272 toStringCache = null;
273 super.append(String.valueOf(obj));
274 return this;
275 }
276
277 @Override
278 @HotSpotIntrinsicCandidate
279 public synchronized StringBuffer append(String str) {
280 toStringCache = null;
281 super.append(str);
282 return this;
283 }
284
285 /**
286 * Appends the specified {@code StringBuffer} to this sequence.
287 * <p>
288 * The characters of the {@code StringBuffer} argument are appended,
289 * in order, to the contents of this {@code StringBuffer}, increasing the
290 * length of this {@code StringBuffer} by the length of the argument.
291 * If {@code sb} is {@code null}, then the four characters
292 * {@code "null"} are appended to this {@code StringBuffer}.
293 * <p>
294 * Let <i>n</i> be the length of the old character sequence, the one
295 * contained in the {@code StringBuffer} just prior to execution of the
296 * {@code append} method. Then the character at index <i>k</i> in
297 * the new character sequence is equal to the character at index <i>k</i>
298 * in the old character sequence, if <i>k</i> is less than <i>n</i>;
370 }
371
372 /**
373 * @throws IndexOutOfBoundsException {@inheritDoc}
374 */
375 @Override
376 public synchronized StringBuffer append(char[] str, int offset, int len) {
377 toStringCache = null;
378 super.append(str, offset, len);
379 return this;
380 }
381
382 @Override
383 public synchronized StringBuffer append(boolean b) {
384 toStringCache = null;
385 super.append(b);
386 return this;
387 }
388
389 @Override
390 @HotSpotIntrinsicCandidate
391 public synchronized StringBuffer append(char c) {
392 toStringCache = null;
393 super.append(c);
394 return this;
395 }
396
397 @Override
398 @HotSpotIntrinsicCandidate
399 public synchronized StringBuffer append(int i) {
400 toStringCache = null;
401 super.append(i);
402 return this;
403 }
404
405 /**
406 * @since 1.5
407 */
408 @Override
409 public synchronized StringBuffer appendCodePoint(int codePoint) {
410 toStringCache = null;
411 super.appendCodePoint(codePoint);
412 return this;
413 }
414
415 @Override
416 public synchronized StringBuffer append(long lng) {
417 toStringCache = null;
418 super.append(lng);
660
661 /**
662 * @since 1.4
663 */
664 @Override
665 public synchronized int lastIndexOf(String str, int fromIndex) {
666 return super.lastIndexOf(str, fromIndex);
667 }
668
669 /**
670 * @since 1.0.2
671 */
672 @Override
673 public synchronized StringBuffer reverse() {
674 toStringCache = null;
675 super.reverse();
676 return this;
677 }
678
679 @Override
680 @HotSpotIntrinsicCandidate
681 public synchronized String toString() {
682 if (toStringCache == null) {
683 toStringCache = Arrays.copyOfRange(value, 0, count);
684 }
685 return new String(toStringCache, true);
686 }
687
688 /**
689 * Serializable fields for StringBuffer.
690 *
691 * @serialField value char[]
692 * The backing character array of this StringBuffer.
693 * @serialField count int
694 * The number of characters in this StringBuffer.
695 * @serialField shared boolean
696 * A flag indicating whether the backing array is shared.
697 * The value is ignored upon deserialization.
698 */
699 private static final java.io.ObjectStreamField[] serialPersistentFields =
700 {
|