1 /*
   2  * Copyright (c) 2003, 2012, 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}, but with no guarantee of synchronization.
  32  * This class is designed for use as a drop-in replacement for
  33  * {@code StringBuffer} 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} as it will be faster under most implementations.
  37  *
  38  * <p>The principal operations on a {@code StringBuilder} are the
  39  * {@code append} and {@code insert} 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} method always adds these characters at the end
  44  * of the builder; the {@code insert} method adds the characters at
  45  * a specified point.
  46  * <p>
  47  * For example, if {@code z} refers to a string builder object
  48  * whose current contents are "{@code start}", then
  49  * the method call {@code z.append("le")} would cause the string
  50  * builder to contain "{@code startle}", whereas
  51  * {@code z.insert(4, "le")} would alter the string builder to
  52  * contain "{@code starlet}".
  53  * <p>
  54  * In general, if sb refers to an instance of a {@code StringBuilder},
  55  * then {@code sb.append(x)} has the same effect as
  56  * {@code sb.insert(sb.length(), x)}.
  57  * <p>
  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} 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  * <p>Unless otherwise noted, passing a {@code null} argument to a constructor
  68  * or method in this class will cause a {@link NullPointerException} to be
  69  * thrown.
  70  *
  71  * @author      Michael McCloskey
  72  * @see         java.lang.StringBuffer
  73  * @see         java.lang.String
  74  * @since       1.5
  75  */
  76 public final class StringBuilder
  77     extends AbstractStringBuilder
  78     implements java.io.Serializable, CharSequence
  79 {
  80 
  81     /** use serialVersionUID for interoperability */
  82     static final long serialVersionUID = 4383685877147921099L;
  83 
  84     /**
  85      * Constructs a string builder with no characters in it and an
  86      * initial capacity of 16 characters.
  87      */
  88     public StringBuilder() {
  89         super(16);
  90     }
  91 
  92     /**
  93      * Constructs a string builder with no characters in it and an
  94      * initial capacity specified by the {@code capacity} argument.
  95      *
  96      * @param      capacity  the initial capacity.
  97      * @throws     NegativeArraySizeException  if the {@code capacity}
  98      *               argument is less than {@code 0}.
  99      */
 100     public StringBuilder(int capacity) {
 101         super(capacity);
 102     }
 103 
 104     /**
 105      * Constructs a string builder initialized to the contents of the
 106      * specified string. The initial capacity of the string builder is
 107      * {@code 16} plus the length of the string argument.
 108      *
 109      * @param   str   the initial contents of the buffer.
 110      */
 111     public StringBuilder(String str) {
 112         super(str.length() + 16);
 113         append(str);
 114     }
 115 
 116     /**
 117      * Constructs a string builder that contains the same characters
 118      * as the specified {@code CharSequence}. The initial capacity of
 119      * the string builder is {@code 16} plus the length of the
 120      * {@code CharSequence} argument.
 121      *
 122      * @param      seq   the sequence to copy.
 123      */
 124     public StringBuilder(CharSequence seq) {
 125         this(seq.length() + 16);
 126         append(seq);
 127     }
 128 
 129     @Override
 130     public StringBuilder append(Object obj) {
 131         return append(String.valueOf(obj));
 132     }
 133 
 134     @Override
 135     public StringBuilder append(String str) {
 136         super.append(str);
 137         return this;
 138     }
 139 
 140     /**
 141      * Appends the specified {@code StringBuffer} to this sequence.
 142      * <p>
 143      * The characters of the {@code StringBuffer} argument are appended,
 144      * in order, to this sequence, increasing the
 145      * length of this sequence by the length of the argument.
 146      * If {@code sb} is {@code null}, then the four characters
 147      * {@code "null"} are appended to this sequence.
 148      * <p>
 149      * Let <i>n</i> be the length of this character sequence just prior to
 150      * execution of the {@code append} method. Then the character at index
 151      * <i>k</i> in the new character sequence is equal to the character at
 152      * index <i>k</i> in the old character sequence, if <i>k</i> is less than
 153      * <i>n</i>; otherwise, it is equal to the character at index <i>k-n</i>
 154      * in the argument {@code sb}.
 155      *
 156      * @param   sb   the {@code StringBuffer} to append.
 157      * @return  a reference to this object.
 158      */
 159     public StringBuilder append(StringBuffer sb) {
 160         super.append(sb);
 161         return this;
 162     }
 163 
 164     @Override
 165     public StringBuilder append(CharSequence s) {
 166         super.append(s);
 167         return this;
 168     }
 169 
 170     /**
 171      * @throws     IndexOutOfBoundsException {@inheritDoc}
 172      */
 173     @Override
 174     public StringBuilder append(CharSequence s, int start, int end) {
 175         super.append(s, start, end);
 176         return this;
 177     }
 178 
 179     @Override
 180     public StringBuilder append(char[] str) {
 181         super.append(str);
 182         return this;
 183     }
 184 
 185     /**
 186      * @throws IndexOutOfBoundsException {@inheritDoc}
 187      */
 188     @Override
 189     public StringBuilder append(char[] str, int offset, int len) {
 190         super.append(str, offset, len);
 191         return this;
 192     }
 193 
 194     @Override
 195     public StringBuilder append(boolean b) {
 196         super.append(b);
 197         return this;
 198     }
 199 
 200     @Override
 201     public StringBuilder append(char c) {
 202         super.append(c);
 203         return this;
 204     }
 205 
 206     @Override
 207     public StringBuilder append(int i) {
 208         super.append(i);
 209         return this;
 210     }
 211 
 212     @Override
 213     public StringBuilder append(long lng) {
 214         super.append(lng);
 215         return this;
 216     }
 217 
 218     @Override
 219     public StringBuilder append(float f) {
 220         super.append(f);
 221         return this;
 222     }
 223 
 224     @Override
 225     public StringBuilder append(double d) {
 226         super.append(d);
 227         return this;
 228     }
 229 
 230     /**
 231      * @since 1.5
 232      */
 233     @Override
 234     public StringBuilder appendCodePoint(int codePoint) {
 235         super.appendCodePoint(codePoint);
 236         return this;
 237     }
 238 
 239     /**
 240      * @throws StringIndexOutOfBoundsException {@inheritDoc}
 241      */
 242     @Override
 243     public StringBuilder delete(int start, int end) {
 244         super.delete(start, end);
 245         return this;
 246     }
 247 
 248     /**
 249      * @throws StringIndexOutOfBoundsException {@inheritDoc}
 250      */
 251     @Override
 252     public StringBuilder deleteCharAt(int index) {
 253         super.deleteCharAt(index);
 254         return this;
 255     }
 256 
 257     /**
 258      * @throws StringIndexOutOfBoundsException {@inheritDoc}
 259      */
 260     @Override
 261     public StringBuilder replace(int start, int end, String str) {
 262         super.replace(start, end, str);
 263         return this;
 264     }
 265 
 266     /**
 267      * @throws StringIndexOutOfBoundsException {@inheritDoc}
 268      */
 269     @Override
 270     public StringBuilder insert(int index, char[] str, int offset,
 271                                 int len)
 272     {
 273         super.insert(index, str, offset, len);
 274         return this;
 275     }
 276 
 277     /**
 278      * @throws StringIndexOutOfBoundsException {@inheritDoc}
 279      */
 280     @Override
 281     public StringBuilder insert(int offset, Object obj) {
 282             super.insert(offset, obj);
 283             return this;
 284     }
 285 
 286     /**
 287      * @throws StringIndexOutOfBoundsException {@inheritDoc}
 288      */
 289     @Override
 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     @Override
 299     public StringBuilder insert(int offset, char[] str) {
 300         super.insert(offset, str);
 301         return this;
 302     }
 303 
 304     /**
 305      * @throws IndexOutOfBoundsException {@inheritDoc}
 306      */
 307     @Override
 308     public StringBuilder insert(int dstOffset, CharSequence s) {
 309             super.insert(dstOffset, s);
 310             return this;
 311     }
 312 
 313     /**
 314      * @throws IndexOutOfBoundsException {@inheritDoc}
 315      */
 316     @Override
 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     @Override
 328     public StringBuilder insert(int offset, boolean b) {
 329         super.insert(offset, b);
 330         return this;
 331     }
 332 
 333     /**
 334      * @throws IndexOutOfBoundsException {@inheritDoc}
 335      */
 336     @Override
 337     public StringBuilder insert(int offset, char c) {
 338         super.insert(offset, c);
 339         return this;
 340     }
 341 
 342     /**
 343      * @throws StringIndexOutOfBoundsException {@inheritDoc}
 344      */
 345     @Override
 346     public StringBuilder insert(int offset, int i) {
 347         super.insert(offset, i);
 348         return this;
 349     }
 350 
 351     /**
 352      * @throws StringIndexOutOfBoundsException {@inheritDoc}
 353      */
 354     @Override
 355     public StringBuilder insert(int offset, long l) {
 356         super.insert(offset, l);
 357         return this;
 358     }
 359 
 360     /**
 361      * @throws StringIndexOutOfBoundsException {@inheritDoc}
 362      */
 363     @Override
 364     public StringBuilder insert(int offset, float f) {
 365         super.insert(offset, f);
 366         return this;
 367     }
 368 
 369     /**
 370      * @throws StringIndexOutOfBoundsException {@inheritDoc}
 371      */
 372     @Override
 373     public StringBuilder insert(int offset, double d) {
 374         super.insert(offset, d);
 375         return this;
 376     }
 377 
 378     @Override
 379     public int indexOf(String str) {
 380         return super.indexOf(str);
 381     }
 382 
 383     @Override
 384     public int indexOf(String str, int fromIndex) {
 385         return super.indexOf(str, fromIndex);
 386     }
 387 
 388     @Override
 389     public int lastIndexOf(String str) {
 390         return super.lastIndexOf(str);
 391     }
 392 
 393     @Override
 394     public int lastIndexOf(String str, int fromIndex) {
 395         return super.lastIndexOf(str, fromIndex);
 396     }
 397 
 398     @Override
 399     public StringBuilder reverse() {
 400         super.reverse();
 401         return this;
 402     }
 403 
 404     @Override
 405     public String toString() {
 406         // Create a copy, don't share the array
 407         return new String(value, 0, count);
 408     }
 409 
 410     /**
 411      * Save the state of the {@code StringBuilder} instance to a stream
 412      * (that is, serialize it).
 413      *
 414      * @serialData the number of characters currently stored in the string
 415      *             builder ({@code int}), followed by the characters in the
 416      *             string builder ({@code char[]}).   The length of the
 417      *             {@code char} array may be greater than the number of
 418      *             characters currently stored in the string builder, in which
 419      *             case extra characters are ignored.
 420      */
 421     private void writeObject(java.io.ObjectOutputStream s)
 422         throws java.io.IOException {
 423         s.defaultWriteObject();
 424         s.writeInt(count);
 425         s.writeObject(value);
 426     }
 427 
 428     /**
 429      * readObject is called to restore the state of the StringBuffer from
 430      * a stream.
 431      */
 432     private void readObject(java.io.ObjectInputStream s)
 433         throws java.io.IOException, ClassNotFoundException {
 434         s.defaultReadObject();
 435         count = s.readInt();
 436         value = (char[]) s.readObject();
 437     }
 438 
 439 }