1 /*
2 * Copyright (c) 2003, 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 jdk.internal.HotSpotIntrinsicCandidate;
29
30 /**
31 * A mutable sequence of characters. This class provides an API compatible
32 * with {@code StringBuffer}, but with no guarantee of synchronization.
33 * This class is designed for use as a drop-in replacement for
34 * {@code StringBuffer} in places where the string buffer was being
35 * used by a single thread (as is generally the case). Where possible,
36 * it is recommended that this class be used in preference to
37 * {@code StringBuffer} as it will be faster under most implementations.
38 *
39 * <p>The principal operations on a {@code StringBuilder} are the
40 * {@code append} and {@code insert} methods, which are
41 * overloaded so as to accept data of any type. Each effectively
42 * converts a given datum to a string and then appends or inserts the
43 * characters of that string to the string builder. The
44 * {@code append} method always adds these characters at the end
45 * of the builder; the {@code insert} method adds the characters at
46 * a specified point.
47 * <p>
48 * For example, if {@code z} refers to a string builder object
49 * whose current contents are "{@code start}", then
50 * the method call {@code z.append("le")} would cause the string
51 * builder to contain "{@code startle}", whereas
52 * {@code z.insert(4, "le")} would alter the string builder to
53 * contain "{@code starlet}".
54 * <p>
55 * In general, if sb refers to an instance of a {@code StringBuilder},
56 * then {@code sb.append(x)} has the same effect as
57 * {@code sb.insert(sb.length(), x)}.
58 * <p>
59 * Every string builder has a capacity. As long as the length of the
60 * character sequence contained in the string builder does not exceed
61 * the capacity, it is not necessary to allocate a new internal
62 * buffer. If the internal buffer overflows, it is automatically made larger.
63 *
64 * <p>Instances of {@code StringBuilder} are not safe for
65 * use by multiple threads. If such synchronization is required then it is
66 * recommended that {@link java.lang.StringBuffer} be used.
67 *
68 * <p>Unless otherwise noted, passing a {@code null} argument to a constructor
69 * or method in this class will cause a {@link NullPointerException} to be
70 * thrown.
71 *
72 * @apiNote
73 * {@code StringBuilder} implements {@code Comparable} but does not override
74 * {@link Object#equals equals}. Thus, the natural ordering of {@code StringBuilder}
75 * is inconsistent with equals. Care should be exercised if {@code StringBuilder}
76 * objects are used as keys in a {@code SortedMap} or elements in a {@code SortedSet}.
77 * See {@link Comparable}, {@link java.util.SortedMap SortedMap}, or
78 * {@link java.util.SortedSet SortedSet} for more information.
79 *
80 * @author Michael McCloskey
81 * @see java.lang.StringBuffer
82 * @see java.lang.String
83 * @since 1.5
84 */
85 public final class StringBuilder
86 extends AbstractStringBuilder
87 implements java.io.Serializable, Comparable<StringBuilder>, CharSequence
88 {
89
90 /** use serialVersionUID for interoperability */
91 static final long serialVersionUID = 4383685877147921099L;
92
93 /**
94 * Constructs a string builder with no characters in it and an
95 * initial capacity of 16 characters.
96 */
97 @HotSpotIntrinsicCandidate
98 public StringBuilder() {
99 super(16);
100 }
101
102 /**
103 * Constructs a string builder with no characters in it and an
104 * initial capacity specified by the {@code capacity} argument.
105 *
106 * @param capacity the initial capacity.
107 * @throws NegativeArraySizeException if the {@code capacity}
108 * argument is less than {@code 0}.
109 */
110 @HotSpotIntrinsicCandidate
111 public StringBuilder(int capacity) {
112 super(capacity);
113 }
114
115 /**
116 * Constructs a string builder initialized to the contents of the
117 * specified string. The initial capacity of the string builder is
118 * {@code 16} plus the length of the string argument.
119 *
120 * @param str the initial contents of the buffer.
121 */
122 @HotSpotIntrinsicCandidate
123 public StringBuilder(String str) {
124 super(str);
125 }
126
127 /**
128 * Constructs a string builder that contains the same characters
129 * as the specified {@code CharSequence}. The initial capacity of
130 * the string builder is {@code 16} plus the length of the
131 * {@code CharSequence} argument.
132 *
133 * @param seq the sequence to copy.
134 */
135 public StringBuilder(CharSequence seq) {
136 super(seq);
137 }
138
139 /**
140 * Compares two {@code StringBuilder} instances lexicographically. This method
141 * follows the same rules for lexicographical comparison as defined in the
142 * {@linkplain java.lang.CharSequence#compare(java.lang.CharSequence,
143 * java.lang.CharSequence) CharSequence.compare(this, another)} method.
144 *
145 * <p>
146 * For finer-grained, locale-sensitive String comparison, refer to
147 * {@link java.text.Collator}.
148 *
149 * @param another the {@code StringBuilder} to be compared with
150 *
151 * @return the value {@code 0} if this {@code StringBuilder} contains the same
152 * character sequence as that of the argument {@code StringBuilder}; a negative integer
153 * if this {@code StringBuilder} is lexicographically less than the
154 * {@code StringBuilder} argument; or a positive integer if this {@code StringBuilder}
155 * is lexicographically greater than the {@code StringBuilder} argument.
156 *
157 * @since 11
158 */
159 @Override
160 public int compareTo(StringBuilder another) {
161 return super.compareTo(another);
162 }
163
164 @Override
165 public StringBuilder append(Object obj) {
166 return append(String.valueOf(obj));
167 }
168
169 @Override
170 @HotSpotIntrinsicCandidate
171 public StringBuilder append(String str) {
172 super.append(str);
173 return this;
174 }
175
176 /**
177 * Appends the specified {@code StringBuffer} to this sequence.
178 * <p>
179 * The characters of the {@code StringBuffer} argument are appended,
180 * in order, to this sequence, increasing the
181 * length of this sequence by the length of the argument.
182 * If {@code sb} is {@code null}, then the four characters
183 * {@code "null"} are appended to this sequence.
184 * <p>
185 * Let <i>n</i> be the length of this character sequence just prior to
186 * execution of the {@code append} method. Then the character at index
187 * <i>k</i> in the new character sequence is equal to the character at
188 * index <i>k</i> in the old character sequence, if <i>k</i> is less than
189 * <i>n</i>; otherwise, it is equal to the character at index <i>k-n</i>
190 * in the argument {@code sb}.
191 *
192 * @param sb the {@code StringBuffer} to append.
193 * @return a reference to this object.
194 */
195 public StringBuilder append(StringBuffer sb) {
196 super.append(sb);
197 return this;
198 }
199
200 @Override
201 public StringBuilder append(CharSequence s) {
202 super.append(s);
203 return this;
204 }
205
206 /**
207 * @throws IndexOutOfBoundsException {@inheritDoc}
208 */
209 @Override
210 public StringBuilder append(CharSequence s, int start, int end) {
211 super.append(s, start, end);
212 return this;
213 }
214
215 @Override
216 public StringBuilder append(char[] str) {
217 super.append(str);
218 return this;
219 }
220
221 /**
222 * @throws IndexOutOfBoundsException {@inheritDoc}
223 */
224 @Override
225 public StringBuilder append(char[] str, int offset, int len) {
226 super.append(str, offset, len);
227 return this;
228 }
229
230 @Override
231 public StringBuilder append(boolean b) {
232 super.append(b);
233 return this;
234 }
235
236 @Override
237 @HotSpotIntrinsicCandidate
238 public StringBuilder append(char c) {
239 super.append(c);
240 return this;
241 }
242
243 @Override
244 @HotSpotIntrinsicCandidate
245 public StringBuilder append(int i) {
246 super.append(i);
247 return this;
248 }
249
250 @Override
251 public StringBuilder append(long lng) {
252 super.append(lng);
253 return this;
254 }
255
256 @Override
257 public StringBuilder append(float f) {
258 super.append(f);
259 return this;
260 }
261
262 @Override
263 public StringBuilder append(double d) {
264 super.append(d);
265 return this;
266 }
267
268 /**
269 * @since 1.5
270 */
271 @Override
272 public StringBuilder appendCodePoint(int codePoint) {
273 super.appendCodePoint(codePoint);
274 return this;
275 }
276
277 /**
278 * @throws StringIndexOutOfBoundsException {@inheritDoc}
279 */
280 @Override
281 public StringBuilder delete(int start, int end) {
282 super.delete(start, end);
283 return this;
284 }
285
286 /**
287 * @throws StringIndexOutOfBoundsException {@inheritDoc}
288 */
289 @Override
290 public StringBuilder deleteCharAt(int index) {
291 super.deleteCharAt(index);
292 return this;
293 }
294
295 /**
296 * @throws StringIndexOutOfBoundsException {@inheritDoc}
297 */
298 @Override
299 public StringBuilder replace(int start, int end, String str) {
300 super.replace(start, end, str);
301 return this;
302 }
303
304 /**
305 * @throws StringIndexOutOfBoundsException {@inheritDoc}
306 */
307 @Override
308 public StringBuilder insert(int index, char[] str, int offset,
309 int len)
310 {
311 super.insert(index, str, offset, len);
312 return this;
313 }
314
315 /**
316 * @throws StringIndexOutOfBoundsException {@inheritDoc}
317 */
318 @Override
319 public StringBuilder insert(int offset, Object obj) {
320 super.insert(offset, obj);
321 return this;
322 }
323
324 /**
325 * @throws StringIndexOutOfBoundsException {@inheritDoc}
326 */
327 @Override
328 public StringBuilder insert(int offset, String str) {
329 super.insert(offset, str);
330 return this;
331 }
332
333 /**
334 * @throws StringIndexOutOfBoundsException {@inheritDoc}
335 */
336 @Override
337 public StringBuilder insert(int offset, char[] str) {
338 super.insert(offset, str);
339 return this;
340 }
341
342 /**
343 * @throws IndexOutOfBoundsException {@inheritDoc}
344 */
345 @Override
346 public StringBuilder insert(int dstOffset, CharSequence s) {
347 super.insert(dstOffset, s);
348 return this;
349 }
350
351 /**
352 * @throws IndexOutOfBoundsException {@inheritDoc}
353 */
354 @Override
355 public StringBuilder insert(int dstOffset, CharSequence s,
356 int start, int end)
357 {
358 super.insert(dstOffset, s, start, end);
359 return this;
360 }
361
362 /**
363 * @throws StringIndexOutOfBoundsException {@inheritDoc}
364 */
365 @Override
366 public StringBuilder insert(int offset, boolean b) {
367 super.insert(offset, b);
368 return this;
369 }
370
371 /**
372 * @throws IndexOutOfBoundsException {@inheritDoc}
373 */
374 @Override
375 public StringBuilder insert(int offset, char c) {
376 super.insert(offset, c);
377 return this;
378 }
379
380 /**
381 * @throws StringIndexOutOfBoundsException {@inheritDoc}
382 */
383 @Override
384 public StringBuilder insert(int offset, int i) {
385 super.insert(offset, i);
386 return this;
387 }
388
389 /**
390 * @throws StringIndexOutOfBoundsException {@inheritDoc}
391 */
392 @Override
393 public StringBuilder insert(int offset, long l) {
394 super.insert(offset, l);
395 return this;
396 }
397
398 /**
399 * @throws StringIndexOutOfBoundsException {@inheritDoc}
400 */
401 @Override
402 public StringBuilder insert(int offset, float f) {
403 super.insert(offset, f);
404 return this;
405 }
406
407 /**
408 * @throws StringIndexOutOfBoundsException {@inheritDoc}
409 */
410 @Override
411 public StringBuilder insert(int offset, double d) {
412 super.insert(offset, d);
413 return this;
414 }
415
416 @Override
417 public int indexOf(String str) {
418 return super.indexOf(str);
419 }
420
421 @Override
422 public int indexOf(String str, int fromIndex) {
423 return super.indexOf(str, fromIndex);
424 }
425
426 @Override
427 public int lastIndexOf(String str) {
428 return super.lastIndexOf(str);
429 }
430
431 @Override
432 public int lastIndexOf(String str, int fromIndex) {
433 return super.lastIndexOf(str, fromIndex);
434 }
435
436 @Override
437 public StringBuilder reverse() {
438 super.reverse();
439 return this;
440 }
441
442 @Override
443 @HotSpotIntrinsicCandidate
444 public String toString() {
445 // Create a copy, don't share the array
446 return isLatin1() ? StringLatin1.newString(value, 0, count)
447 : StringUTF16.newString(value, 0, count);
448 }
449
450 /**
451 * Save the state of the {@code StringBuilder} instance to a stream
452 * (that is, serialize it).
453 *
454 * @serialData the number of characters currently stored in the string
455 * builder ({@code int}), followed by the characters in the
456 * string builder ({@code char[]}). The length of the
457 * {@code char} array may be greater than the number of
458 * characters currently stored in the string builder, in which
459 * case extra characters are ignored.
460 */
461 private void writeObject(java.io.ObjectOutputStream s)
462 throws java.io.IOException {
463 s.defaultWriteObject();
464 s.writeInt(count);
465 char[] val = new char[capacity()];
466 if (isLatin1()) {
467 StringLatin1.getChars(value, 0, count, val, 0);
468 } else {
469 StringUTF16.getChars(value, 0, count, val, 0);
470 }
471 s.writeObject(val);
472 }
473
474 /**
475 * readObject is called to restore the state of the StringBuffer from
476 * a stream.
477 */
478 private void readObject(java.io.ObjectInputStream s)
479 throws java.io.IOException, ClassNotFoundException {
480 s.defaultReadObject();
481 count = s.readInt();
482 char[] val = (char[]) s.readObject();
483 initBytes(val, 0, val.length);
484 }
485
486 }