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
26package java.lang;
27
28import 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 */
77public 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    /**
238     * @since 1.5
239     */
240    @Override
241    public StringBuilder appendCodePoint(int codePoint) {
242        super.appendCodePoint(codePoint);
243        return this;
244    }
245
246    /**
247     * @throws StringIndexOutOfBoundsException {@inheritDoc}
248     */
249    @Override
250    public StringBuilder delete(int start, int end) {
251        super.delete(start, end);
252        return this;
253    }
254
255    /**
256     * @throws StringIndexOutOfBoundsException {@inheritDoc}
257     */
258    @Override
259    public StringBuilder deleteCharAt(int index) {
260        super.deleteCharAt(index);
261        return this;
262    }
263
264    /**
265     * @throws StringIndexOutOfBoundsException {@inheritDoc}
266     */
267    @Override
268    public StringBuilder replace(int start, int end, String str) {
269        super.replace(start, end, str);
270        return this;
271    }
272
273    /**
274     * @throws StringIndexOutOfBoundsException {@inheritDoc}
275     */
276    @Override
277    public StringBuilder insert(int index, char[] str, int offset,
278                                int len)
279    {
280        super.insert(index, str, offset, len);
281        return this;
282    }
283
284    /**
285     * @throws StringIndexOutOfBoundsException {@inheritDoc}
286     */
287    @Override
288    public StringBuilder insert(int offset, Object obj) {
289            super.insert(offset, obj);
290            return this;
291    }
292
293    /**
294     * @throws StringIndexOutOfBoundsException {@inheritDoc}
295     */
296    @Override
297    public StringBuilder insert(int offset, String str) {
298        super.insert(offset, str);
299        return this;
300    }
301
302    /**
303     * @throws StringIndexOutOfBoundsException {@inheritDoc}
304     */
305    @Override
306    public StringBuilder insert(int offset, char[] str) {
307        super.insert(offset, str);
308        return this;
309    }
310
311    /**
312     * @throws IndexOutOfBoundsException {@inheritDoc}
313     */
314    @Override
315    public StringBuilder insert(int dstOffset, CharSequence s) {
316            super.insert(dstOffset, s);
317            return this;
318    }
319
320    /**
321     * @throws IndexOutOfBoundsException {@inheritDoc}
322     */
323    @Override
324    public StringBuilder insert(int dstOffset, CharSequence s,
325                                int start, int end)
326    {
327        super.insert(dstOffset, s, start, end);
328        return this;
329    }
330
331    /**
332     * @throws StringIndexOutOfBoundsException {@inheritDoc}
333     */
334    @Override
335    public StringBuilder insert(int offset, boolean b) {
336        super.insert(offset, b);
337        return this;
338    }
339
340    /**
341     * @throws IndexOutOfBoundsException {@inheritDoc}
342     */
343    @Override
344    public StringBuilder insert(int offset, char c) {
345        super.insert(offset, c);
346        return this;
347    }
348
349    /**
350     * @throws StringIndexOutOfBoundsException {@inheritDoc}
351     */
352    @Override
353    public StringBuilder insert(int offset, int i) {
354        super.insert(offset, i);
355        return this;
356    }
357
358    /**
359     * @throws StringIndexOutOfBoundsException {@inheritDoc}
360     */
361    @Override
362    public StringBuilder insert(int offset, long l) {
363        super.insert(offset, l);
364        return this;
365    }
366
367    /**
368     * @throws StringIndexOutOfBoundsException {@inheritDoc}
369     */
370    @Override
371    public StringBuilder insert(int offset, float f) {
372        super.insert(offset, f);
373        return this;
374    }
375
376    /**
377     * @throws StringIndexOutOfBoundsException {@inheritDoc}
378     */
379    @Override
380    public StringBuilder insert(int offset, double d) {
381        super.insert(offset, d);
382        return this;
383    }
384
385    @Override
386    public int indexOf(String str) {
387        return super.indexOf(str);
388    }
389
390    @Override
391    public int indexOf(String str, int fromIndex) {
392        return super.indexOf(str, fromIndex);
393    }
394
395    @Override
396    public int lastIndexOf(String str) {
397        return super.lastIndexOf(str);
398    }
399
400    @Override
401    public int lastIndexOf(String str, int fromIndex) {
402        return super.lastIndexOf(str, fromIndex);
403    }
404
405    @Override
406    public StringBuilder reverse() {
407        super.reverse();
408        return this;
409    }
410
411    @Override
412    @HotSpotIntrinsicCandidate
413    public String toString() {
414        // Create a copy, don't share the array
415        return isLatin1() ? StringLatin1.newString(value, 0, count)
416                          : StringUTF16.newString(value, 0, count);
417    }
418
419    /**
420     * Save the state of the {@code StringBuilder} instance to a stream
421     * (that is, serialize it).
422     *
423     * @serialData the number of characters currently stored in the string
424     *             builder ({@code int}), followed by the characters in the
425     *             string builder ({@code char[]}).   The length of the
426     *             {@code char} array may be greater than the number of
427     *             characters currently stored in the string builder, in which
428     *             case extra characters are ignored.
429     */
430    private void writeObject(java.io.ObjectOutputStream s)
431        throws java.io.IOException {
432        s.defaultWriteObject();
433        s.writeInt(count);
434        char[] val = new char[capacity()];
435        if (isLatin1()) {
436            StringLatin1.getChars(value, 0, count, val, 0);
437        } else {
438            StringUTF16.getChars(value, 0, count, val, 0);
439        }
440        s.writeObject(val);
441    }
442
443    /**
444     * readObject is called to restore the state of the StringBuffer from
445     * a stream.
446     */
447    private void readObject(java.io.ObjectInputStream s)
448        throws java.io.IOException, ClassNotFoundException {
449        s.defaultReadObject();
450        count = s.readInt();
451        char[] val = (char[]) s.readObject();
452        initBytes(val, 0, val.length);
453    }
454
455}
456