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