1 /*
2 * Copyright (c) 2003, 2013, 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 * @author Michael McCloskey
73 * @see java.lang.StringBuffer
74 * @see java.lang.String
75 * @since 1.5
76 */
77 public final class StringBuilder
78 extends AbstractStringBuilder
79 implements java.io.Serializable, CharSequence
80 {
81
82 /** use serialVersionUID for interoperability */
83 static final long serialVersionUID = 4383685877147921099L;
84
85 /**
86 * Constructs a string builder with no characters in it and an
87 * initial capacity of 16 characters.
88 */
89 @HotSpotIntrinsicCandidate
90 public StringBuilder() {
91 super(16);
92 }
93
94 /**
95 * Constructs a string builder with no characters in it and an
96 * initial capacity specified by the {@code capacity} argument.
97 *
98 * @param capacity the initial capacity.
99 * @throws NegativeArraySizeException if the {@code capacity}
100 * argument is less than {@code 0}.
101 */
102 @HotSpotIntrinsicCandidate
103 public StringBuilder(int capacity) {
104 super(capacity);
105 }
106
107 /**
108 * Constructs a string builder initialized to the contents of the
109 * specified string. The initial capacity of the string builder is
110 * {@code 16} plus the length of the string argument.
111 *
112 * @param str the initial contents of the buffer.
113 */
114 @HotSpotIntrinsicCandidate
115 public StringBuilder(String str) {
116 super(str.length() + 16);
117 append(str);
118 }
119
120 /**
121 * Constructs a string builder that contains the same characters
122 * as the specified {@code CharSequence}. The initial capacity of
123 * the string builder is {@code 16} plus the length of the
124 * {@code CharSequence} argument.
125 *
126 * @param seq the sequence to copy.
127 */
128 public StringBuilder(CharSequence seq) {
129 this(seq.length() + 16);
130 append(seq);
131 }
132
133 @Override
134 public StringBuilder append(Object obj) {
135 return append(String.valueOf(obj));
136 }
137
138 @Override
139 @HotSpotIntrinsicCandidate
140 public StringBuilder append(String str) {
141 super.append(str);
142 return this;
143 }
144
145 /**
146 * Appends the specified {@code StringBuffer} to this sequence.
147 * <p>
148 * The characters of the {@code StringBuffer} argument are appended,
149 * in order, to this sequence, increasing the
150 * length of this sequence by the length of the argument.
151 * If {@code sb} is {@code null}, then the four characters
152 * {@code "null"} are appended to this sequence.
153 * <p>
154 * Let <i>n</i> be the length of this character sequence just prior to
155 * execution of the {@code append} method. Then the character at index
156 * <i>k</i> in the new character sequence is equal to the character at
157 * index <i>k</i> in the old character sequence, if <i>k</i> is less than
158 * <i>n</i>; otherwise, it is equal to the character at index <i>k-n</i>
159 * in the argument {@code sb}.
160 *
161 * @param sb the {@code StringBuffer} to append.
162 * @return a reference to this object.
163 */
164 public StringBuilder append(StringBuffer sb) {
165 super.append(sb);
166 return this;
167 }
168
169 @Override
170 public StringBuilder append(CharSequence s) {
171 super.append(s);
172 return this;
173 }
174
175 /**
176 * @throws IndexOutOfBoundsException {@inheritDoc}
177 */
178 @Override
179 public StringBuilder append(CharSequence s, int start, int end) {
180 super.append(s, start, end);
181 return this;
182 }
183
184 @Override
185 public StringBuilder append(char[] str) {
186 super.append(str);
187 return this;
188 }
189
190 /**
191 * @throws IndexOutOfBoundsException {@inheritDoc}
192 */
193 @Override
194 public StringBuilder append(char[] str, int offset, int len) {
195 super.append(str, offset, len);
196 return this;
197 }
198
199 @Override
200 public StringBuilder append(boolean b) {
201 super.append(b);
202 return this;
203 }
204
205 @Override
206 @HotSpotIntrinsicCandidate
207 public StringBuilder append(char c) {
208 super.append(c);
209 return this;
210 }
211
212 @Override
213 @HotSpotIntrinsicCandidate
214 public StringBuilder append(int i) {
215 super.append(i);
216 return this;
217 }
218
219 @Override
220 public StringBuilder append(long lng) {
221 super.append(lng);
222 return this;
223 }
224
225 @Override
226 public StringBuilder append(float f) {
227 super.append(f);
228 return this;
229 }
230
231 @Override
232 public StringBuilder append(double d) {
233 super.append(d);
234 return this;
235 }
236
237 @Override
238 public StringBuilder appendN(char c, int n) {
239 super.appendN(c, n);
240 return this;
241 }
242
243 /**
244 * @since 1.5
245 */
246 @Override
247 public StringBuilder appendCodePoint(int codePoint) {
248 super.appendCodePoint(codePoint);
249 return this;
250 }
251
252 /**
253 * @throws StringIndexOutOfBoundsException {@inheritDoc}
254 */
255 @Override
256 public StringBuilder delete(int start, int end) {
257 super.delete(start, end);
258 return this;
259 }
260
261 /**
262 * @throws StringIndexOutOfBoundsException {@inheritDoc}
263 */
264 @Override
265 public StringBuilder deleteCharAt(int index) {
266 super.deleteCharAt(index);
267 return this;
268 }
269
270 /**
271 * @throws StringIndexOutOfBoundsException {@inheritDoc}
272 */
273 @Override
274 public StringBuilder replace(int start, int end, String str) {
275 super.replace(start, end, str);
276 return this;
277 }
278
279 /**
280 * @throws StringIndexOutOfBoundsException {@inheritDoc}
281 */
282 @Override
283 public StringBuilder insert(int index, char[] str, int offset,
284 int len)
285 {
286 super.insert(index, str, offset, len);
287 return this;
288 }
289
290 /**
291 * @throws StringIndexOutOfBoundsException {@inheritDoc}
292 */
293 @Override
294 public StringBuilder insert(int offset, Object obj) {
295 super.insert(offset, obj);
296 return this;
297 }
298
299 /**
300 * @throws StringIndexOutOfBoundsException {@inheritDoc}
301 */
302 @Override
303 public StringBuilder insert(int offset, String str) {
304 super.insert(offset, str);
305 return this;
306 }
307
308 /**
309 * @throws StringIndexOutOfBoundsException {@inheritDoc}
310 */
311 @Override
312 public StringBuilder insert(int offset, char[] str) {
313 super.insert(offset, str);
314 return this;
315 }
316
317 /**
318 * @throws IndexOutOfBoundsException {@inheritDoc}
319 */
320 @Override
321 public StringBuilder insert(int dstOffset, CharSequence s) {
322 super.insert(dstOffset, s);
323 return this;
324 }
325
326 /**
327 * @throws IndexOutOfBoundsException {@inheritDoc}
328 */
329 @Override
330 public StringBuilder insert(int dstOffset, CharSequence s,
331 int start, int end)
332 {
333 super.insert(dstOffset, s, start, end);
334 return this;
335 }
336
337 /**
338 * @throws StringIndexOutOfBoundsException {@inheritDoc}
339 */
340 @Override
341 public StringBuilder insert(int offset, boolean b) {
342 super.insert(offset, b);
343 return this;
344 }
345
346 /**
347 * @throws IndexOutOfBoundsException {@inheritDoc}
348 */
349 @Override
350 public StringBuilder insert(int offset, char c) {
351 super.insert(offset, c);
352 return this;
353 }
354
355 /**
356 * @throws StringIndexOutOfBoundsException {@inheritDoc}
357 */
358 @Override
359 public StringBuilder insert(int offset, int i) {
360 super.insert(offset, i);
361 return this;
362 }
363
364 /**
365 * @throws StringIndexOutOfBoundsException {@inheritDoc}
366 */
367 @Override
368 public StringBuilder insert(int offset, long l) {
369 super.insert(offset, l);
370 return this;
371 }
372
373 /**
374 * @throws StringIndexOutOfBoundsException {@inheritDoc}
375 */
376 @Override
377 public StringBuilder insert(int offset, float f) {
378 super.insert(offset, f);
379 return this;
380 }
381
382 /**
383 * @throws StringIndexOutOfBoundsException {@inheritDoc}
384 */
385 @Override
386 public StringBuilder insert(int offset, double d) {
387 super.insert(offset, d);
388 return this;
389 }
390
391 @Override
392 public int indexOf(String str) {
393 return super.indexOf(str);
394 }
395
396 @Override
397 public int indexOf(String str, int fromIndex) {
398 return super.indexOf(str, fromIndex);
399 }
400
401 @Override
402 public int lastIndexOf(String str) {
403 return super.lastIndexOf(str);
404 }
405
406 @Override
407 public int lastIndexOf(String str, int fromIndex) {
408 return super.lastIndexOf(str, fromIndex);
409 }
410
411 @Override
412 public StringBuilder reverse() {
413 super.reverse();
414 return this;
415 }
416
417 @Override
418 @HotSpotIntrinsicCandidate
419 public String toString() {
420 // Create a copy, don't share the array
421 return isLatin1() ? StringLatin1.newString(value, 0, count)
422 : StringUTF16.newString(value, 0, count);
423 }
424
425 /**
426 * Save the state of the {@code StringBuilder} instance to a stream
427 * (that is, serialize it).
428 *
429 * @serialData the number of characters currently stored in the string
430 * builder ({@code int}), followed by the characters in the
431 * string builder ({@code char[]}). The length of the
432 * {@code char} array may be greater than the number of
433 * characters currently stored in the string builder, in which
434 * case extra characters are ignored.
435 */
436 private void writeObject(java.io.ObjectOutputStream s)
437 throws java.io.IOException {
438 s.defaultWriteObject();
439 s.writeInt(count);
440 char[] val = new char[capacity()];
441 if (isLatin1()) {
442 StringLatin1.getChars(value, 0, count, val, 0);
443 } else {
444 StringUTF16.getChars(value, 0, count, val, 0);
445 }
446 s.writeObject(val);
447 }
448
449 /**
450 * readObject is called to restore the state of the StringBuffer from
451 * a stream.
452 */
453 private void readObject(java.io.ObjectInputStream s)
454 throws java.io.IOException, ClassNotFoundException {
455 s.defaultReadObject();
456 count = s.readInt();
457 char[] val = (char[]) s.readObject();
458 initBytes(val, 0, val.length);
459 }
460
461 }