java.lang.StringBuffer

  1 package java.lang;
  2 
  3 /**
  4  * A thread-safe, mutable sequence of characters. A string buffer is like a
  5  * {@link String}, but can be modified. At any point in time it contains some
  6  * particular sequence of characters, but the length and content of the sequence
  7  * can be changed through certain method calls.
  8  * <p>
  9  * String buffers are safe for use by multiple threads. The methods are
 10  * synchronized where necessary so that all the operations on any particular
 11  * instance behave as if they occur in some serial order that is consistent with
 12  * the order of the method calls made by each of the individual threads
 13  * involved.
 14  * <p>
 15  * The principal operations on a <code>StringBuffer</code> are the
 16  * <code>append</code> and <code>insert</code> methods, which are overloaded so
 17  * as to accept data of any type. Each effectively converts a given datum to a
 18  * string and then appends or inserts the characters of that string to the
 19  * string buffer. The <code>append</code> method always adds these characters at
 20  * the end of the buffer; the <code>insert</code> method adds the characters at
 21  * a specified point.
 22  * <p>
 23  * For example, if <code>z</code> refers to a string buffer object whose current
 24  * contents are "<code>start</code>", then the method call
 25  * <code>z.append("le")</code> would cause the string buffer to contain "
 26  * <code>startle</code>", whereas <code>z.insert(4, "le")</code> would alter the
 27  * string buffer to contain "<code>starlet</code>".
 28  * <p>
 29  * In general, if sb refers to an instance of a <code>StringBuffer</code>, then
 30  * <code>sb.append(x)</code> has the same effect as
 31  * <code>sb.insert(sb.length(),&nbsp;x)</code>.
 32  * <p>
 33  * Whenever an operation occurs involving a source sequence (such as appending
 34  * or inserting from a source sequence) this class synchronizes only on the
 35  * string buffer performing the operation, not on the source.
 36  * <p>
 37  * Every string buffer has a capacity. As long as the length of the character
 38  * sequence contained in the string buffer does not exceed the capacity, it is
 39  * not necessary to allocate a new internal buffer array. If the internal buffer
 40  * overflows, it is automatically made larger.
 41  *
 42  * As of release JDK 5, this class has been supplemented with an equivalent
 43  * class designed for use by a single thread, {@link StringBuilder}. The
 44  * <tt>StringBuilder</tt> class should generally be used in preference to this
 45  * one, as it supports all of the same operations but it is faster, as it
 46  * performs no synchronization.
 47  *
 48  * @author Arthur van Hoff
 49  * @version %I%, %G%
 50  * @see java.lang.StringBuilder
 51  * @see java.lang.String
 52  * @since JDK1.0
 53  */
 54 public final class StringBuffer extends AbstractStringBuilder implements
 55         java.io.Serializable, CharSequence {
 56 
 57     /** use serialVersionUID from JDK 1.0.2 for interoperability */
 58     static final long serialVersionUID = 3388685877147921107L;
 59 
 60     /**
 61      * Constructs a string buffer with no characters in it and an initial
 62      * capacity of 16 characters.
 63      */
 64     public StringBuffer() {
 65         super(16);
 66     }
 67 
 68     /**
 69      * Constructs a string buffer with no characters in it and the specified
 70      * initial capacity.
 71      *
 72      * @param capacity
 73      *            the initial capacity.
 74      * @exception NegativeArraySizeException
 75      *                if the <code>capacity</code> argument is less than
 76      *                <code>0</code>.
 77      */
 78     public StringBuffer(int capacity) {
 79         super(capacity);
 80     }
 81 
 82     /**
 83      * Constructs a string buffer initialized to the contents of the specified
 84      * string. The initial capacity of the string buffer is <code>16</code> plus
 85      * the length of the string argument.
 86      *
 87      * @param str
 88      *            the initial contents of the buffer.
 89      * @exception NullPointerException
 90      *                if <code>str</code> is <code>null</code>
 91      */
 92     public StringBuffer(String str) {
 93         super(str.length() + 16);
 94         append(str);
 95     }
 96 
 97     /**
 98      * Constructs a string buffer that contains the same characters as the
 99      * specified <code>CharSequence</code>. The initial capacity of the string
100      * buffer is <code>16</code> plus the length of the
101      * <code>CharSequence</code> argument.
102      * <p>
103      * If the length of the specified <code>CharSequence</code> is less than or
104      * equal to zero, then an empty buffer of capacity <code>16</code> is
105      * returned.
106      *
107      * @param seq
108      *            the sequence to copy.
109      * @exception NullPointerException
110      *                if <code>seq</code> is <code>null</code>
111      * @since 1.5
112      */
113     public StringBuffer(CharSequence seq) {
114         this(seq.length() + 16);
115         append(seq);
116     }
117 
118     public synchronized int length() {
119         return count;
120     }
121 
122     public synchronized int capacity() {
123         return value.length;
124     }
125 
126     public synchronized void ensureCapacity(int minimumCapacity) {
127         if (minimumCapacity > value.length) {
128             expandCapacity(minimumCapacity);
129         }
130     }
131 
132     /**
133      * @since 1.5
134      */
135     public synchronized void trimToSize() {
136         super.trimToSize();
137     }
138 
139     /**
140      * @throws IndexOutOfBoundsException
141      *             {@inheritDoc}
142      * @see #length()
143      */
144     public synchronized void setLength(int newLength) {
145         super.setLength(newLength);
146     }
147 
148     /**
149      * @throws IndexOutOfBoundsException
150      *             {@inheritDoc}
151      * @see #length()
152      */
153     public synchronized char charAt(int index) {
154         if ((index < 0) || (index >= count))
155             throw new StringIndexOutOfBoundsException(index);
156         return value[index];
157     }
158 
159     /**
160      * @since 1.5
161      */
162     public synchronized int codePointAt(int index) {
163         return super.codePointAt(index);
164     }
165 
166     /**
167      * @since 1.5
168      */
169     public synchronized int codePointBefore(int index) {
170         return super.codePointBefore(index);
171     }
172 
173     /**
174      * @since 1.5
175      */
176     public synchronized int codePointCount(int beginIndex, int endIndex) {
177         return super.codePointCount(beginIndex, endIndex);
178     }
179 
180     /**
181      * @since 1.5
182      */
183     public synchronized int offsetByCodePoints(int index, int codePointOffset) {
184         return super.offsetByCodePoints(index, codePointOffset);
185     }
186 
187     /**
188      * @throws NullPointerException
189      *             {@inheritDoc}
190      * @throws IndexOutOfBoundsException
191      *             {@inheritDoc}
192      */
193     public synchronized void getChars(int srcBegin, int srcEnd, char dst[],
194             int dstBegin) {
195         super.getChars(srcBegin, srcEnd, dst, dstBegin);
196     }
197 
198     /**
199      * @throws IndexOutOfBoundsException
200      *             {@inheritDoc}
201      * @see #length()
202      */
203     public synchronized void setCharAt(int index, char ch) {
204         if ((index < 0) || (index >= count))
205             throw new StringIndexOutOfBoundsException(index);
206         value[index] = ch;
207     }
208 
209     /**
210      * @see java.lang.String#valueOf(java.lang.Object)
211      * @see #append(java.lang.String)
212      */
213     public synchronized StringBuffer append(Object obj) {
214         super.append(String.valueOf(obj));
215         return this;
216     }
217 
218     public synchronized StringBuffer append(String str) {
219         super.append(str);
220         return this;
221     }
222 
223     /**
224      * Appends the specified <tt>StringBuffer</tt> to this sequence.
225      * <p>
226      * The characters of the <tt>StringBuffer</tt> argument are appended, in
227      * order, to the contents of this <tt>StringBuffer</tt>, increasing the
228      * length of this <tt>StringBuffer</tt> by the length of the argument. If
229      * <tt>sb</tt> is <tt>null</tt>, then the four characters <tt>"null"</tt>
230      * are appended to this <tt>StringBuffer</tt>.
231      * <p>
232      * Let <i>n</i> be the length of the old character sequence, the one
233      * contained in the <tt>StringBuffer</tt> just prior to execution of the
234      * <tt>append</tt> method. Then the character at index <i>k</i> in the new
235      * character sequence is equal to the character at index <i>k</i> in the old
236      * character sequence, if <i>k</i> is less than <i>n</i>; otherwise, it is
237      * equal to the character at index <i>k-n</i> in the argument
238      * <code>sb</code>.
239      * <p>
240      * This method synchronizes on <code>this</code> (the destination) object
241      * but does not synchronize on the source (<code>sb</code>).
242      *
243      * @param sb
244      *            the <tt>StringBuffer</tt> to append.
245      * @return a reference to this object.
246      * @since 1.4
247      */
248     public synchronized StringBuffer append(StringBuffer sb) {
249         super.append(sb);
250         return this;
251     }
252 
253     /**
254      * Appends the specified <code>CharSequence</code> to this sequence.
255      * <p>
256      * The characters of the <code>CharSequence</code> argument are appended, in
257      * order, increasing the length of this sequence by the length of the
258      * argument.
259      *
260      * <p>
261      * The result of this method is exactly the same as if it were an invocation
262      * of this.append(s, 0, s.length());
263      *
264      * <p>
265      * This method synchronizes on this (the destination) object but does not
266      * synchronize on the source (<code>s</code>).
267      *
268      * <p>
269      * If <code>s</code> is <code>null</code>, then the four characters
270      * <code>"null"</code> are appended.
271      *
272      * @param s
273      *            the <code>CharSequence</code> to append.
274      * @return a reference to this object.
275      * @since 1.5
276      */
277     public StringBuffer append(CharSequence s) {
278         // Note, synchronization achieved via other invocations
279         if (s == null)
280             s = "null";
281         if (s instanceof String)
282             return this.append((String) s);
283         if (s instanceof StringBuffer)
284             return this.append((StringBuffer) s);
285         return this.append(s, 0, s.length());
286     }
287 
288     /**
289      * @throws IndexOutOfBoundsException
290      *             {@inheritDoc}
291      * @since 1.5
292      */
293     public synchronized StringBuffer append(CharSequence s, int start, int end) {
294         super.append(s, start, end);
295         return this;
296     }
297 
298     public synchronized StringBuffer append(char str[]) {
299         super.append(str);
300         return this;
301     }
302 
303     public synchronized StringBuffer append(char str[], int offset, int len) {
304         super.append(str, offset, len);
305         return this;
306     }
307 
308     /**
309      * @see java.lang.String#valueOf(boolean)
310      * @see #append(java.lang.String)
311      */
312     public synchronized StringBuffer append(boolean b) {
313         super.append(b);
314         return this;
315     }
316 
317     public synchronized StringBuffer append(char c) {
318         super.append(c);
319         return this;
320     }
321 
322     /**
323      * @see java.lang.String#valueOf(int)
324      * @see #append(java.lang.String)
325      */
326     public synchronized StringBuffer append(int i) {
327         super.append(i);
328         return this;
329     }
330 
331     /**
332      * @since 1.5
333      */
334     public synchronized StringBuffer appendCodePoint(int codePoint) {
335         super.appendCodePoint(codePoint);
336         return this;
337     }
338 
339     /**
340      * @see java.lang.String#valueOf(long)
341      * @see #append(java.lang.String)
342      */
343     public synchronized StringBuffer append(long lng) {
344         super.append(lng);
345         return this;
346     }
347 
348     /**
349      * @see java.lang.String#valueOf(float)
350      * @see #append(java.lang.String)
351      */
352     public synchronized StringBuffer append(float f) {
353         super.append(f);
354         return this;
355     }
356 
357     /**
358      * @see java.lang.String#valueOf(double)
359      * @see #append(java.lang.String)
360      */
361     public synchronized StringBuffer append(double d) {
362         super.append(d);
363         return this;
364     }
365 
366     /**
367      * @throws StringIndexOutOfBoundsException
368      *             {@inheritDoc}
369      * @since 1.2
370      */
371     public synchronized StringBuffer delete(int start, int end) {
372         super.delete(start, end);
373         return this;
374     }
375 
376     /**
377      * @throws StringIndexOutOfBoundsException
378      *             {@inheritDoc}
379      * @since 1.2
380      */
381     public synchronized StringBuffer deleteCharAt(int index) {
382         super.deleteCharAt(index);
383         return this;
384     }
385 
386     /**
387      * @throws StringIndexOutOfBoundsException
388      *             {@inheritDoc}
389      * @since 1.2
390      */
391     public synchronized StringBuffer replace(int start, int end, String str) {
392         super.replace(start, end, str);
393         return this;
394     }
395 
396     /**
397      * @throws StringIndexOutOfBoundsException
398      *             {@inheritDoc}
399      * @since 1.2
400      */
401     public synchronized String substring(int start) {
402         return substring(start, count);
403     }
404 
405     /**
406      * @throws IndexOutOfBoundsException
407      *             {@inheritDoc}
408      * @since 1.4
409      */
410     public synchronized CharSequence subSequence(int start, int end) {
411         return super.substring(start, end);
412     }
413 
414     /**
415      * @throws StringIndexOutOfBoundsException
416      *             {@inheritDoc}
417      * @since 1.2
418      */
419     public synchronized String substring(int start, int end) {
420         return super.substring(start, end);
421     }
422 
423     /**
424      * @throws StringIndexOutOfBoundsException
425      *             {@inheritDoc}
426      * @since 1.2
427      */
428     public synchronized StringBuffer insert(int index, char str[], int offset,
429             int len) {
430         super.insert(index, str, offset, len);
431         return this;
432     }
433 
434     /**
435      * @throws StringIndexOutOfBoundsException
436      *             {@inheritDoc}
437      * @see java.lang.String#valueOf(java.lang.Object)
438      * @see #insert(int, java.lang.String)
439      * @see #length()
440      */
441     public synchronized StringBuffer insert(int offset, Object obj) {
442         super.insert(offset, String.valueOf(obj));
443         return this;
444     }
445 
446     /**
447      * @throws StringIndexOutOfBoundsException
448      *             {@inheritDoc}
449      * @see #length()
450      */
451     public synchronized StringBuffer insert(int offset, String str) {
452         super.insert(offset, str);
453         return this;
454     }
455 
456     /**
457      * @throws StringIndexOutOfBoundsException
458      *             {@inheritDoc}
459      */
460     public synchronized StringBuffer insert(int offset, char str[]) {
461         super.insert(offset, str);
462         return this;
463     }
464 
465     /**
466      * @throws IndexOutOfBoundsException
467      *             {@inheritDoc}
468      * @since 1.5
469      */
470     public StringBuffer insert(int dstOffset, CharSequence s) {
471         // Note, synchronization achieved via other invocations
472         if (s == null)
473             s = "null";
474         if (s instanceof String)
475             return this.insert(dstOffset, (String) s);
476         return this.insert(dstOffset, s, 0, s.length());
477     }
478 
479     /**
480      * @throws IndexOutOfBoundsException
481      *             {@inheritDoc}
482      * @since 1.5
483      */
484     public synchronized StringBuffer insert(int dstOffset, CharSequence s,
485             int start, int end) {
486         super.insert(dstOffset, s, start, end);
487         return this;
488     }
489 
490     /**
491      * @throws StringIndexOutOfBoundsException
492      *             {@inheritDoc}
493      * @see java.lang.String#valueOf(boolean)
494      * @see #insert(int, java.lang.String)
495      * @see #length()
496      */
497     public StringBuffer insert(int offset, boolean b) {
498         return insert(offset, String.valueOf(b));
499     }
500 
501     /**
502      * @throws IndexOutOfBoundsException
503      *             {@inheritDoc}
504      * @see #length()
505      */
506     public synchronized StringBuffer insert(int offset, char c) {
507         super.insert(offset, c);
508         return this;
509     }
510 
511     /**
512      * @throws StringIndexOutOfBoundsException
513      *             {@inheritDoc}
514      * @see java.lang.String#valueOf(int)
515      * @see #insert(int, java.lang.String)
516      * @see #length()
517      */
518     public StringBuffer insert(int offset, int i) {
519         return insert(offset, String.valueOf(i));
520     }
521 
522     /**
523      * @throws StringIndexOutOfBoundsException
524      *             {@inheritDoc}
525      * @see java.lang.String#valueOf(long)
526      * @see #insert(int, java.lang.String)
527      * @see #length()
528      */
529     public StringBuffer insert(int offset, long l) {
530         return insert(offset, String.valueOf(l));
531     }
532 
533     /**
534      * @throws StringIndexOutOfBoundsException
535      *             {@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
546      *             {@inheritDoc}
547      * @see java.lang.String#valueOf(double)
548      * @see #insert(int, java.lang.String)
549      * @see #length()
550      */
551     public StringBuffer insert(int offset, double d) {
552         return insert(offset, String.valueOf(d));
553     }
554 
555     /**
556      * @throws NullPointerException
557      *             {@inheritDoc}
558      * @since 1.4
559      */
560     public int indexOf(String str) {
561         return indexOf(str, 0);
562     }
563 
564     /**
565      * @throws NullPointerException
566      *             {@inheritDoc}
567      * @since 1.4
568      */
569     public synchronized int indexOf(String str, int fromIndex) {
570         return String.indexOf(value, 0, count, str.toCharArray(), 0,
571                 str.length(), fromIndex);
572     }
573 
574     /**
575      * @throws NullPointerException
576      *             {@inheritDoc}
577      * @since 1.4
578      */
579     public int lastIndexOf(String str) {
580         // Note, synchronization achieved via other invocations
581         return lastIndexOf(str, count);
582     }
583 
584     /**
585      * @throws NullPointerException
586      *             {@inheritDoc}
587      * @since 1.4
588      */
589     public synchronized int lastIndexOf(String str, int fromIndex) {
590         return String.lastIndexOf(value, 0, count, str.toCharArray(), 0,
591                 str.length(), fromIndex);
592     }
593 
594     /**
595      * @since JDK1.0.2
596      */
597     public synchronized StringBuffer reverse() {
598         super.reverse();
599         return this;
600     }
601 
602     public synchronized String toString() {
603         return new String(value, 0, count);
604     }
605 
606     /**
607      * Serializable fields for StringBuffer.
608      * 
609      * @serialField
610      *                  value char[] The backing character array of this
611      *                  StringBuffer.
612      * @serialField
613      *                  count int The number of characters in this StringBuffer.
614      * @serialField
615      *                  shared boolean A flag indicating whether the backing
616      *                  array is shared. The value is ignored upon
617      *                  deserialization.
618      */
619     private static final java.io.ObjectStreamField[] serialPersistentFields = {
620             new java.io.ObjectStreamField("value", char[].class),
621             new java.io.ObjectStreamField("count", Integer.TYPE),
622             new java.io.ObjectStreamField("shared", Boolean.TYPE), };
623 
624     /**
625      * readObject is called to restore the state of the StringBuffer from a
626      * stream.
627      */
628     private synchronized void writeObject(java.io.ObjectOutputStream s)
629             throws java.io.IOException {
630         java.io.ObjectOutputStream.PutField fields = s.putFields();
631         fields.put("value", value);
632         fields.put("count", count);
633         fields.put("shared", false);
634         s.writeFields();
635     }
636 
637     /**
638      * readObject is called to restore the state of the StringBuffer from a
639      * stream.
640      */
641     private void readObject(java.io.ObjectInputStream s)
642             throws java.io.IOException, ClassNotFoundException {
643         java.io.ObjectInputStream.GetField fields = s.readFields();
644         value = (char[]) fields.get("value", null);
645         count = (int) fields.get("count", 0);
646     }
647 }