001    /* StringBuffer.java -- Growable strings
002       Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2008
003       Free Software Foundation, Inc.
004    
005    This file is part of GNU Classpath.
006    
007    GNU Classpath is free software; you can redistribute it and/or modify
008    it under the terms of the GNU General Public License as published by
009    the Free Software Foundation; either version 2, or (at your option)
010    any later version.
011    
012    GNU Classpath is distributed in the hope that it will be useful, but
013    WITHOUT ANY WARRANTY; without even the implied warranty of
014    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015    General Public License for more details.
016    
017    You should have received a copy of the GNU General Public License
018    along with GNU Classpath; see the file COPYING.  If not, write to the
019    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
020    02110-1301 USA.
021    
022    Linking this library statically or dynamically with other modules is
023    making a combined work based on this library.  Thus, the terms and
024    conditions of the GNU General Public License cover the whole
025    combination.
026    
027    As a special exception, the copyright holders of this library give you
028    permission to link this library with independent modules to produce an
029    executable, regardless of the license terms of these independent
030    modules, and to copy and distribute the resulting executable under
031    terms of your choice, provided that you also meet, for each linked
032    independent module, the terms and conditions of the license of that
033    module.  An independent module is a module which is not derived from
034    or based on this library.  If you modify this library, you may extend
035    this exception to your version of the library, but you are not
036    obligated to do so.  If you do not wish to do so, delete this
037    exception statement from your version. */
038    
039    package java.lang;
040    
041    import java.io.Serializable;
042    
043    /**
044     * <code>StringBuffer</code> represents a changeable <code>String</code>.
045     * It provides the operations required to modify the
046     * <code>StringBuffer</code>, including insert, replace, delete, append,
047     * and reverse. It is thread-safe; meaning that all modifications to a buffer
048     * are in synchronized methods.
049     *
050     * <p><code>StringBuffer</code>s are variable-length in nature, so even if
051     * you initialize them to a certain size, they can still grow larger than
052     * that. <em>Capacity</em> indicates the number of characters the
053     * <code>StringBuffer</code> can have in it before it has to grow (growing
054     * the char array is an expensive operation involving <code>new</code>).
055     *
056     * <p>Incidentally, compilers often implement the String operator "+"
057     * by using a <code>StringBuffer</code> operation:<br>
058     * <code>a + b</code><br>
059     * is the same as<br>
060     * <code>new StringBuffer().append(a).append(b).toString()</code>.
061     *
062     * <p>Classpath's StringBuffer is capable of sharing memory with Strings for
063     * efficiency.  This will help when a StringBuffer is converted to a String
064     * and the StringBuffer is not changed after that (quite common when performing
065     * string concatenation).
066     *
067     * @author Paul Fisher
068     * @author John Keiser
069     * @author Tom Tromey
070     * @author Eric Blake (ebb9@email.byu.edu)
071     * @see String
072     * @since 1.0
073     * @status updated to 1.4
074     */
075    public final class StringBuffer
076      extends AbstractStringBuffer
077      implements Serializable, CharSequence, Appendable
078    {
079      // Implementation note: if you change this class, you usually will
080      // want to change StringBuilder as well.
081    
082      /**
083       * Compatible with JDK 1.0+.
084       */
085      private static final long serialVersionUID = 3388685877147921107L;
086    
087      /**
088       * True if the buffer is shared with another object (StringBuffer or
089       * String); this means the buffer must be copied before writing to it again.
090       * Note that this has permissions set this way so that String can get the
091       * value.
092       *
093       * @serial whether the buffer is shared
094       */
095      boolean shared;
096    
097      /**
098       * Create a new StringBuffer with default capacity 16.
099       */
100      public StringBuffer()
101      {
102        super();
103      }
104    
105      /**
106       * Create an empty <code>StringBuffer</code> with the specified initial
107       * capacity.
108       *
109       * @param capacity the initial capacity
110       * @throws NegativeArraySizeException if capacity is negative
111       */
112      public StringBuffer(int capacity)
113      {
114        super(capacity);
115      }
116    
117      /**
118       * Create a new <code>StringBuffer</code> with the characters in the
119       * specified <code>String</code>. Initial capacity will be the size of the
120       * String plus 16.
121       *
122       * @param str the <code>String</code> to convert
123       * @throws NullPointerException if str is null
124       */
125      public StringBuffer(String str)
126      {
127        // Unfortunately, because the size is 16 larger, we cannot share.
128        super(str);
129      }
130    
131      /**
132       * Create a new <code>StringBuffer</code> with the characters in the
133       * specified <code>CharSequence</code>. Initial capacity will be the
134       * length of the sequence plus 16; if the sequence reports a length
135       * less than or equal to 0, then the initial capacity will be 16.
136       *
137       * @param seq the initializing <code>CharSequence</code>
138       * @throws NullPointerException if str is null
139       * @since 1.5
140       */
141      public StringBuffer(CharSequence seq)
142      {
143        super(seq);
144      }
145    
146      /**
147       * Get the length of the <code>String</code> this <code>StringBuffer</code>
148       * would create. Not to be confused with the <em>capacity</em> of the
149       * <code>StringBuffer</code>.
150       *
151       * @return the length of this <code>StringBuffer</code>
152       * @see #capacity()
153       * @see #setLength(int)
154       */
155      public synchronized int length()
156      {
157        return count;
158      }
159    
160      /**
161       * Get the total number of characters this <code>StringBuffer</code> can
162       * support before it must be grown.  Not to be confused with <em>length</em>.
163       *
164       * @return the capacity of this <code>StringBuffer</code>
165       * @see #length()
166       * @see #ensureCapacity(int)
167       */
168      public synchronized int capacity()
169      {
170        return value.length;
171      }
172    
173      /**
174       * Increase the capacity of this <code>StringBuffer</code>. This will
175       * ensure that an expensive growing operation will not occur until
176       * <code>minimumCapacity</code> is reached. The buffer is grown to the
177       * larger of <code>minimumCapacity</code> and
178       * <code>capacity() * 2 + 2</code>, if it is not already large enough.
179       *
180       * @param minimumCapacity the new capacity
181       * @see #capacity()
182       */
183      public synchronized void ensureCapacity(int minimumCapacity)
184      {
185        ensureCapacity_unsynchronized(minimumCapacity);
186      }
187    
188      /**
189       * Set the length of this StringBuffer. If the new length is greater than
190       * the current length, all the new characters are set to '\0'. If the new
191       * length is less than the current length, the first <code>newLength</code>
192       * characters of the old array will be preserved, and the remaining
193       * characters are truncated.
194       *
195       * @param newLength the new length
196       * @throws IndexOutOfBoundsException if the new length is negative
197       *         (while unspecified, this is a StringIndexOutOfBoundsException)
198       * @see #length()
199       */
200      public synchronized void setLength(int newLength)
201      {
202        super.setLength(newLength);
203      }
204    
205      /**
206       * Get the character at the specified index.
207       *
208       * @param index the index of the character to get, starting at 0
209       * @return the character at the specified index
210       * @throws IndexOutOfBoundsException if index is negative or &gt;= length()
211       *         (while unspecified, this is a StringIndexOutOfBoundsException)
212       */
213      public synchronized char charAt(int index)
214      {
215        return super.charAt(index);
216      }
217    
218      /**
219       * Get the code point at the specified index.  This is like #charAt(int),
220       * but if the character is the start of a surrogate pair, and the
221       * following character completes the pair, then the corresponding
222       * supplementary code point is returned.
223       * @param index the index of the codepoint to get, starting at 0
224       * @return the codepoint at the specified index
225       * @throws IndexOutOfBoundsException if index is negative or &gt;= length()
226       * @since 1.5
227       */
228      public synchronized int codePointAt(int index)
229      {
230        return super.codePointAt(index);
231      }
232    
233      /**
234       * Get the code point before the specified index.  This is like
235       * #codePointAt(int), but checks the characters at <code>index-1</code> and
236       * <code>index-2</code> to see if they form a supplementary code point.
237       * @param index the index just past the codepoint to get, starting at 0
238       * @return the codepoint at the specified index
239       * @throws IndexOutOfBoundsException if index is negative or &gt;= length()
240       * @since 1.5
241       */
242      public synchronized int codePointBefore(int index)
243      {
244        return super.codePointBefore(index);
245      }
246    
247      /**
248       * Get the specified array of characters. <code>srcOffset - srcEnd</code>
249       * characters will be copied into the array you pass in.
250       *
251       * @param srcOffset the index to start copying from (inclusive)
252       * @param srcEnd the index to stop copying from (exclusive)
253       * @param dst the array to copy into
254       * @param dstOffset the index to start copying into
255       * @throws NullPointerException if dst is null
256       * @throws IndexOutOfBoundsException if any source or target indices are
257       *         out of range (while unspecified, source problems cause a
258       *         StringIndexOutOfBoundsException, and dest problems cause an
259       *         ArrayIndexOutOfBoundsException)
260       * @see System#arraycopy(Object, int, Object, int, int)
261       */
262      public synchronized void getChars(int srcOffset, int srcEnd,
263                                        char[] dst, int dstOffset)
264      {
265        super.getChars(srcOffset, srcEnd, dst, dstOffset);
266      }
267    
268      /**
269       * Set the character at the specified index.
270       *
271       * @param index the index of the character to set starting at 0
272       * @param ch the value to set that character to
273       * @throws IndexOutOfBoundsException if index is negative or &gt;= length()
274       *         (while unspecified, this is a StringIndexOutOfBoundsException)
275       */
276      public synchronized void setCharAt(int index, char ch)
277      {
278        super.setCharAt(index, ch);
279      }
280    
281      /**
282       * Append the <code>String</code> value of the argument to this
283       * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert
284       * to <code>String</code>.
285       *
286       * @param obj the <code>Object</code> to convert and append
287       * @return this <code>StringBuffer</code>
288       * @see String#valueOf(Object)
289       * @see #append(String)
290       */
291      public synchronized StringBuffer append(Object obj)
292      {
293        super.append(obj);
294        return this;
295      }
296    
297      /**
298       * Append the <code>String</code> to this <code>StringBuffer</code>. If
299       * str is null, the String "null" is appended.
300       *
301       * @param str the <code>String</code> to append
302       * @return this <code>StringBuffer</code>
303       */
304      public synchronized StringBuffer append(String str)
305      {
306        super.append(str);
307        return this;
308      }
309    
310      /**
311       * Append the <code>StringBuffer</code> value of the argument to this
312       * <code>StringBuffer</code>. This behaves the same as
313       * <code>append((Object) stringBuffer)</code>, except it is more efficient.
314       *
315       * @param stringBuffer the <code>StringBuffer</code> to convert and append
316       * @return this <code>StringBuffer</code>
317       * @see #append(Object)
318       * @since 1.4
319       */
320      public synchronized StringBuffer append(StringBuffer stringBuffer)
321      {
322        super.append(stringBuffer);
323        return this;
324      }
325    
326      /**
327       * Append the <code>char</code> array to this <code>StringBuffer</code>.
328       * This is similar (but more efficient) than
329       * <code>append(new String(data))</code>, except in the case of null.
330       *
331       * @param data the <code>char[]</code> to append
332       * @return this <code>StringBuffer</code>
333       * @throws NullPointerException if <code>str</code> is <code>null</code>
334       * @see #append(char[], int, int)
335       */
336      public synchronized StringBuffer append(char[] data)
337      {
338        super.append(data, 0, data.length);
339        return this;
340      }
341    
342      /**
343       * Append part of the <code>char</code> array to this
344       * <code>StringBuffer</code>. This is similar (but more efficient) than
345       * <code>append(new String(data, offset, count))</code>, except in the case
346       * of null.
347       *
348       * @param data the <code>char[]</code> to append
349       * @param offset the start location in <code>str</code>
350       * @param count the number of characters to get from <code>str</code>
351       * @return this <code>StringBuffer</code>
352       * @throws NullPointerException if <code>str</code> is <code>null</code>
353       * @throws IndexOutOfBoundsException if offset or count is out of range
354       *         (while unspecified, this is a StringIndexOutOfBoundsException)
355       */
356      public synchronized StringBuffer append(char[] data, int offset, int count)
357      {
358        super.append(data, offset, count);
359        return this;
360      }
361    
362      /**
363       * Append the <code>String</code> value of the argument to this
364       * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert
365       * to <code>String</code>.
366       *
367       * @param bool the <code>boolean</code> to convert and append
368       * @return this <code>StringBuffer</code>
369       * @see String#valueOf(boolean)
370       */
371      public synchronized StringBuffer append(boolean bool)
372      {
373        super.append(bool);
374        return this;
375      }
376    
377      /**
378       * Append the <code>char</code> to this <code>StringBuffer</code>.
379       *
380       * @param ch the <code>char</code> to append
381       * @return this <code>StringBuffer</code>
382       */
383      public synchronized StringBuffer append(char ch)
384      {
385        super.append(ch);
386        return this;
387      }
388    
389      /**
390       * Append the characters in the <code>CharSequence</code> to this
391       * buffer.
392       *
393       * @param seq the <code>CharSequence</code> providing the characters
394       * @return this <code>StringBuffer</code>
395       * @since 1.5
396       */
397      public synchronized StringBuffer append(CharSequence seq)
398      {
399        super.append(seq, 0, seq.length());
400        return this;
401      }
402    
403      /**
404       * Append some characters from the <code>CharSequence</code> to this
405       * buffer.  If the argument is null, the four characters "null" are
406       * appended.
407       *
408       * @param seq the <code>CharSequence</code> providing the characters
409       * @param start the starting index
410       * @param end one past the final index
411       * @return this <code>StringBuffer</code>
412       * @since 1.5
413       */
414      public synchronized StringBuffer append(CharSequence seq, int start, int end)
415      {
416        super.append(seq, start, end);
417        return this;
418      }
419    
420      /**
421       * Append the <code>String</code> value of the argument to this
422       * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert
423       * to <code>String</code>.
424       *
425       * @param inum the <code>int</code> to convert and append
426       * @return this <code>StringBuffer</code>
427       * @see String#valueOf(int)
428       */
429      // This is native in libgcj, for efficiency.
430      public synchronized StringBuffer append(int inum)
431      {
432        super.append(inum);
433        return this;
434      }
435    
436      /**
437       * Append the <code>String</code> value of the argument to this
438       * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert
439       * to <code>String</code>.
440       *
441       * @param lnum the <code>long</code> to convert and append
442       * @return this <code>StringBuffer</code>
443       * @see String#valueOf(long)
444       */
445      public synchronized StringBuffer append(long lnum)
446      {
447        super.append(lnum);
448        return this;
449      }
450    
451      /**
452       * Append the <code>String</code> value of the argument to this
453       * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert
454       * to <code>String</code>.
455       *
456       * @param fnum the <code>float</code> to convert and append
457       * @return this <code>StringBuffer</code>
458       * @see String#valueOf(float)
459       */
460      public synchronized StringBuffer append(float fnum)
461      {
462        super.append(fnum);
463        return this;
464      }
465    
466      /**
467       * Append the <code>String</code> value of the argument to this
468       * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert
469       * to <code>String</code>.
470       *
471       * @param dnum the <code>double</code> to convert and append
472       * @return this <code>StringBuffer</code>
473       * @see String#valueOf(double)
474       */
475      public synchronized StringBuffer append(double dnum)
476      {
477        super.append(dnum);
478        return this;
479      }
480    
481      /**
482       * Append the code point to this <code>StringBuffer</code>.
483       * This is like #append(char), but will append two characters
484       * if a supplementary code point is given.
485       *
486       * @param code the code point to append
487       * @return this <code>StringBuffer</code>
488       * @see Character#toChars(int, char[], int)
489       * @since 1.5
490       */
491      public synchronized StringBuffer appendCodePoint(int code)
492      {
493        super.appendCodePoint(code);
494        return this;
495      }
496    
497      /**
498       * Delete characters from this <code>StringBuffer</code>.
499       * <code>delete(10, 12)</code> will delete 10 and 11, but not 12. It is
500       * harmless for end to be larger than length().
501       *
502       * @param start the first character to delete
503       * @param end the index after the last character to delete
504       * @return this <code>StringBuffer</code>
505       * @throws StringIndexOutOfBoundsException if start or end are out of bounds
506       * @since 1.2
507       */
508      public synchronized StringBuffer delete(int start, int end)
509      {
510        // This will unshare if required.
511        super.delete(start, end);
512        return this;
513      }
514    
515      /**
516       * Delete a character from this <code>StringBuffer</code>.
517       *
518       * @param index the index of the character to delete
519       * @return this <code>StringBuffer</code>
520       * @throws StringIndexOutOfBoundsException if index is out of bounds
521       * @since 1.2
522       */
523      public synchronized StringBuffer deleteCharAt(int index)
524      {
525        super.deleteCharAt(index);
526        return this;
527      }
528    
529      /**
530       * Replace characters between index <code>start</code> (inclusive) and
531       * <code>end</code> (exclusive) with <code>str</code>. If <code>end</code>
532       * is larger than the size of this StringBuffer, all characters after
533       * <code>start</code> are replaced.
534       *
535       * @param start the beginning index of characters to delete (inclusive)
536       * @param end the ending index of characters to delete (exclusive)
537       * @param str the new <code>String</code> to insert
538       * @return this <code>StringBuffer</code>
539       * @throws StringIndexOutOfBoundsException if start or end are out of bounds
540       * @throws NullPointerException if str is null
541       * @since 1.2
542       */
543      public synchronized StringBuffer replace(int start, int end, String str)
544      {
545        super.replace(start, end, str);
546        return this;
547      }
548    
549      /**
550       * Creates a substring of this StringBuffer, starting at a specified index
551       * and ending at the end of this StringBuffer.
552       *
553       * @param beginIndex index to start substring (base 0)
554       * @return new String which is a substring of this StringBuffer
555       * @throws StringIndexOutOfBoundsException if beginIndex is out of bounds
556       * @see #substring(int, int)
557       * @since 1.2
558       */
559      public String substring(int beginIndex)
560      {
561        return substring(beginIndex, count);
562      }
563    
564      /**
565       * Creates a substring of this StringBuffer, starting at a specified index
566       * and ending at one character before a specified index. This is implemented
567       * the same as <code>substring(beginIndex, endIndex)</code>, to satisfy
568       * the CharSequence interface.
569       *
570       * @param beginIndex index to start at (inclusive, base 0)
571       * @param endIndex index to end at (exclusive)
572       * @return new String which is a substring of this StringBuffer
573       * @throws IndexOutOfBoundsException if beginIndex or endIndex is out of
574       *         bounds
575       * @see #substring(int, int)
576       * @since 1.4
577       */
578      public CharSequence subSequence(int beginIndex, int endIndex)
579      {
580        return substring(beginIndex, endIndex);
581      }
582    
583      /**
584       * Creates a substring of this StringBuffer, starting at a specified index
585       * and ending at one character before a specified index.
586       *
587       * @param beginIndex index to start at (inclusive, base 0)
588       * @param endIndex index to end at (exclusive)
589       * @return new String which is a substring of this StringBuffer
590       * @throws StringIndexOutOfBoundsException if beginIndex or endIndex is out
591       *         of bounds
592       * @since 1.2
593       */
594      public synchronized String substring(int beginIndex, int endIndex)
595      {
596        int len = endIndex - beginIndex;
597        if (beginIndex < 0 || endIndex > count || endIndex < beginIndex)
598          throw new StringIndexOutOfBoundsException();
599        if (len == 0)
600          return "";
601        // Don't copy unless substring is smaller than 1/4 of the buffer.
602        boolean share_buffer = ((len << 2) >= value.length);
603        if (share_buffer)
604          this.shared = true;
605        // Package constructor avoids an array copy.
606        return new String(value, beginIndex, len, share_buffer);
607      }
608    
609      /**
610       * Insert a subarray of the <code>char[]</code> argument into this
611       * <code>StringBuffer</code>.
612       *
613       * @param offset the place to insert in this buffer
614       * @param str the <code>char[]</code> to insert
615       * @param str_offset the index in <code>str</code> to start inserting from
616       * @param len the number of characters to insert
617       * @return this <code>StringBuffer</code>
618       * @throws NullPointerException if <code>str</code> is <code>null</code>
619       * @throws StringIndexOutOfBoundsException if any index is out of bounds
620       * @since 1.2
621       */
622      public synchronized StringBuffer insert(int offset,
623                                              char[] str, int str_offset, int len)
624      {
625        super.insert(offset, str, str_offset, len);
626        return this;
627      }
628    
629      /**
630       * Insert the <code>String</code> value of the argument into this
631       * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert
632       * to <code>String</code>.
633       *
634       * @param offset the place to insert in this buffer
635       * @param obj the <code>Object</code> to convert and insert
636       * @return this <code>StringBuffer</code>
637       * @exception StringIndexOutOfBoundsException if offset is out of bounds
638       * @see String#valueOf(Object)
639       */
640      public synchronized StringBuffer insert(int offset, Object obj)
641      {
642        super.insert(offset, obj);
643        return this;
644      }
645    
646      /**
647       * Insert the <code>String</code> argument into this
648       * <code>StringBuffer</code>. If str is null, the String "null" is used
649       * instead.
650       *
651       * @param offset the place to insert in this buffer
652       * @param str the <code>String</code> to insert
653       * @return this <code>StringBuffer</code>
654       * @throws StringIndexOutOfBoundsException if offset is out of bounds
655       */
656      public synchronized StringBuffer insert(int offset, String str)
657      {
658        super.insert(offset, str);
659        return this;
660      }
661    
662      /**
663       * Insert the <code>CharSequence</code> argument into this
664       * <code>StringBuffer</code>.  If the sequence is null, the String
665       * "null" is used instead.
666       *
667       * @param offset the place to insert in this buffer
668       * @param sequence the <code>CharSequence</code> to insert
669       * @return this <code>StringBuffer</code>
670       * @throws IndexOutOfBoundsException if offset is out of bounds
671       * @since 1.5
672       */
673      public synchronized StringBuffer insert(int offset, CharSequence sequence)
674      {
675        super.insert(offset, sequence);
676        return this;
677      }
678    
679      /**
680       * Insert a subsequence of the <code>CharSequence</code> argument into this
681       * <code>StringBuffer</code>.  If the sequence is null, the String
682       * "null" is used instead.
683       *
684       * @param offset the place to insert in this buffer
685       * @param sequence the <code>CharSequence</code> to insert
686       * @param start the starting index of the subsequence
687       * @param end one past the ending index of the subsequence
688       * @return this <code>StringBuffer</code>
689       * @throws IndexOutOfBoundsException if offset, start,
690       * or end are out of bounds
691       * @since 1.5
692       */
693      public synchronized StringBuffer insert(int offset, CharSequence sequence,
694                                              int start, int end)
695      {
696        super.insert(offset, sequence, start, end);
697        return this;
698      }
699    
700      /**
701       * Insert the <code>char[]</code> argument into this
702       * <code>StringBuffer</code>.
703       *
704       * @param offset the place to insert in this buffer
705       * @param data the <code>char[]</code> to insert
706       * @return this <code>StringBuffer</code>
707       * @throws NullPointerException if <code>data</code> is <code>null</code>
708       * @throws StringIndexOutOfBoundsException if offset is out of bounds
709       * @see #insert(int, char[], int, int)
710       */
711      public synchronized StringBuffer insert(int offset, char[] data)
712      {
713        super.insert(offset, data, 0, data.length);
714        return this;
715      }
716    
717      /**
718       * Insert the <code>String</code> value of the argument into this
719       * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert
720       * to <code>String</code>.
721       *
722       * @param offset the place to insert in this buffer
723       * @param bool the <code>boolean</code> to convert and insert
724       * @return this <code>StringBuffer</code>
725       * @throws StringIndexOutOfBoundsException if offset is out of bounds
726       * @see String#valueOf(boolean)
727       */
728      public synchronized StringBuffer insert(int offset, boolean bool)
729      {
730        super.insert(offset, bool);
731        return this;
732      }
733    
734      /**
735       * Insert the <code>char</code> argument into this <code>StringBuffer</code>.
736       *
737       * @param offset the place to insert in this buffer
738       * @param ch the <code>char</code> to insert
739       * @return this <code>StringBuffer</code>
740       * @throws StringIndexOutOfBoundsException if offset is out of bounds
741       */
742      public synchronized StringBuffer insert(int offset, char ch)
743      {
744        super.insert(offset, ch);
745        return this;
746      }
747    
748      /**
749       * Insert the <code>String</code> value of the argument into this
750       * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert
751       * to <code>String</code>.
752       *
753       * @param offset the place to insert in this buffer
754       * @param inum the <code>int</code> to convert and insert
755       * @return this <code>StringBuffer</code>
756       * @throws StringIndexOutOfBoundsException if offset is out of bounds
757       * @see String#valueOf(int)
758       */
759      public synchronized StringBuffer insert(int offset, int inum)
760      {
761        super.insert(offset, inum);
762        return this;
763      }
764    
765      /**
766       * Insert the <code>String</code> value of the argument into this
767       * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert
768       * to <code>String</code>.
769       *
770       * @param offset the place to insert in this buffer
771       * @param lnum the <code>long</code> to convert and insert
772       * @return this <code>StringBuffer</code>
773       * @throws StringIndexOutOfBoundsException if offset is out of bounds
774       * @see String#valueOf(long)
775       */
776      public synchronized StringBuffer insert(int offset, long lnum)
777      {
778        super.insert(offset, lnum);
779        return this;
780      }
781    
782      /**
783       * Insert the <code>String</code> value of the argument into this
784       * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert
785       * to <code>String</code>.
786       *
787       * @param offset the place to insert in this buffer
788       * @param fnum the <code>float</code> to convert and insert
789       * @return this <code>StringBuffer</code>
790       * @throws StringIndexOutOfBoundsException if offset is out of bounds
791       * @see String#valueOf(float)
792       */
793      public synchronized StringBuffer insert(int offset, float fnum)
794      {
795        super.insert(offset, fnum);
796        return this;
797      }
798    
799      /**
800       * Insert the <code>String</code> value of the argument into this
801       * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert
802       * to <code>String</code>.
803       *
804       * @param offset the place to insert in this buffer
805       * @param dnum the <code>double</code> to convert and insert
806       * @return this <code>StringBuffer</code>
807       * @throws StringIndexOutOfBoundsException if offset is out of bounds
808       * @see String#valueOf(double)
809       */
810      public synchronized StringBuffer insert(int offset, double dnum)
811      {
812        super.insert(offset, dnum);
813        return this;
814      }
815    
816      /**
817       * Finds the first instance of a substring in this StringBuffer.
818       *
819       * @param str String to find
820       * @return location (base 0) of the String, or -1 if not found
821       * @throws NullPointerException if str is null
822       * @see #indexOf(String, int)
823       * @since 1.4
824       */
825      public synchronized int indexOf(String str)
826      {
827        return super.indexOf(str, 0);
828      }
829    
830      /**
831       * Finds the first instance of a String in this StringBuffer, starting at
832       * a given index.  If starting index is less than 0, the search starts at
833       * the beginning of this String.  If the starting index is greater than the
834       * length of this String, or the substring is not found, -1 is returned.
835       *
836       * @param str String to find
837       * @param fromIndex index to start the search
838       * @return location (base 0) of the String, or -1 if not found
839       * @throws NullPointerException if str is null
840       * @since 1.4
841       */
842      public synchronized int indexOf(String str, int fromIndex)
843      {
844        return super.indexOf(str, fromIndex);
845      }
846    
847      /**
848       * Finds the last instance of a substring in this StringBuffer.
849       *
850       * @param str String to find
851       * @return location (base 0) of the String, or -1 if not found
852       * @throws NullPointerException if str is null
853       * @see #lastIndexOf(String, int)
854       * @since 1.4
855       */
856      public synchronized int lastIndexOf(String str)
857      {
858        return super.lastIndexOf(str, count - str.count);
859      }
860    
861      /**
862       * Finds the last instance of a String in this StringBuffer, starting at a
863       * given index.  If starting index is greater than the maximum valid index,
864       * then the search begins at the end of this String.  If the starting index
865       * is less than zero, or the substring is not found, -1 is returned.
866       *
867       * @param str String to find
868       * @param fromIndex index to start the search
869       * @return location (base 0) of the String, or -1 if not found
870       * @throws NullPointerException if str is null
871       * @since 1.4
872       */
873      public synchronized int lastIndexOf(String str, int fromIndex)
874      {
875        return super.lastIndexOf(str, fromIndex);
876      }
877    
878      /**
879       * Reverse the characters in this StringBuffer. The same sequence of
880       * characters exists, but in the reverse index ordering.
881       *
882       * @return this <code>StringBuffer</code>
883       */
884      public synchronized StringBuffer reverse()
885      {
886        super.reverse();
887        return this;
888      }
889    
890      /**
891       * Convert this <code>StringBuffer</code> to a <code>String</code>. The
892       * String is composed of the characters currently in this StringBuffer. Note
893       * that the result is a copy, and that future modifications to this buffer
894       * do not affect the String.
895       *
896       * @return the characters in this StringBuffer
897       */
898      public String toString()
899      {
900        // The string will set this.shared = true.
901        return new String(this);
902      }
903    
904      /**
905       * This may reduce the amount of memory used by the StringBuffer,
906       * by resizing the internal array to remove unused space.  However,
907       * this method is not required to resize, so this behavior cannot
908       * be relied upon.
909       * @since 1.5
910       */
911      public synchronized void trimToSize()
912      {
913        super.trimToSize();
914      }
915    
916      /**
917       * Return the number of code points between two indices in the
918       * <code>StringBuffer</code>.  An unpaired surrogate counts as a
919       * code point for this purpose.  Characters outside the indicated
920       * range are not examined, even if the range ends in the middle of a
921       * surrogate pair.
922       *
923       * @param start the starting index
924       * @param end one past the ending index
925       * @return the number of code points
926       * @since 1.5
927       */
928      public synchronized int codePointCount(int start, int end)
929      {
930        return super.codePointCount(start, end);
931      }
932    
933      /**
934       * Starting at the given index, this counts forward by the indicated
935       * number of code points, and then returns the resulting index.  An
936       * unpaired surrogate counts as a single code point for this
937       * purpose.
938       *
939       * @param start the starting index
940       * @param codePoints the number of code points
941       * @return the resulting index
942       * @since 1.5
943       */
944      public synchronized int offsetByCodePoints(int start, int codePoints)
945      {
946        return super.offsetByCodePoints(start, codePoints);
947      }
948    
949      /**
950       * An unsynchronized version of ensureCapacity, used internally to avoid
951       * the cost of a second lock on the same object. This also has the side
952       * effect of duplicating the array, if it was shared (to form copy-on-write
953       * semantics).
954       *
955       * @param minimumCapacity the minimum capacity
956       * @see #ensureCapacity(int)
957       */
958      void ensureCapacity_unsynchronized(int minimumCapacity)
959      {
960        if (shared || minimumCapacity > value.length)
961          {
962            // We don't want to make a larger vector when `shared' is
963            // set.  If we do, then setLength becomes very inefficient
964            // when repeatedly reusing a StringBuffer in a loop.
965            int max = (minimumCapacity > value.length
966                       ? value.length * 2 + 2
967                       : value.length);
968            minimumCapacity = (minimumCapacity < max ? max : minimumCapacity);
969            char[] nb = new char[minimumCapacity];
970            System.arraycopy(value, 0, nb, 0, count);
971            value = nb;
972            shared = false;
973          }
974      }
975    
976    }