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
29 /**
30 * A mutable sequence of characters. This class provides an API compatible
31 * with {@code StringBuffer}, but with no guarantee of synchronization.
32 * This class is designed for use as a drop-in replacement for
33 * {@code StringBuffer} in places where the string buffer was being
34 * used by a single thread (as is generally the case). Where possible,
35 * it is recommended that this class be used in preference to
36 * {@code StringBuffer} as it will be faster under most implementations.
37 *
38 * <p>The principal operations on a {@code StringBuilder} are the
39 * {@code append} and {@code insert} methods, which are
40 * overloaded so as to accept data of any type. Each effectively
41 * converts a given datum to a string and then appends or inserts the
42 * characters of that string to the string builder. The
43 * {@code append} method always adds these characters at the end
44 * of the builder; the {@code insert} method adds the characters at
45 * a specified point.
46 * <p>
47 * For example, if {@code z} refers to a string builder object
68 * or method in this class will cause a {@link NullPointerException} to be
69 * thrown.
70 *
71 * @author Michael McCloskey
72 * @see java.lang.StringBuffer
73 * @see java.lang.String
74 * @since 1.5
75 */
76 public final class StringBuilder
77 extends AbstractStringBuilder
78 implements java.io.Serializable, CharSequence
79 {
80
81 /** use serialVersionUID for interoperability */
82 static final long serialVersionUID = 4383685877147921099L;
83
84 /**
85 * Constructs a string builder with no characters in it and an
86 * initial capacity of 16 characters.
87 */
88 public StringBuilder() {
89 super(16);
90 }
91
92 /**
93 * Constructs a string builder with no characters in it and an
94 * initial capacity specified by the {@code capacity} argument.
95 *
96 * @param capacity the initial capacity.
97 * @throws NegativeArraySizeException if the {@code capacity}
98 * argument is less than {@code 0}.
99 */
100 public StringBuilder(int capacity) {
101 super(capacity);
102 }
103
104 /**
105 * Constructs a string builder initialized to the contents of the
106 * specified string. The initial capacity of the string builder is
107 * {@code 16} plus the length of the string argument.
108 *
109 * @param str the initial contents of the buffer.
110 */
111 public StringBuilder(String str) {
112 super(str.length() + 16);
113 append(str);
114 }
115
116 /**
117 * Constructs a string builder that contains the same characters
118 * as the specified {@code CharSequence}. The initial capacity of
119 * the string builder is {@code 16} plus the length of the
120 * {@code CharSequence} argument.
121 *
122 * @param seq the sequence to copy.
123 */
124 public StringBuilder(CharSequence seq) {
125 this(seq.length() + 16);
126 append(seq);
127 }
128
129 @Override
130 public StringBuilder append(Object obj) {
131 return append(String.valueOf(obj));
132 }
133
134 @Override
135 public StringBuilder append(String str) {
136 super.append(str);
137 return this;
138 }
139
140 /**
141 * Appends the specified {@code StringBuffer} to this sequence.
142 * <p>
143 * The characters of the {@code StringBuffer} argument are appended,
144 * in order, to this sequence, increasing the
145 * length of this sequence by the length of the argument.
146 * If {@code sb} is {@code null}, then the four characters
147 * {@code "null"} are appended to this sequence.
148 * <p>
149 * Let <i>n</i> be the length of this character sequence just prior to
150 * execution of the {@code append} method. Then the character at index
151 * <i>k</i> in the new character sequence is equal to the character at
152 * index <i>k</i> in the old character sequence, if <i>k</i> is less than
153 * <i>n</i>; otherwise, it is equal to the character at index <i>k-n</i>
154 * in the argument {@code sb}.
181 super.append(str);
182 return this;
183 }
184
185 /**
186 * @throws IndexOutOfBoundsException {@inheritDoc}
187 */
188 @Override
189 public StringBuilder append(char[] str, int offset, int len) {
190 super.append(str, offset, len);
191 return this;
192 }
193
194 @Override
195 public StringBuilder append(boolean b) {
196 super.append(b);
197 return this;
198 }
199
200 @Override
201 public StringBuilder append(char c) {
202 super.append(c);
203 return this;
204 }
205
206 @Override
207 public StringBuilder append(int i) {
208 super.append(i);
209 return this;
210 }
211
212 @Override
213 public StringBuilder append(long lng) {
214 super.append(lng);
215 return this;
216 }
217
218 @Override
219 public StringBuilder append(float f) {
220 super.append(f);
221 return this;
222 }
223
224 @Override
225 public StringBuilder append(double d) {
226 super.append(d);
385 return super.indexOf(str, fromIndex);
386 }
387
388 @Override
389 public int lastIndexOf(String str) {
390 return super.lastIndexOf(str);
391 }
392
393 @Override
394 public int lastIndexOf(String str, int fromIndex) {
395 return super.lastIndexOf(str, fromIndex);
396 }
397
398 @Override
399 public StringBuilder reverse() {
400 super.reverse();
401 return this;
402 }
403
404 @Override
405 public String toString() {
406 // Create a copy, don't share the array
407 return new String(value, 0, count);
408 }
409
410 /**
411 * Save the state of the {@code StringBuilder} instance to a stream
412 * (that is, serialize it).
413 *
414 * @serialData the number of characters currently stored in the string
415 * builder ({@code int}), followed by the characters in the
416 * string builder ({@code char[]}). The length of the
417 * {@code char} array may be greater than the number of
418 * characters currently stored in the string builder, in which
419 * case extra characters are ignored.
420 */
421 private void writeObject(java.io.ObjectOutputStream s)
422 throws java.io.IOException {
423 s.defaultWriteObject();
424 s.writeInt(count);
|
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
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}.
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);
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 new String(value, 0, count);
416 }
417
418 /**
419 * Save the state of the {@code StringBuilder} instance to a stream
420 * (that is, serialize it).
421 *
422 * @serialData the number of characters currently stored in the string
423 * builder ({@code int}), followed by the characters in the
424 * string builder ({@code char[]}). The length of the
425 * {@code char} array may be greater than the number of
426 * characters currently stored in the string builder, in which
427 * case extra characters are ignored.
428 */
429 private void writeObject(java.io.ObjectOutputStream s)
430 throws java.io.IOException {
431 s.defaultWriteObject();
432 s.writeInt(count);
|