1 /*
2 * Copyright (c) 2003, 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 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.length() + 16);
125 append(str);
126 }
127
128 /**
129 * Constructs a string builder that contains the same characters
130 * as the specified {@code CharSequence}. The initial capacity of
131 * the string builder is {@code 16} plus the length of the
132 * {@code CharSequence} argument.
133 *
134 * @param seq the sequence to copy.
135 */
136 public StringBuilder(CharSequence seq) {
137 this(seq.length() + 16);
138 append(seq);
139 }
140
141 /**
142 * Compares two {@code StringBuilder} instances lexicographically. This method
143 * follows the same rules for lexicographical comparison as defined in the
144 * {@linkplain java.lang.CharSequence#compare(java.lang.CharSequence,
145 * java.lang.CharSequence) CharSequence.compare(this, another)} method.
146 *
147 * <p>
148 * For finer-grained, locale-sensitive String comparison, refer to
149 * {@link java.text.Collator}.
150 *
151 * @param another the {@code StringBuilder} to be compared with
152 *
153 * @return the value {@code 0} if this {@code StringBuilder} contains the same
154 * character sequence as that of the argument {@code StringBuilder}; a negative integer
155 * if this {@code StringBuilder} is lexicographically less than the
156 * {@code StringBuilder} argument; or a positive integer if this {@code StringBuilder}
157 * is lexicographically greater than the {@code StringBuilder} argument.
158 *
159 * @since 11
160 */
161 @Override
162 public int compareTo(StringBuilder another) {
163 return super.compareTo(another);
164 }
165
166 @Override
167 public StringBuilder append(Object obj) {
168 return append(String.valueOf(obj));
169 }
170
171 @Override
172 @HotSpotIntrinsicCandidate
173 public StringBuilder append(String str) {
174 super.append(str);
175 return this;
176 }
177
178 /**
179 * Appends the specified {@code StringBuffer} to this sequence.
180 * <p>
181 * The characters of the {@code StringBuffer} argument are appended,
182 * in order, to this sequence, increasing the
183 * length of this sequence by the length of the argument.
184 * If {@code sb} is {@code null}, then the four characters
185 * {@code "null"} are appended to this sequence.
186 * <p>
187 * Let <i>n</i> be the length of this character sequence just prior to
188 * execution of the {@code append} method. Then the character at index
189 * <i>k</i> in the new character sequence is equal to the character at
190 * index <i>k</i> in the old character sequence, if <i>k</i> is less than
191 * <i>n</i>; otherwise, it is equal to the character at index <i>k-n</i>
192 * in the argument {@code sb}.
193 *
194 * @param sb the {@code StringBuffer} to append.
195 * @return a reference to this object.
196 */
197 public StringBuilder append(StringBuffer sb) {
198 super.append(sb);
199 return this;
200 }
201
202 @Override
203 public StringBuilder append(CharSequence s) {
204 super.append(s);
205 return this;
206 }
207
208 /**
209 * @throws IndexOutOfBoundsException {@inheritDoc}
210 */
211 @Override
212 public StringBuilder append(CharSequence s, int start, int end) {
213 super.append(s, start, end);
214 return this;
215 }
216
217 @Override
218 public StringBuilder append(char[] str) {
219 super.append(str);
220 return this;
221 }
222
223 /**
224 * @throws IndexOutOfBoundsException {@inheritDoc}
225 */
226 @Override
227 public StringBuilder append(char[] str, int offset, int len) {
228 super.append(str, offset, len);
229 return this;
230 }
231
232 @Override
233 public StringBuilder append(boolean b) {
234 super.append(b);
235 return this;
236 }
237
238 @Override
239 @HotSpotIntrinsicCandidate
240 public StringBuilder append(char c) {
241 super.append(c);
242 return this;
243 }
244
245 @Override
246 @HotSpotIntrinsicCandidate
247 public StringBuilder append(int i) {
248 super.append(i);
249 return this;
250 }
251
252 @Override
253 public StringBuilder append(long lng) {
254 super.append(lng);
255 return this;
256 }
257
258 @Override
259 public StringBuilder append(float f) {
260 super.append(f);
261 return this;
262 }
263
264 @Override
265 public StringBuilder append(double d) {
266 super.append(d);
267 return this;
268 }
269
270 /**
271 * @since 1.5
272 */
273 @Override
274 public StringBuilder appendCodePoint(int codePoint) {
275 super.appendCodePoint(codePoint);
276 return this;
277 }
278
279 /**
280 * @throws StringIndexOutOfBoundsException {@inheritDoc}
281 */
282 @Override
283 public StringBuilder delete(int start, int end) {
284 super.delete(start, end);
285 return this;
286 }
287
288 /**
289 * @throws StringIndexOutOfBoundsException {@inheritDoc}
290 */
291 @Override
292 public StringBuilder deleteCharAt(int index) {
293 super.deleteCharAt(index);
294 return this;
295 }
296
297 /**
298 * @throws StringIndexOutOfBoundsException {@inheritDoc}
299 */
300 @Override
301 public StringBuilder replace(int start, int end, String str) {
302 super.replace(start, end, str);
303 return this;
304 }
305
306 /**
307 * @throws StringIndexOutOfBoundsException {@inheritDoc}
308 */
309 @Override
310 public StringBuilder insert(int index, char[] str, int offset,
311 int len)
312 {
313 super.insert(index, str, offset, len);
314 return this;
315 }
316
317 /**
318 * @throws StringIndexOutOfBoundsException {@inheritDoc}
319 */
320 @Override
321 public StringBuilder insert(int offset, Object obj) {
322 super.insert(offset, obj);
323 return this;
324 }
325
326 /**
327 * @throws StringIndexOutOfBoundsException {@inheritDoc}
328 */
329 @Override
330 public StringBuilder insert(int offset, String str) {
331 super.insert(offset, str);
332 return this;
333 }
334
335 /**
336 * @throws StringIndexOutOfBoundsException {@inheritDoc}
337 */
338 @Override
339 public StringBuilder insert(int offset, char[] str) {
340 super.insert(offset, str);
341 return this;
342 }
343
344 /**
345 * @throws IndexOutOfBoundsException {@inheritDoc}
346 */
347 @Override
348 public StringBuilder insert(int dstOffset, CharSequence s) {
349 super.insert(dstOffset, s);
350 return this;
351 }
352
353 /**
354 * @throws IndexOutOfBoundsException {@inheritDoc}
355 */
356 @Override
357 public StringBuilder insert(int dstOffset, CharSequence s,
358 int start, int end)
359 {
360 super.insert(dstOffset, s, start, end);
361 return this;
362 }
363
364 /**
365 * @throws StringIndexOutOfBoundsException {@inheritDoc}
366 */
367 @Override
368 public StringBuilder insert(int offset, boolean b) {
369 super.insert(offset, b);
370 return this;
371 }
372
373 /**
374 * @throws IndexOutOfBoundsException {@inheritDoc}
375 */
376 @Override
377 public StringBuilder insert(int offset, char c) {
378 super.insert(offset, c);
379 return this;
380 }
381
382 /**
383 * @throws StringIndexOutOfBoundsException {@inheritDoc}
384 */
385 @Override
386 public StringBuilder insert(int offset, int i) {
387 super.insert(offset, i);
388 return this;
389 }
390
391 /**
392 * @throws StringIndexOutOfBoundsException {@inheritDoc}
393 */
394 @Override
395 public StringBuilder insert(int offset, long l) {
396 super.insert(offset, l);
397 return this;
398 }
399
400 /**
401 * @throws StringIndexOutOfBoundsException {@inheritDoc}
402 */
403 @Override
404 public StringBuilder insert(int offset, float f) {
405 super.insert(offset, f);
406 return this;
407 }
408
409 /**
410 * @throws StringIndexOutOfBoundsException {@inheritDoc}
411 */
412 @Override
413 public StringBuilder insert(int offset, double d) {
414 super.insert(offset, d);
415 return this;
416 }
417
418 @Override
419 public int indexOf(String str) {
420 return super.indexOf(str);
421 }
422
423 @Override
424 public int indexOf(String str, int fromIndex) {
425 return super.indexOf(str, fromIndex);
426 }
427
428 @Override
429 public int lastIndexOf(String str) {
430 return super.lastIndexOf(str);
431 }
432
433 @Override
434 public int lastIndexOf(String str, int fromIndex) {
435 return super.lastIndexOf(str, fromIndex);
436 }
437
438 @Override
439 public StringBuilder reverse() {
440 super.reverse();
441 return this;
442 }
443
444 @Override
445 @HotSpotIntrinsicCandidate
446 public String toString() {
447 // Create a copy, don't share the array
448 return isLatin1() ? StringLatin1.newString(value, 0, count)
449 : StringUTF16.newString(value, 0, count);
450 }
451
452 /**
453 * Save the state of the {@code StringBuilder} instance to a stream
454 * (that is, serialize it).
455 *
456 * @serialData the number of characters currently stored in the string
457 * builder ({@code int}), followed by the characters in the
458 * string builder ({@code char[]}). The length of the
459 * {@code char} array may be greater than the number of
460 * characters currently stored in the string builder, in which
461 * case extra characters are ignored.
462 */
463 private void writeObject(java.io.ObjectOutputStream s)
464 throws java.io.IOException {
465 s.defaultWriteObject();
466 s.writeInt(count);
467 char[] val = new char[capacity()];
468 if (isLatin1()) {
469 StringLatin1.getChars(value, 0, count, val, 0);
470 } else {
471 StringUTF16.getChars(value, 0, count, val, 0);
472 }
473 s.writeObject(val);
474 }
475
476 /**
477 * readObject is called to restore the state of the StringBuffer from
478 * a stream.
479 */
480 private void readObject(java.io.ObjectInputStream s)
481 throws java.io.IOException, ClassNotFoundException {
482 s.defaultReadObject();
483 count = s.readInt();
484 char[] val = (char[]) s.readObject();
485 initBytes(val, 0, val.length);
486 }
487
488 }
489