Home » openjdk-7 » java » lang » [javadoc | source]

    1   /*
    2    * Copyright (c) 2003, 2008, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.lang;
   27   
   28   
   29   /**
   30    * A mutable sequence of characters.  This class provides an API compatible
   31    * with <code>StringBuffer</code>, but with no guarantee of synchronization.
   32    * This class is designed for use as a drop-in replacement for
   33    * <code>StringBuffer</code> in places where the string buffer was being
   34    * used by a single thread (as is generally the case).   Where possible,
   35    * it is recommended that this class be used in preference to
   36    * <code>StringBuffer</code> as it will be faster under most implementations.
   37    *
   38    * <p>The principal operations on a <code>StringBuilder</code> are the
   39    * <code>append</code> and <code>insert</code> methods, which are
   40    * overloaded so as to accept data of any type. Each effectively
   41    * converts a given datum to a string and then appends or inserts the
   42    * characters of that string to the string builder. The
   43    * <code>append</code> method always adds these characters at the end
   44    * of the builder; the <code>insert</code> method adds the characters at
   45    * a specified point.
   46    * <p>
   47    * For example, if <code>z</code> refers to a string builder object
   48    * whose current contents are "<code>start</code>", then
   49    * the method call <code>z.append("le")</code> would cause the string
   50    * builder to contain "<code>startle</code>", whereas
   51    * <code>z.insert(4, "le")</code> would alter the string builder to
   52    * contain "<code>starlet</code>".
   53    * <p>
   54    * In general, if sb refers to an instance of a <code>StringBuilder</code>,
   55    * then <code>sb.append(x)</code> has the same effect as
   56    * <code>sb.insert(sb.length(),&nbsp;x)</code>.
   57    *
   58    * Every string builder has a capacity. As long as the length of the
   59    * character sequence contained in the string builder does not exceed
   60    * the capacity, it is not necessary to allocate a new internal
   61    * buffer. If the internal buffer overflows, it is automatically made larger.
   62    *
   63    * <p>Instances of <code>StringBuilder</code> are not safe for
   64    * use by multiple threads. If such synchronization is required then it is
   65    * recommended that {@link java.lang.StringBuffer} be used.
   66    *
   67    * @author      Michael McCloskey
   68    * @see         java.lang.StringBuffer
   69    * @see         java.lang.String
   70    * @since       1.5
   71    */
   72   public final class StringBuilder
   73       extends AbstractStringBuilder
   74       implements java.io.Serializable, CharSequence
   75   {
   76   
   77       /** use serialVersionUID for interoperability */
   78       static final long serialVersionUID = 4383685877147921099L;
   79   
   80       /**
   81        * Constructs a string builder with no characters in it and an
   82        * initial capacity of 16 characters.
   83        */
   84       public StringBuilder() {
   85           super(16);
   86       }
   87   
   88       /**
   89        * Constructs a string builder with no characters in it and an
   90        * initial capacity specified by the <code>capacity</code> argument.
   91        *
   92        * @param      capacity  the initial capacity.
   93        * @throws     NegativeArraySizeException  if the <code>capacity</code>
   94        *               argument is less than <code>0</code>.
   95        */
   96       public StringBuilder(int capacity) {
   97           super(capacity);
   98       }
   99   
  100       /**
  101        * Constructs a string builder initialized to the contents of the
  102        * specified string. The initial capacity of the string builder is
  103        * <code>16</code> plus the length of the string argument.
  104        *
  105        * @param   str   the initial contents of the buffer.
  106        * @throws    NullPointerException if <code>str</code> is <code>null</code>
  107        */
  108       public StringBuilder(String str) {
  109           super(str.length() + 16);
  110           append(str);
  111       }
  112   
  113       /**
  114        * Constructs a string builder that contains the same characters
  115        * as the specified <code>CharSequence</code>. The initial capacity of
  116        * the string builder is <code>16</code> plus the length of the
  117        * <code>CharSequence</code> argument.
  118        *
  119        * @param      seq   the sequence to copy.
  120        * @throws    NullPointerException if <code>seq</code> is <code>null</code>
  121        */
  122       public StringBuilder(CharSequence seq) {
  123           this(seq.length() + 16);
  124           append(seq);
  125       }
  126   
  127       public StringBuilder append(Object obj) {
  128           return append(String.valueOf(obj));
  129       }
  130   
  131       public StringBuilder append(String str) {
  132           super.append(str);
  133           return this;
  134       }
  135   
  136       // Appends the specified string builder to this sequence.
  137       private StringBuilder append(StringBuilder sb) {
  138           if (sb == null)
  139               return append("null");
  140           int len = sb.length();
  141           int newcount = count + len;
  142           if (newcount > value.length)
  143               expandCapacity(newcount);
  144           sb.getChars(0, len, value, count);
  145           count = newcount;
  146           return this;
  147       }
  148   
  149       /**
  150        * Appends the specified <tt>StringBuffer</tt> to this sequence.
  151        * <p>
  152        * The characters of the <tt>StringBuffer</tt> argument are appended,
  153        * in order, to this sequence, increasing the
  154        * length of this sequence by the length of the argument.
  155        * If <tt>sb</tt> is <tt>null</tt>, then the four characters
  156        * <tt>"null"</tt> are appended to this sequence.
  157        * <p>
  158        * Let <i>n</i> be the length of this character sequence just prior to
  159        * execution of the <tt>append</tt> method. Then the character at index
  160        * <i>k</i> in the new character sequence is equal to the character at
  161        * index <i>k</i> in the old character sequence, if <i>k</i> is less than
  162        * <i>n</i>; otherwise, it is equal to the character at index <i>k-n</i>
  163        * in the argument <code>sb</code>.
  164        *
  165        * @param   sb   the <tt>StringBuffer</tt> to append.
  166        * @return  a reference to this object.
  167        */
  168       public StringBuilder append(StringBuffer sb) {
  169           super.append(sb);
  170           return this;
  171       }
  172   
  173       /**
  174        */
  175       public StringBuilder append(CharSequence s) {
  176           if (s == null)
  177               s = "null";
  178           if (s instanceof String)
  179               return this.append((String)s);
  180           if (s instanceof StringBuffer)
  181               return this.append((StringBuffer)s);
  182           if (s instanceof StringBuilder)
  183               return this.append((StringBuilder)s);
  184           return this.append(s, 0, s.length());
  185       }
  186   
  187       /**
  188        * @throws     IndexOutOfBoundsException {@inheritDoc}
  189        */
  190       public StringBuilder append(CharSequence s, int start, int end) {
  191           super.append(s, start, end);
  192           return this;
  193       }
  194   
  195       public StringBuilder append(char[] str) {
  196           super.append(str);
  197           return this;
  198       }
  199   
  200       /**
  201        * @throws IndexOutOfBoundsException {@inheritDoc}
  202        */
  203       public StringBuilder append(char[] str, int offset, int len) {
  204           super.append(str, offset, len);
  205           return this;
  206       }
  207   
  208       public StringBuilder append(boolean b) {
  209           super.append(b);
  210           return this;
  211       }
  212   
  213       public StringBuilder append(char c) {
  214           super.append(c);
  215           return this;
  216       }
  217   
  218       public StringBuilder append(int i) {
  219           super.append(i);
  220           return this;
  221       }
  222   
  223       public StringBuilder append(long lng) {
  224           super.append(lng);
  225           return this;
  226       }
  227   
  228       public StringBuilder append(float f) {
  229           super.append(f);
  230           return this;
  231       }
  232   
  233       public StringBuilder append(double d) {
  234           super.append(d);
  235           return this;
  236       }
  237   
  238       /**
  239        * @since 1.5
  240        */
  241       public StringBuilder appendCodePoint(int codePoint) {
  242           super.appendCodePoint(codePoint);
  243           return this;
  244       }
  245   
  246       /**
  247        * @throws StringIndexOutOfBoundsException {@inheritDoc}
  248        */
  249       public StringBuilder delete(int start, int end) {
  250           super.delete(start, end);
  251           return this;
  252       }
  253   
  254       /**
  255        * @throws StringIndexOutOfBoundsException {@inheritDoc}
  256        */
  257       public StringBuilder deleteCharAt(int index) {
  258           super.deleteCharAt(index);
  259           return this;
  260       }
  261   
  262       /**
  263        * @throws StringIndexOutOfBoundsException {@inheritDoc}
  264        */
  265       public StringBuilder replace(int start, int end, String str) {
  266           super.replace(start, end, str);
  267           return this;
  268       }
  269   
  270       /**
  271        * @throws StringIndexOutOfBoundsException {@inheritDoc}
  272        */
  273       public StringBuilder insert(int index, char[] str, int offset,
  274                                   int len)
  275       {
  276           super.insert(index, str, offset, len);
  277           return this;
  278       }
  279   
  280       /**
  281        * @throws StringIndexOutOfBoundsException {@inheritDoc}
  282        */
  283       public StringBuilder insert(int offset, Object obj) {
  284           return insert(offset, String.valueOf(obj));
  285       }
  286   
  287       /**
  288        * @throws StringIndexOutOfBoundsException {@inheritDoc}
  289        */
  290       public StringBuilder insert(int offset, String str) {
  291           super.insert(offset, str);
  292           return this;
  293       }
  294   
  295       /**
  296        * @throws StringIndexOutOfBoundsException {@inheritDoc}
  297        */
  298       public StringBuilder insert(int offset, char[] str) {
  299           super.insert(offset, str);
  300           return this;
  301       }
  302   
  303       /**
  304        * @throws IndexOutOfBoundsException {@inheritDoc}
  305        */
  306       public StringBuilder insert(int dstOffset, CharSequence s) {
  307           if (s == null)
  308               s = "null";
  309           if (s instanceof String)
  310               return this.insert(dstOffset, (String)s);
  311           return this.insert(dstOffset, s, 0, s.length());
  312       }
  313   
  314       /**
  315        * @throws IndexOutOfBoundsException {@inheritDoc}
  316        */
  317       public StringBuilder insert(int dstOffset, CharSequence s,
  318                                   int start, int end)
  319       {
  320           super.insert(dstOffset, s, start, end);
  321           return this;
  322       }
  323   
  324       /**
  325        * @throws StringIndexOutOfBoundsException {@inheritDoc}
  326        */
  327       public StringBuilder insert(int offset, boolean b) {
  328           super.insert(offset, b);
  329           return this;
  330       }
  331   
  332       /**
  333        * @throws IndexOutOfBoundsException {@inheritDoc}
  334        */
  335       public StringBuilder insert(int offset, char c) {
  336           super.insert(offset, c);
  337           return this;
  338       }
  339   
  340       /**
  341        * @throws StringIndexOutOfBoundsException {@inheritDoc}
  342        */
  343       public StringBuilder insert(int offset, int i) {
  344           return insert(offset, String.valueOf(i));
  345       }
  346   
  347       /**
  348        * @throws StringIndexOutOfBoundsException {@inheritDoc}
  349        */
  350       public StringBuilder insert(int offset, long l) {
  351           return insert(offset, String.valueOf(l));
  352       }
  353   
  354       /**
  355        * @throws StringIndexOutOfBoundsException {@inheritDoc}
  356        */
  357       public StringBuilder insert(int offset, float f) {
  358           return insert(offset, String.valueOf(f));
  359       }
  360   
  361       /**
  362        * @throws StringIndexOutOfBoundsException {@inheritDoc}
  363        */
  364       public StringBuilder insert(int offset, double d) {
  365           return insert(offset, String.valueOf(d));
  366       }
  367   
  368       /**
  369        * @throws NullPointerException {@inheritDoc}
  370        */
  371       public int indexOf(String str) {
  372           return indexOf(str, 0);
  373       }
  374   
  375       /**
  376        * @throws NullPointerException {@inheritDoc}
  377        */
  378       public int indexOf(String str, int fromIndex) {
  379           return String.indexOf(value, 0, count,
  380                                 str.toCharArray(), 0, str.length(), fromIndex);
  381       }
  382   
  383       /**
  384        * @throws NullPointerException {@inheritDoc}
  385        */
  386       public int lastIndexOf(String str) {
  387           return lastIndexOf(str, count);
  388       }
  389   
  390       /**
  391        * @throws NullPointerException {@inheritDoc}
  392        */
  393       public int lastIndexOf(String str, int fromIndex) {
  394           return String.lastIndexOf(value, 0, count,
  395                                 str.toCharArray(), 0, str.length(), fromIndex);
  396       }
  397   
  398       public StringBuilder reverse() {
  399           super.reverse();
  400           return this;
  401       }
  402   
  403       public String toString() {
  404           // Create a copy, don't share the array
  405           return new String(value, 0, count);
  406       }
  407   
  408       /**
  409        * Save the state of the <tt>StringBuilder</tt> instance to a stream
  410        * (that is, serialize it).
  411        *
  412        * @serialData the number of characters currently stored in the string
  413        *             builder (<tt>int</tt>), followed by the characters in the
  414        *             string builder (<tt>char[]</tt>).   The length of the
  415        *             <tt>char</tt> array may be greater than the number of
  416        *             characters currently stored in the string builder, in which
  417        *             case extra characters are ignored.
  418        */
  419       private void writeObject(java.io.ObjectOutputStream s)
  420           throws java.io.IOException {
  421           s.defaultWriteObject();
  422           s.writeInt(count);
  423           s.writeObject(value);
  424       }
  425   
  426       /**
  427        * readObject is called to restore the state of the StringBuffer from
  428        * a stream.
  429        */
  430       private void readObject(java.io.ObjectInputStream s)
  431           throws java.io.IOException, ClassNotFoundException {
  432           s.defaultReadObject();
  433           count = s.readInt();
  434           value = (char[]) s.readObject();
  435       }
  436   
  437   }

Home » openjdk-7 » java » lang » [javadoc | source]