home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 July & August / Pcwk78a98.iso / Internet / Javadraw / DATA.Z / StringBuffer.java < prev    next >
Text File  |  1997-08-30  |  28KB  |  777 lines
  1. /*
  2.  * @(#)StringBuffer.java    1.33 97/01/24
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  * 
  21.  */
  22.  
  23. package java.lang;
  24.  
  25. /**
  26.  * A string buffer implements a mutable sequence of characters. 
  27.  * <p>
  28.  * String buffers are safe for use by multiple threads. The methods 
  29.  * are synchronized where necessary so that all the operations on any 
  30.  * particular instance behave as if they occur in some serial order. 
  31.  * <p>
  32.  * String buffers are used by the compiler to implement the binary 
  33.  * string concatenation operator <code>+</code>. For example, the code:
  34.  * <p><blockquote><pre>
  35.  *     x = "a" + 4 + "c"
  36.  * </pre></blockquote><p>
  37.  * is compiled to the equivalent of: 
  38.  * <p><blockquote><pre>
  39.  *     x = new StringBuffer().append("a").append(4).append("c")
  40.  *                           .toString()
  41.  * </pre></blockquote><p>
  42.  * The principal operations on a <code>StringBuffer</code> are the 
  43.  * <code>append</code> and <code>insert</code> methods, which are 
  44.  * overloaded so as to accept data of any type. Each effectively 
  45.  * converts a given datum to a string and then appends or inserts the 
  46.  * characters of that string to the string buffer. The 
  47.  * <code>append</code> method always adds these characters at the end 
  48.  * of the buffer; the <code>insert</code> method adds the characters at 
  49.  * a specified point. 
  50.  * <p>
  51.  * For example, if <code>z</code> refers to a string buffer object 
  52.  * whose current contents are "<code>start</code>", then 
  53.  * the method call <code>z.append("le")</code> would cause the string 
  54.  * buffer to contain "<code>startle</code>", whereas 
  55.  * <code>z.insert(4, "le")</code> would alter the string buffer to 
  56.  * contain "<code>starlet</code>". 
  57.  * <p>
  58.  * Every string buffer has a capacity. As long as the length of the 
  59.  * character sequence contained in the string buffer does not exceed 
  60.  * the capacity, it is not necessary to allocate a new internal 
  61.  * buffer array. If the internal buffer overflows, it is 
  62.  * automatically made larger. 
  63.  *
  64.  * @author    Arthur van Hoff
  65.  * @version     1.33, 01/24/97
  66.  * @see     java.io.ByteArrayOutputStream
  67.  * @see     java.lang.String
  68.  * @since   JDK1.0
  69.  */
  70.  
  71. public final class StringBuffer implements java.io.Serializable {
  72.     /** The value is used for character storage. */
  73.     private char value[];
  74.  
  75.     /** The count is the number of characters in the buffer. */
  76.     private int count;
  77.  
  78.     /** A flag indicating whether the buffer is shared */
  79.     private boolean shared;
  80.  
  81.     /** use serialVersionUID from JDK 1.0.2 for interoperability */
  82.     static final long serialVersionUID = 3388685877147921107L;
  83.  
  84.     /**
  85.      * Constructs a string buffer with no characters in it and an 
  86.      * initial capacity of 16 characters. 
  87.      *
  88.      * @since   JDK1.0
  89.      */
  90.     public StringBuffer() {
  91.     this(16);
  92.     }
  93.  
  94.     /**
  95.      * Constructs a string buffer with no characters in it and an 
  96.      * initial capacity specified by the <code>length</code> argument. 
  97.      *
  98.      * @param      length   the initial capacity.
  99.      * @exception  NegativeArraySizeException  if the <code>length</code>
  100.      *               argument is less than <code>0</code>.
  101.      * @since      JDK1.0
  102.      */
  103.     public StringBuffer(int length) {
  104.     value = new char[length];
  105.     shared = false;
  106.     }
  107.  
  108.     /**
  109.      * Constructs a string buffer so that it represents the same 
  110.      * sequence of characters as the string argument. The initial 
  111.      * capacity of the string buffer is <code>16</code> plus the length 
  112.      * of the string argument. 
  113.      *
  114.      * @param   str   the initial contents of the buffer.
  115.      * @since   JDK1.0
  116.      */
  117.     public StringBuffer(String str) {
  118.     this(str.length() + 16);
  119.     append(str);
  120.     }
  121.  
  122.     /**
  123.      * Returns the length (character count) of this string buffer.
  124.      *
  125.      * @return  the number of characters in this string buffer.
  126.      * @since   JDK1.0
  127.      */
  128.     public int length() {
  129.     return count;
  130.     }
  131.  
  132.     /**
  133.      * Returns the current capacity of the String buffer. The capacity
  134.      * is the amount of storage available for newly inserted
  135.      * characters; beyond which an allocation will occur.
  136.      *
  137.      * @return  the current capacity of this string buffer.
  138.      * @since   JDK1.0
  139.      */
  140.     public int capacity() {
  141.     return value.length;
  142.     }
  143.  
  144.     /**
  145.      * Copies the buffer value if it is shared.
  146.      */
  147.     private final void copyWhenShared() {
  148.     if (shared) {
  149.         char newValue[] = new char[value.length];
  150.         System.arraycopy(value, 0, newValue, 0, count);
  151.         value = newValue;
  152.         shared = false;
  153.     }
  154.     }
  155.  
  156.     /**
  157.      * Ensures that the capacity of the buffer is at least equal to the
  158.      * specified minimum.
  159.      * If the current capacity of this string buffer is less than the 
  160.      * argument, then a new internal buffer is allocated with greater 
  161.      * capacity. The new capacity is the larger of: 
  162.      * <ul>
  163.      * <li>The <code>minimumCapacity</code> argument. 
  164.      * <li>Twice the old capacity, plus <code>2</code>. 
  165.      * </ul>
  166.      * If the <code>minimumCapacity</code> argument is nonpositive, this
  167.      * method takes no action and simply returns.
  168.      *
  169.      * @param   minimumCapacity   the minimum desired capacity.
  170.      * @since   JDK1.0
  171.      */
  172.     public synchronized void ensureCapacity(int minimumCapacity) {
  173.     int maxCapacity = value.length;
  174.  
  175.     if (minimumCapacity > maxCapacity) {
  176.         int newCapacity = (maxCapacity + 1) * 2;
  177.         if (minimumCapacity > newCapacity) {
  178.         newCapacity = minimumCapacity;
  179.         }
  180.  
  181.         char newValue[] = new char[newCapacity];
  182.         System.arraycopy(value, 0, newValue, 0, count);
  183.         value = newValue;
  184.         shared = false;
  185.     }
  186.     }
  187.  
  188.     /**
  189.      * Sets the length of this String buffer.
  190.      * If the <code>newLength</code> argument is less than the current 
  191.      * length of the string buffer, the string buffer is truncated to 
  192.      * contain exactly the number of characters given by the 
  193.      * <code>newLength</code> argument. 
  194.      * <p>
  195.      * If the <code>newLength</code> argument is greater than or equal 
  196.      * to the current length, sufficient null characters 
  197.      * (<code>'\u0000'</code>) are appended to the string buffer so that 
  198.      * length becomes the <code>newLength</code> argument. 
  199.      * <p>
  200.      * The <code>newLength</code> argument must be greater than or equal 
  201.      * to <code>0</code>. 
  202.      *
  203.      * @param      newLength   the new length of the buffer.
  204.      * @exception  StringIndexOutOfBoundsException  if the
  205.      *               <code>newLength</code> argument is invalid.
  206.      * @see        java.lang.StringBuffer#length()
  207.      * @since      JDK1.0
  208.      */
  209.     public synchronized void setLength(int newLength) {
  210.     if (newLength < 0) {
  211.         throw new StringIndexOutOfBoundsException(newLength);
  212.     }
  213.     ensureCapacity(newLength);
  214.  
  215.     if (count < newLength) {
  216.         copyWhenShared();
  217.         for (; count < newLength; count++) {
  218.         value[count] = '\0';
  219.         }
  220.     }
  221.     count = newLength;
  222.     }
  223.  
  224.     /**
  225.      * Returns the character at a specific index in this string buffer. 
  226.      * <p>
  227.      * The first character of a string buffer is at index 
  228.      * <code>0</code>, the next at index <code>1</code>, and so on, for 
  229.      * array indexing. 
  230.      * <p>
  231.      * The index argument must be greater than or equal to 
  232.      * <code>0</code>, and less than the length of this string buffer. 
  233.      *
  234.      * @param      index   the index of the desired character.
  235.      * @return     the character at the specified index of this string buffer.
  236.      * @exception  StringIndexOutOfBoundsException  if the index is invalid.
  237.      * @see        java.lang.StringBuffer#length()
  238.      * @since      JDK1.0
  239.      */
  240.     public synchronized char charAt(int index) {
  241.     if ((index < 0) || (index >= count)) {
  242.         throw new StringIndexOutOfBoundsException(index);
  243.     }
  244.     return value[index];
  245.     }
  246.  
  247.     /**
  248.      * Characters are copied from this string buffer into the 
  249.      * destination character array <code>dst</code>. The first character to 
  250.      * be copied is at index <code>srcBegin</code>; the last character to 
  251.      * be copied is at index <code>srcEnd-1.</code> The total number of 
  252.      * characters to be copied is <code>srcEnd-srcBegin</code>. The 
  253.      * characters are copied into the subarray of <code>dst</code> starting 
  254.      * at index <code>dstBegin</code> and ending at index:
  255.      * <p><blockquote><pre>
  256.      *     dstbegin + (srcEnd-srcBegin) - 1
  257.      * </pre></blockquote>
  258.      *
  259.      * @param      srcBegin   start copying at this offset in the string buffer.
  260.      * @param      srcEnd     stop copying at this offset in the string buffer.
  261.      * @param      dst        the array to copy the data into.
  262.      * @param      dstBegin   offset into <code>dst</code>.
  263.      * @exception  StringIndexOutOfBoundsException  if there is an invalid
  264.      *               index into the buffer.
  265.      * @since      JDK1.0
  266.      */
  267.     public synchronized void getChars(int srcBegin, int srcEnd, char dst[], int dstBegin) {
  268.     if ((srcBegin < 0) || (srcBegin >= count)) {
  269.         throw new StringIndexOutOfBoundsException(srcBegin);
  270.     }
  271.     if ((srcEnd < 0) || (srcEnd > count)) {
  272.         throw new StringIndexOutOfBoundsException(srcEnd);
  273.     }
  274.     if (srcBegin < srcEnd) {
  275.         System.arraycopy(value, srcBegin, dst, dstBegin, srcEnd - srcBegin);
  276.     }
  277.     }
  278.  
  279.     /**
  280.      * The character at the specified index of this string buffer is set 
  281.      * to <code>ch</code>. 
  282.      * <p>
  283.      * The offset argument must be greater than or equal to 
  284.      * <code>0</code>, and less than the length of this string buffer. 
  285.      *
  286.      * @param      index   the index of the character to modify.
  287.      * @param      ch      the new character.
  288.      * @exception  StringIndexOutOfBoundsException  if the index is invalid.
  289.      * @see        java.lang.StringBuffer#length()
  290.      * @since      JDK1.0
  291.      */
  292.     public synchronized void setCharAt(int index, char ch) {
  293.     if ((index < 0) || (index >= count)) {
  294.         throw new StringIndexOutOfBoundsException(index);
  295.     }
  296.     copyWhenShared();
  297.     value[index] = ch;
  298.     }
  299.  
  300.     /**
  301.      * Appends the string representation of the <code>Object</code> 
  302.      * argument to this string buffer. 
  303.      * <p>
  304.      * The argument is converted to a string as if by the method 
  305.      * <code>String.valueOf</code>, and the characters of that 
  306.      * string are then appended to this string buffer. 
  307.      *
  308.      * @param   obj   an <code>Object</code>.
  309.      * @return  this string buffer.
  310.      * @see     java.lang.String#valueOf(java.lang.Object)
  311.      * @see     java.lang.StringBuffer#append(java.lang.String)
  312.      * @since   JDK1.0
  313.      */
  314.     public synchronized StringBuffer append(Object obj) {
  315.     return append(String.valueOf(obj));
  316.     }
  317.  
  318.     /**
  319.      * Appends the string to this string buffer. 
  320.      * <p>
  321.      * The characters of the <code>String</code> argument are appended, in 
  322.      * order, to the contents of this string buffer, increasing the 
  323.      * length of this string buffer by the length of the argument. 
  324.      *
  325.      * @param   str   a string.
  326.      * @return  this string buffer.
  327.      * @since   JDK1.0
  328.      */
  329.     public synchronized StringBuffer append(String str) {
  330.     if (str == null) {
  331.         str = String.valueOf(str);
  332.     }
  333.  
  334.     int len = str.length();
  335.     ensureCapacity(count + len);
  336.     copyWhenShared();
  337.     str.getChars(0, len, value, count);
  338.     count += len;
  339.     return this;
  340.     }
  341.  
  342.     /**
  343.      * Appends the string representation of the <code>char</code> array 
  344.      * argument to this string buffer. 
  345.      * <p>
  346.      * The characters of the array argument are appended, in order, to 
  347.      * the contents of this string buffer. The length of this string 
  348.      * buffer increases by the length of the argument. 
  349.      *
  350.      * @param   str   the characters to be appended.
  351.      * @return  this string buffer.
  352.      * @since   JDK1.0
  353.      */
  354.     public synchronized StringBuffer append(char str[]) {
  355.     int len = str.length;
  356.     ensureCapacity(count + len);
  357.     copyWhenShared();
  358.     System.arraycopy(str, 0, value, count, len);
  359.     count += len;
  360.     return this;
  361.     }
  362.  
  363.     /**
  364.      * Appends the string representation of a subarray of the 
  365.      * <code>char</code> array argument to this string buffer. 
  366.      * <p>
  367.      * Characters of the character array <code>str</code>, starting at 
  368.      * index <code>offset</code>, are appended, in order, to the contents 
  369.      * of this string buffer. The length of this string buffer increases 
  370.      * by the value of <code>len</code>. 
  371.      *
  372.      * @param   str      the characters to be appended.
  373.      * @param   offset   the index of the first character to append.
  374.      * @param   len      the number of characters to append.
  375.      * @return  this string buffer.
  376.      * @since   JDK1.0
  377.      */
  378.     public synchronized StringBuffer append(char str[], int offset, int len) {
  379.     ensureCapacity(count + len);
  380.     copyWhenShared();
  381.     System.arraycopy(str, offset, value, count, len);
  382.     count += len;
  383.     return this;
  384.     }
  385.  
  386.     /**
  387.      * Appends the string representation of the <code>boolean</code> 
  388.      * argument to the string buffer. 
  389.      * <p>
  390.      * The argument is converted to a string as if by the method 
  391.      * <code>String.valueOf</code>, and the characters of that 
  392.      * string are then appended to this string buffer. 
  393.      *
  394.      * @param   b   a <code>boolean</code>.
  395.      * @return  this string buffer.
  396.      * @see     java.lang.String#valueOf(boolean)
  397.      * @see     java.lang.StringBuffer#append(java.lang.String)
  398.      * @since   JDK1.0
  399.      */
  400.     public StringBuffer append(boolean b) {
  401.     return append(String.valueOf(b));
  402.     }
  403.  
  404.     /**
  405.      * Appends the string representation of the <code>char</code> 
  406.      * argument to this string buffer. 
  407.      * <p>
  408.      * The argument is appended to the contents of this string buffer. 
  409.      * The length of this string buffer increases by <code>1</code>. 
  410.      *
  411.      * @param   ch   a <code>char</code>.
  412.      * @return  this string buffer.
  413.      * @since   JDK1.0
  414.      */
  415.     public synchronized StringBuffer append(char c) {
  416.     ensureCapacity(count + 1);
  417.     copyWhenShared();
  418.     value[count++] = c;
  419.     return this;
  420.     }
  421.  
  422.     /**
  423.      * Appends the string representation of the <code>int</code> 
  424.      * argument to this string buffer. 
  425.      * <p>
  426.      * The argument is converted to a string as if by the method 
  427.      * <code>String.valueOf</code>, and the characters of that 
  428.      * string are then appended to this string buffer. 
  429.      *
  430.      * @param   i   an <code>int</code>.
  431.      * @return  this string buffer.
  432.      * @see     java.lang.String#valueOf(int)
  433.      * @see     java.lang.StringBuffer#append(java.lang.String)
  434.      * @since   JDK1.0
  435.      */
  436.     public StringBuffer append(int i) {
  437.     return append(String.valueOf(i));
  438.     }
  439.  
  440.     /**
  441.      * Appends the string representation of the <code>long</code> 
  442.      * argument to this string buffer. 
  443.      * <p>
  444.      * The argument is converted to a string as if by the method 
  445.      * <code>String.valueOf</code>, and the characters of that 
  446.      * string are then appended to this string buffer. 
  447.      *
  448.      * @param   l   a <code>long</code>.
  449.      * @return  this string buffer.
  450.      * @see     java.lang.String#valueOf(long)
  451.      * @see     java.lang.StringBuffer#append(java.lang.String)
  452.      * @since   JDK1.0
  453.      */
  454.     public StringBuffer append(long l) {
  455.     return append(String.valueOf(l));
  456.     }
  457.  
  458.     /**
  459.      * Appends the string representation of the <code>float</code> 
  460.      * argument to this string buffer. 
  461.      * <p>
  462.      * The argument is converted to a string as if by the method 
  463.      * <code>String.valueOf</code>, and the characters of that 
  464.      * string are then appended to this string buffer. 
  465.      *
  466.      * @param   f   a <code>float</code>.
  467.      * @return  this string buffer.
  468.      * @see     java.lang.String#valueOf(float)
  469.      * @see     java.lang.StringBuffer#append(java.lang.String)
  470.      * @since   JDK1.0
  471.      */
  472.     public StringBuffer append(float f) {
  473.     return append(String.valueOf(f));
  474.     }
  475.  
  476.     /**
  477.      * Appends the string representation of the <code>double</code> 
  478.      * argument to this string buffer. 
  479.      * <p>
  480.      * The argument is converted to a string as if by the method 
  481.      * <code>String.valueOf</code>, and the characters of that 
  482.      * string are then appended to this string buffer. 
  483.      *
  484.      * @param   d   a <code>double</code>.
  485.      * @return  this string buffer.
  486.      * @see     java.lang.String#valueOf(double)
  487.      * @see     java.lang.StringBuffer#append(java.lang.String)
  488.      * @since   JDK1.0
  489.      */
  490.     public StringBuffer append(double d) {
  491.     return append(String.valueOf(d));
  492.     }
  493.  
  494.     /**
  495.      * Inserts the string representation of the <code>Object</code> 
  496.      * argument into this string buffer. 
  497.      * <p>
  498.      * The second argument is converted to a string as if by the method 
  499.      * <code>String.valueOf</code>, and the characters of that 
  500.      * string are then inserted into this string buffer at the indicated 
  501.      * offset. 
  502.      * <p>
  503.      * The offset argument must be greater than or equal to 
  504.      * <code>0</code>, and less than or equal to the length of this 
  505.      * string buffer. 
  506.      *
  507.      * @param      offset   the offset.
  508.      * @param      b        an <code>Object</code>.
  509.      * @return     this string buffer.
  510.      * @exception  StringIndexOutOfBoundsException  if the offset is invalid.
  511.      * @see        java.lang.String#valueOf(java.lang.Object)
  512.      * @see        java.lang.StringBuffer#insert(int, java.lang.String)
  513.      * @see        java.lang.StringBuffer#length()
  514.      * @since      JDK1.0
  515.      */
  516.     public synchronized StringBuffer insert(int offset, Object obj) {
  517.     return insert(offset, String.valueOf(obj));
  518.     }
  519.  
  520.     /**
  521.      * Inserts the string into this string buffer. 
  522.      * <p>
  523.      * The characters of the <code>String</code> argument are inserted, in 
  524.      * order, into this string buffer at the indicated offset. The length 
  525.      * of this string buffer is increased by the length of the argument. 
  526.      * <p>
  527.      * The offset argument must be greater than or equal to 
  528.      * <code>0</code>, and less than or equal to the length of this 
  529.      * string buffer. 
  530.      *
  531.      * @param      offset   the offset.
  532.      * @param      str      a string.
  533.      * @return     this string buffer.
  534.      * @exception  StringIndexOutOfBoundsException  if the offset is invalid.
  535.      * @see        java.lang.StringBuffer#length()
  536.      * @since      JDK1.0
  537.      */
  538.     public synchronized StringBuffer insert(int offset, String str) {
  539.     if ((offset < 0) || (offset > count)) {
  540.         throw new StringIndexOutOfBoundsException();
  541.     }
  542.     int len = str.length();
  543.     ensureCapacity(count + len);
  544.     copyWhenShared();
  545.     System.arraycopy(value, offset, value, offset + len, count - offset);
  546.     str.getChars(0, len, value, offset);
  547.     count += len;
  548.     return this;
  549.     }
  550.  
  551.     /**
  552.      * Inserts the string representation of the <code>char</code> array 
  553.      * argument into this string buffer. 
  554.      * <p>
  555.      * The characters of the array argument are inserted into the 
  556.      * contents of this string buffer at the position indicated by 
  557.      * <code>offset</code>. The length of this string buffer increases by 
  558.      * the length of the argument. 
  559.      *
  560.      * @param      offset   the offset.
  561.      * @param      ch       a character array.
  562.      * @return     this string buffer.
  563.      * @exception  StringIndexOutOfBoundsException  if the offset is invalid.
  564.      * @since      JDK1.0
  565.      */
  566.     public synchronized StringBuffer insert(int offset, char str[]) {
  567.     if ((offset < 0) || (offset > count)) {
  568.         throw new StringIndexOutOfBoundsException();
  569.     }
  570.     int len = str.length;
  571.     ensureCapacity(count + len);
  572.     copyWhenShared();
  573.     System.arraycopy(value, offset, value, offset + len, count - offset);
  574.     System.arraycopy(str, 0, value, offset, len);
  575.     count += len;
  576.     return this;
  577.     }
  578.  
  579.     /**
  580.      * Inserts the string representation of the <code>boolean</code> 
  581.      * argument into this string buffer. 
  582.      * <p>
  583.      * The second argument is converted to a string as if by the method 
  584.      * <code>String.valueOf</code>, and the characters of that 
  585.      * string are then inserted into this string buffer at the indicated 
  586.      * offset. 
  587.      * <p>
  588.      * The offset argument must be greater than or equal to 
  589.      * <code>0</code>, and less than or equal to the length of this 
  590.      * string buffer. 
  591.      *
  592.      * @param      offset   the offset.
  593.      * @param      b        a <code>boolean</code>.
  594.      * @return     this string buffer.
  595.      * @exception  StringIndexOutOfBoundsException  if the offset is invalid.
  596.      * @see        java.lang.String#valueOf(boolean)
  597.      * @see        java.lang.StringBuffer#insert(int, java.lang.String)
  598.      * @see        java.lang.StringBuffer#length()
  599.      * @since      JDK1.0
  600.      */
  601.     public StringBuffer insert(int offset, boolean b) {
  602.     return insert(offset, String.valueOf(b));
  603.     }
  604.  
  605.     /**
  606.      * Inserts the string representation of the <code>char</code> 
  607.      * argument into this string buffer. 
  608.      * <p>
  609.      * The second argument is inserted into the contents of this string 
  610.      * buffer at the position indicated by <code>offset</code>. The length 
  611.      * of this string buffer increases by one. 
  612.      * <p>
  613.      * The offset argument must be greater than or equal to 
  614.      * <code>0</code>, and less than or equal to the length of this 
  615.      * string buffer. 
  616.      *
  617.      * @param      offset   the offset.
  618.      * @param      ch       a <code>char</code>.
  619.      * @return     this string buffer.
  620.      * @exception  StringIndexOutOfBoundsException  if the offset is invalid.
  621.      * @see        java.lang.StringBuffer#length()
  622.      * @since      JDK1.0
  623.      */
  624.     public synchronized StringBuffer insert(int offset, char c) {
  625.     ensureCapacity(count + 1);
  626.     copyWhenShared();
  627.     System.arraycopy(value, offset, value, offset + 1, count - offset);
  628.     value[offset] = c;
  629.     count += 1;
  630.     return this;
  631.     }
  632.  
  633.     /**
  634.      * Inserts the string representation of the second <code>int</code> 
  635.      * argument into this string buffer. 
  636.      * <p>
  637.      * The second argument is converted to a string as if by the method 
  638.      * <code>String.valueOf</code>, and the characters of that 
  639.      * string are then inserted into this string buffer at the indicated 
  640.      * offset. 
  641.      * <p>
  642.      * The offset argument must be greater than or equal to 
  643.      * <code>0</code>, and less than or equal to the length of this 
  644.      * string buffer. 
  645.      *
  646.      * @param      offset   the offset.
  647.      * @param      b        an <code>int</code>.
  648.      * @return     this string buffer.
  649.      * @exception  StringIndexOutOfBoundsException  if the offset is invalid.
  650.      * @see        java.lang.String#valueOf(int)
  651.      * @see        java.lang.StringBuffer#insert(int, java.lang.String)
  652.      * @see        java.lang.StringBuffer#length()
  653.      * @since      JDK1.0
  654.      */
  655.     public StringBuffer insert(int offset, int i) {
  656.     return insert(offset, String.valueOf(i));
  657.     }
  658.  
  659.     /**
  660.      * Inserts the string representation of the <code>long</code> 
  661.      * argument into this string buffer. 
  662.      * <p>
  663.      * The second argument is converted to a string as if by the method 
  664.      * <code>String.valueOf</code>, and the characters of that 
  665.      * string are then inserted into this string buffer at the indicated 
  666.      * offset. 
  667.      * <p>
  668.      * The offset argument must be greater than or equal to 
  669.      * <code>0</code>, and less than or equal to the length of this 
  670.      * string buffer. 
  671.      *
  672.      * @param      offset   the offset.
  673.      * @param      b        a <code>long</code>.
  674.      * @return     this string buffer.
  675.      * @exception  StringIndexOutOfBoundsException  if the offset is invalid.
  676.      * @see        java.lang.String#valueOf(long)
  677.      * @see        java.lang.StringBuffer#insert(int, java.lang.String)
  678.      * @see        java.lang.StringBuffer#length()
  679.      * @since      JDK1.0
  680.      */
  681.     public StringBuffer insert(int offset, long l) {
  682.     return insert(offset, String.valueOf(l));
  683.     }
  684.  
  685.     /**
  686.      * Inserts the string representation of the <code>float</code> 
  687.      * argument into this string buffer. 
  688.      * <p>
  689.      * The second argument is converted to a string as if by the method 
  690.      * <code>String.valueOf</code>, and the characters of that 
  691.      * string are then inserted into this string buffer at the indicated 
  692.      * offset. 
  693.      * <p>
  694.      * The offset argument must be greater than or equal to 
  695.      * <code>0</code>, and less than or equal to the length of this 
  696.      * string buffer. 
  697.      *
  698.      * @param      offset   the offset.
  699.      * @param      b        a <code>float</code>.
  700.      * @return     this string buffer.
  701.      * @exception  StringIndexOutOfBoundsException  if the offset is invalid.
  702.      * @see        java.lang.String#valueOf(float)
  703.      * @see        java.lang.StringBuffer#insert(int, java.lang.String)
  704.      * @see        java.lang.StringBuffer#length()
  705.      * @since      JDK1.0
  706.      */
  707.     public StringBuffer insert(int offset, float f) {
  708.     return insert(offset, String.valueOf(f));
  709.     }
  710.  
  711.     /**
  712.      * Inserts the string representation of the <code>double</code> 
  713.      * argument into this string buffer. 
  714.      * <p>
  715.      * The second argument is converted to a string as if by the method 
  716.      * <code>String.valueOf</code>, and the characters of that 
  717.      * string are then inserted into this string buffer at the indicated 
  718.      * offset. 
  719.      * <p>
  720.      * The offset argument must be greater than or equal to 
  721.      * <code>0</code>, and less than or equal to the length of this 
  722.      * string buffer. 
  723.      *
  724.      * @param      offset   the offset.
  725.      * @param      b        a <code>double</code>.
  726.      * @return     this string buffer.
  727.      * @exception  StringIndexOutOfBoundsException  if the offset is invalid.
  728.      * @see        java.lang.String#valueOf(double)
  729.      * @see        java.lang.StringBuffer#insert(int, java.lang.String)
  730.      * @see        java.lang.StringBuffer#length()
  731.      * @since      JDK1.0
  732.      */
  733.     public StringBuffer insert(int offset, double d) {
  734.     return insert(offset, String.valueOf(d));
  735.     }
  736.  
  737.     /**
  738.      * The character sequence contained in this string buffer is 
  739.      * replaced by the reverse of the sequence. 
  740.      *
  741.      * @return  this string buffer.
  742.      * @since   JDK1.0.2
  743.      */
  744.     public synchronized StringBuffer reverse() {
  745.     copyWhenShared();
  746.     int n = count - 1;
  747.     for (int j = (n-1) >> 1; j >= 0; --j) {
  748.         char temp = value[j];
  749.         value[j] = value[n - j];
  750.         value[n - j] = temp;
  751.     }
  752.     return this;
  753.     }
  754.  
  755.     /**
  756.      * Converts to a string representing the data in this string buffer.
  757.      * A new <code>String</code> object is allocated and initialized to 
  758.      * contain the character sequence currently represented by this 
  759.      * string buffer. This <code>String</code> is then returned. Subsequent 
  760.      * changes to the string buffer do not affect the contents of the 
  761.      * <code>String</code>. 
  762.      *
  763.      * @return  a string representation of the string buffer.
  764.      * @since   JDK1.0
  765.      */
  766.     public String toString() {
  767.     return new String(this);
  768.     }
  769.  
  770.     //
  771.     // The following two methods are needed by String to efficiently
  772.     // convert a StringBuffer into a String.  They are not public.
  773.     // They shouldn't be called by anyone but String.
  774.     final void setShared() { shared = true; } 
  775.     final char[] getValue() { return value; }
  776. }
  777.