libjava/java/lang/StringBuffer.java

   1 /* StringBuffer.java -- Growable strings
   2    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2008
   3    Free Software Foundation, Inc.
   4
   5 This file is part of GNU Classpath.
   6
   7 GNU Classpath is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2, or (at your option)
  10 any later version.
  11
  12 GNU Classpath is distributed in the hope that it will be useful, but
  13 WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GNU Classpath; see the file COPYING.  If not, write to the
  19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20 02110-1301 USA.
  21
  22 Linking this library statically or dynamically with other modules is
  23 making a combined work based on this library.  Thus, the terms and
  24 conditions of the GNU General Public License cover the whole
  25 combination.
  26
  27 As a special exception, the copyright holders of this library give you
  28 permission to link this library with independent modules to produce an
  29 executable, regardless of the license terms of these independent
  30 modules, and to copy and distribute the resulting executable under
  31 terms of your choice, provided that you also meet, for each linked
  32 independent module, the terms and conditions of the license of that
  33 module.  An independent module is a module which is not derived from
  34 or based on this library.  If you modify this library, you may extend
  35 this exception to your version of the library, but you are not
  36 obligated to do so.  If you do not wish to do so, delete this
  37 exception statement from your version. */
  38
  39 package java.lang;
  40
  41 import java.io.Serializable;
  42
  43 /**
  44  * <code>StringBuffer</code> represents a changeable <code>String</code>.
  45  * It provides the operations required to modify the
  46  * <code>StringBuffer</code>, including insert, replace, delete, append,
  47  * and reverse. It is thread-safe; meaning that all modifications to a buffer
  48  * are in synchronized methods.
  49  *
  50  * <p><code>StringBuffer</code>s are variable-length in nature, so even if
  51  * you initialize them to a certain size, they can still grow larger than
  52  * that. <em>Capacity</em> indicates the number of characters the
  53  * <code>StringBuffer</code> can have in it before it has to grow (growing
  54  * the char array is an expensive operation involving <code>new</code>).
  55  *
  56  * <p>Incidentally, compilers often implement the String operator "+"
  57  * by using a <code>StringBuffer</code> operation:<br>
  58  * <code>a + b</code><br>
  59  * is the same as<br>
  60  * <code>new StringBuffer().append(a).append(b).toString()</code>.
  61  *
  62  * <p>Classpath's StringBuffer is capable of sharing memory with Strings for
  63  * efficiency.  This will help when a StringBuffer is converted to a String
  64  * and the StringBuffer is not changed after that (quite common when performing
  65  * string concatenation).
  66  *
  67  * @author Paul Fisher
  68  * @author John Keiser
  69  * @author Tom Tromey
  70  * @author Eric Blake (ebb9@email.byu.edu)
  71  * @see String
  72  * @since 1.0
  73  * @status updated to 1.4
  74  */
  75 public final class StringBuffer
  76   extends AbstractStringBuffer
  77   implements Serializable, CharSequence, Appendable
  78 {
  79   // Implementation note: if you change this class, you usually will
  80   // want to change StringBuilder as well.
  81
  82   /**
  83    * Compatible with JDK 1.0+.
  84    */
  85   private static final long serialVersionUID = 3388685877147921107L;
  86
  87   /**
  88    * True if the buffer is shared with another object (StringBuffer or
  89    * String); this means the buffer must be copied before writing to it again.
  90    * Note that this has permissions set this way so that String can get the
  91    * value.
  92    *
  93    * @serial whether the buffer is shared
  94    */
  95   boolean shared;
  96
  97   /**
  98    * Create a new StringBuffer with default capacity 16.
  99    */
 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 }