001 /*
002 * Copyright 1994-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.lang;
027
028 /**
029 * A thread-safe, mutable sequence of characters.
030 * A string buffer is like a {@link String}, but can be modified. At any
031 * point in time it contains some particular sequence of characters, but
032 * the length and content of the sequence can be changed through certain
033 * method calls.
034 * <p>
035 * String buffers are safe for use by multiple threads. The methods
036 * are synchronized where necessary so that all the operations on any
037 * particular instance behave as if they occur in some serial order
038 * that is consistent with the order of the method calls made by each of
039 * the individual threads involved.
040 * <p>
041 * The principal operations on a <code>StringBuffer</code> are the
042 * <code>append</code> and <code>insert</code> methods, which are
043 * overloaded so as to accept data of any type. Each effectively
044 * converts a given datum to a string and then appends or inserts the
045 * characters of that string to the string buffer. The
046 * <code>append</code> method always adds these characters at the end
047 * of the buffer; the <code>insert</code> method adds the characters at
048 * a specified point.
049 * <p>
050 * For example, if <code>z</code> refers to a string buffer object
051 * whose current contents are "<code>start</code>", then
052 * the method call <code>z.append("le")</code> would cause the string
053 * buffer to contain "<code>startle</code>", whereas
054 * <code>z.insert(4, "le")</code> would alter the string buffer to
055 * contain "<code>starlet</code>".
056 * <p>
057 * In general, if sb refers to an instance of a <code>StringBuffer</code>,
058 * then <code>sb.append(x)</code> has the same effect as
059 * <code>sb.insert(sb.length(), x)</code>.
060 * <p>
061 * Whenever an operation occurs involving a source sequence (such as
062 * appending or inserting from a source sequence) this class synchronizes
063 * only on the string buffer performing the operation, not on the source.
064 * <p>
065 * Every string buffer has a capacity. As long as the length of the
066 * character sequence contained in the string buffer does not exceed
067 * the capacity, it is not necessary to allocate a new internal
068 * buffer array. If the internal buffer overflows, it is
069 * automatically made larger.
070 *
071 * As of release JDK 5, this class has been supplemented with an equivalent
072 * class designed for use by a single thread, {@link StringBuilder}. The
073 * <tt>StringBuilder</tt> class should generally be used in preference to
074 * this one, as it supports all of the same operations but it is faster, as
075 * it performs no synchronization.
076 *
077 * @author Arthur van Hoff
078 * @version 1.107, 05/05/07
079 * @see java.lang.StringBuilder
080 * @see java.lang.String
081 * @since JDK1.0
082 */
083 public final class StringBuffer extends AbstractStringBuilder implements
084 java.io.Serializable, CharSequence {
085
086 /** use serialVersionUID from JDK 1.0.2 for interoperability */
087 static final long serialVersionUID = 3388685877147921107L;
088
089 /**
090 * Constructs a string buffer with no characters in it and an
091 * initial capacity of 16 characters.
092 */
093 public StringBuffer() {
094 super (16);
095 }
096
097 /**
098 * Constructs a string buffer with no characters in it and
099 * the specified initial capacity.
100 *
101 * @param capacity the initial capacity.
102 * @exception NegativeArraySizeException if the <code>capacity</code>
103 * argument is less than <code>0</code>.
104 */
105 public StringBuffer(int capacity) {
106 super (capacity);
107 }
108
109 /**
110 * Constructs a string buffer initialized to the contents of the
111 * specified string. The initial capacity of the string buffer is
112 * <code>16</code> plus the length of the string argument.
113 *
114 * @param str the initial contents of the buffer.
115 * @exception NullPointerException if <code>str</code> is <code>null</code>
116 */
117 public StringBuffer(String str) {
118 super (str.length() + 16);
119 append(str);
120 }
121
122 /**
123 * Constructs a string buffer that contains the same characters
124 * as the specified <code>CharSequence</code>. The initial capacity of
125 * the string buffer is <code>16</code> plus the length of the
126 * <code>CharSequence</code> argument.
127 * <p>
128 * If the length of the specified <code>CharSequence</code> is
129 * less than or equal to zero, then an empty buffer of capacity
130 * <code>16</code> is returned.
131 *
132 * @param seq the sequence to copy.
133 * @exception NullPointerException if <code>seq</code> is <code>null</code>
134 * @since 1.5
135 */
136 public StringBuffer(CharSequence seq) {
137 this (seq.length() + 16);
138 append(seq);
139 }
140
141 public synchronized int length() {
142 return count;
143 }
144
145 public synchronized int capacity() {
146 return value.length;
147 }
148
149 public synchronized void ensureCapacity(int minimumCapacity) {
150 if (minimumCapacity > value.length) {
151 expandCapacity(minimumCapacity);
152 }
153 }
154
155 /**
156 * @since 1.5
157 */
158 public synchronized void trimToSize() {
159 super .trimToSize();
160 }
161
162 /**
163 * @throws IndexOutOfBoundsException {@inheritDoc}
164 * @see #length()
165 */
166 public synchronized void setLength(int newLength) {
167 super .setLength(newLength);
168 }
169
170 /**
171 * @throws IndexOutOfBoundsException {@inheritDoc}
172 * @see #length()
173 */
174 public synchronized char charAt(int index) {
175 if ((index < 0) || (index >= count))
176 throw new StringIndexOutOfBoundsException(index);
177 return value[index];
178 }
179
180 /**
181 * @since 1.5
182 */
183 public synchronized int codePointAt(int index) {
184 return super .codePointAt(index);
185 }
186
187 /**
188 * @since 1.5
189 */
190 public synchronized int codePointBefore(int index) {
191 return super .codePointBefore(index);
192 }
193
194 /**
195 * @since 1.5
196 */
197 public synchronized int codePointCount(int beginIndex, int endIndex) {
198 return super .codePointCount(beginIndex, endIndex);
199 }
200
201 /**
202 * @since 1.5
203 */
204 public synchronized int offsetByCodePoints(int index,
205 int codePointOffset) {
206 return super .offsetByCodePoints(index, codePointOffset);
207 }
208
209 /**
210 * @throws NullPointerException {@inheritDoc}
211 * @throws IndexOutOfBoundsException {@inheritDoc}
212 */
213 public synchronized void getChars(int srcBegin, int srcEnd,
214 char dst[], int dstBegin) {
215 super .getChars(srcBegin, srcEnd, dst, dstBegin);
216 }
217
218 /**
219 * @throws IndexOutOfBoundsException {@inheritDoc}
220 * @see #length()
221 */
222 public synchronized void setCharAt(int index, char ch) {
223 if ((index < 0) || (index >= count))
224 throw new StringIndexOutOfBoundsException(index);
225 value[index] = ch;
226 }
227
228 /**
229 * @see java.lang.String#valueOf(java.lang.Object)
230 * @see #append(java.lang.String)
231 */
232 public synchronized StringBuffer append(Object obj) {
233 super .append(String.valueOf(obj));
234 return this ;
235 }
236
237 public synchronized StringBuffer append(String str) {
238 super .append(str);
239 return this ;
240 }
241
242 /**
243 * Appends the specified <tt>StringBuffer</tt> to this sequence.
244 * <p>
245 * The characters of the <tt>StringBuffer</tt> argument are appended,
246 * in order, to the contents of this <tt>StringBuffer</tt>, increasing the
247 * length of this <tt>StringBuffer</tt> by the length of the argument.
248 * If <tt>sb</tt> is <tt>null</tt>, then the four characters
249 * <tt>"null"</tt> are appended to this <tt>StringBuffer</tt>.
250 * <p>
251 * Let <i>n</i> be the length of the old character sequence, the one
252 * contained in the <tt>StringBuffer</tt> just prior to execution of the
253 * <tt>append</tt> method. Then the character at index <i>k</i> in
254 * the new character sequence is equal to the character at index <i>k</i>
255 * in the old character sequence, if <i>k</i> is less than <i>n</i>;
256 * otherwise, it is equal to the character at index <i>k-n</i> in the
257 * argument <code>sb</code>.
258 * <p>
259 * This method synchronizes on <code>this</code> (the destination)
260 * object but does not synchronize on the source (<code>sb</code>).
261 *
262 * @param sb the <tt>StringBuffer</tt> to append.
263 * @return a reference to this object.
264 * @since 1.4
265 */
266 public synchronized StringBuffer append(StringBuffer sb) {
267 super .append(sb);
268 return this ;
269 }
270
271 /**
272 * Appends the specified <code>CharSequence</code> to this
273 * sequence.
274 * <p>
275 * The characters of the <code>CharSequence</code> argument are appended,
276 * in order, increasing the length of this sequence by the length of the
277 * argument.
278 *
279 * <p>The result of this method is exactly the same as if it were an
280 * invocation of this.append(s, 0, s.length());
281 *
282 * <p>This method synchronizes on this (the destination)
283 * object but does not synchronize on the source (<code>s</code>).
284 *
285 * <p>If <code>s</code> is <code>null</code>, then the four characters
286 * <code>"null"</code> are appended.
287 *
288 * @param s the <code>CharSequence</code> to append.
289 * @return a reference to this object.
290 * @since 1.5
291 */
292 public StringBuffer append(CharSequence s) {
293 // Note, synchronization achieved via other invocations
294 if (s == null)
295 s = "null";
296 if (s instanceof String)
297 return this .append((String) s);
298 if (s instanceof StringBuffer)
299 return this .append((StringBuffer) s);
300 return this .append(s, 0, s.length());
301 }
302
303 /**
304 * @throws IndexOutOfBoundsException {@inheritDoc}
305 * @since 1.5
306 */
307 public synchronized StringBuffer append(CharSequence s, int start,
308 int end) {
309 super .append(s, start, end);
310 return this ;
311 }
312
313 public synchronized StringBuffer append(char str[]) {
314 super .append(str);
315 return this ;
316 }
317
318 public synchronized StringBuffer append(char str[], int offset,
319 int len) {
320 super .append(str, offset, len);
321 return this ;
322 }
323
324 /**
325 * @see java.lang.String#valueOf(boolean)
326 * @see #append(java.lang.String)
327 */
328 public synchronized StringBuffer append(boolean b) {
329 super .append(b);
330 return this ;
331 }
332
333 public synchronized StringBuffer append(char c) {
334 super .append(c);
335 return this ;
336 }
337
338 /**
339 * @see java.lang.String#valueOf(int)
340 * @see #append(java.lang.String)
341 */
342 public synchronized StringBuffer append(int i) {
343 super .append(i);
344 return this ;
345 }
346
347 /**
348 * @since 1.5
349 */
350 public synchronized StringBuffer appendCodePoint(int codePoint) {
351 super .appendCodePoint(codePoint);
352 return this ;
353 }
354
355 /**
356 * @see java.lang.String#valueOf(long)
357 * @see #append(java.lang.String)
358 */
359 public synchronized StringBuffer append(long lng) {
360 super .append(lng);
361 return this ;
362 }
363
364 /**
365 * @see java.lang.String#valueOf(float)
366 * @see #append(java.lang.String)
367 */
368 public synchronized StringBuffer append(float f) {
369 super .append(f);
370 return this ;
371 }
372
373 /**
374 * @see java.lang.String#valueOf(double)
375 * @see #append(java.lang.String)
376 */
377 public synchronized StringBuffer append(double d) {
378 super .append(d);
379 return this ;
380 }
381
382 /**
383 * @throws StringIndexOutOfBoundsException {@inheritDoc}
384 * @since 1.2
385 */
386 public synchronized StringBuffer delete(int start, int end) {
387 super .delete(start, end);
388 return this ;
389 }
390
391 /**
392 * @throws StringIndexOutOfBoundsException {@inheritDoc}
393 * @since 1.2
394 */
395 public synchronized StringBuffer deleteCharAt(int index) {
396 super .deleteCharAt(index);
397 return this ;
398 }
399
400 /**
401 * @throws StringIndexOutOfBoundsException {@inheritDoc}
402 * @since 1.2
403 */
404 public synchronized StringBuffer replace(int start, int end,
405 String str) {
406 super .replace(start, end, str);
407 return this ;
408 }
409
410 /**
411 * @throws StringIndexOutOfBoundsException {@inheritDoc}
412 * @since 1.2
413 */
414 public synchronized String substring(int start) {
415 return substring(start, count);
416 }
417
418 /**
419 * @throws IndexOutOfBoundsException {@inheritDoc}
420 * @since 1.4
421 */
422 public synchronized CharSequence subSequence(int start, int end) {
423 return super .substring(start, end);
424 }
425
426 /**
427 * @throws StringIndexOutOfBoundsException {@inheritDoc}
428 * @since 1.2
429 */
430 public synchronized String substring(int start, int end) {
431 return super .substring(start, end);
432 }
433
434 /**
435 * @throws StringIndexOutOfBoundsException {@inheritDoc}
436 * @since 1.2
437 */
438 public synchronized StringBuffer insert(int index, char str[],
439 int offset, int len) {
440 super .insert(index, str, offset, len);
441 return this ;
442 }
443
444 /**
445 * @throws StringIndexOutOfBoundsException {@inheritDoc}
446 * @see java.lang.String#valueOf(java.lang.Object)
447 * @see #insert(int, java.lang.String)
448 * @see #length()
449 */
450 public synchronized StringBuffer insert(int offset, Object obj) {
451 super .insert(offset, String.valueOf(obj));
452 return this ;
453 }
454
455 /**
456 * @throws StringIndexOutOfBoundsException {@inheritDoc}
457 * @see #length()
458 */
459 public synchronized StringBuffer insert(int offset, String str) {
460 super .insert(offset, str);
461 return this ;
462 }
463
464 /**
465 * @throws StringIndexOutOfBoundsException {@inheritDoc}
466 */
467 public synchronized StringBuffer insert(int offset, char str[]) {
468 super .insert(offset, str);
469 return this ;
470 }
471
472 /**
473 * @throws IndexOutOfBoundsException {@inheritDoc}
474 * @since 1.5
475 */
476 public StringBuffer insert(int dstOffset, CharSequence s) {
477 // Note, synchronization achieved via other invocations
478 if (s == null)
479 s = "null";
480 if (s instanceof String)
481 return this .insert(dstOffset, (String) s);
482 return this .insert(dstOffset, s, 0, s.length());
483 }
484
485 /**
486 * @throws IndexOutOfBoundsException {@inheritDoc}
487 * @since 1.5
488 */
489 public synchronized StringBuffer insert(int dstOffset,
490 CharSequence s, int start, int end) {
491 super .insert(dstOffset, s, start, end);
492 return this ;
493 }
494
495 /**
496 * @throws StringIndexOutOfBoundsException {@inheritDoc}
497 * @see java.lang.String#valueOf(boolean)
498 * @see #insert(int, java.lang.String)
499 * @see #length()
500 */
501 public StringBuffer insert(int offset, boolean b) {
502 return insert(offset, String.valueOf(b));
503 }
504
505 /**
506 * @throws IndexOutOfBoundsException {@inheritDoc}
507 * @see #length()
508 */
509 public synchronized StringBuffer insert(int offset, char c) {
510 super .insert(offset, c);
511 return this ;
512 }
513
514 /**
515 * @throws StringIndexOutOfBoundsException {@inheritDoc}
516 * @see java.lang.String#valueOf(int)
517 * @see #insert(int, java.lang.String)
518 * @see #length()
519 */
520 public StringBuffer insert(int offset, int i) {
521 return insert(offset, String.valueOf(i));
522 }
523
524 /**
525 * @throws StringIndexOutOfBoundsException {@inheritDoc}
526 * @see java.lang.String#valueOf(long)
527 * @see #insert(int, java.lang.String)
528 * @see #length()
529 */
530 public StringBuffer insert(int offset, long l) {
531 return insert(offset, String.valueOf(l));
532 }
533
534 /**
535 * @throws StringIndexOutOfBoundsException {@inheritDoc}
536 * @see java.lang.String#valueOf(float)
537 * @see #insert(int, java.lang.String)
538 * @see #length()
539 */
540 public StringBuffer insert(int offset, float f) {
541 return insert(offset, String.valueOf(f));
542 }
543
544 /**
545 * @throws StringIndexOutOfBoundsException {@inheritDoc}
546 * @see java.lang.String#valueOf(double)
547 * @see #insert(int, java.lang.String)
548 * @see #length()
549 */
550 public StringBuffer insert(int offset, double d) {
551 return insert(offset, String.valueOf(d));
552 }
553
554 /**
555 * @throws NullPointerException {@inheritDoc}
556 * @since 1.4
557 */
558 public int indexOf(String str) {
559 return indexOf(str, 0);
560 }
561
562 /**
563 * @throws NullPointerException {@inheritDoc}
564 * @since 1.4
565 */
566 public synchronized int indexOf(String str, int fromIndex) {
567 return String.indexOf(value, 0, count, str.toCharArray(), 0,
568 str.length(), fromIndex);
569 }
570
571 /**
572 * @throws NullPointerException {@inheritDoc}
573 * @since 1.4
574 */
575 public int lastIndexOf(String str) {
576 // Note, synchronization achieved via other invocations
577 return lastIndexOf(str, count);
578 }
579
580 /**
581 * @throws NullPointerException {@inheritDoc}
582 * @since 1.4
583 */
584 public synchronized int lastIndexOf(String str, int fromIndex) {
585 return String.lastIndexOf(value, 0, count, str.toCharArray(),
586 0, str.length(), fromIndex);
587 }
588
589 /**
590 * @since JDK1.0.2
591 */
592 public synchronized StringBuffer reverse() {
593 super .reverse();
594 return this ;
595 }
596
597 public synchronized String toString() {
598 return new String(value, 0, count);
599 }
600
601 /**
602 * Serializable fields for StringBuffer.
603 *
604 * @serialField value char[]
605 * The backing character array of this StringBuffer.
606 * @serialField count int
607 * The number of characters in this StringBuffer.
608 * @serialField shared boolean
609 * A flag indicating whether the backing array is shared.
610 * The value is ignored upon deserialization.
611 */
612 private static final java.io.ObjectStreamField[] serialPersistentFields = {
613 new java.io.ObjectStreamField("value", char[].class),
614 new java.io.ObjectStreamField("count", Integer.TYPE),
615 new java.io.ObjectStreamField("shared", Boolean.TYPE), };
616
617 /**
618 * readObject is called to restore the state of the StringBuffer from
619 * a stream.
620 */
621 private synchronized void writeObject(java.io.ObjectOutputStream s)
622 throws java.io.IOException {
623 java.io.ObjectOutputStream.PutField fields = s.putFields();
624 fields.put("value", value);
625 fields.put("count", count);
626 fields.put("shared", false);
627 s.writeFields();
628 }
629
630 /**
631 * readObject is called to restore the state of the StringBuffer from
632 * a stream.
633 */
634 private void readObject(java.io.ObjectInputStream s)
635 throws java.io.IOException, ClassNotFoundException {
636 java.io.ObjectInputStream.GetField fields = s.readFields();
637 value = (char[]) fields.get("value", null);
638 count = (int) fields.get("count", 0);
639 }
640 }
|