1 /* 2 * Copyright (c) 2003, 2019, 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 * @apiNote 73 * {@code StringBuilder} implements {@code Comparable} but does not override 74 * {@link Object#equals equals}. Thus, the natural ordering of {@code StringBuilder} 75 * is inconsistent with equals. Care should be exercised if {@code StringBuilder} 76 * objects are used as keys in a {@code SortedMap} or elements in a {@code SortedSet}. 77 * See {@link Comparable}, {@link java.util.SortedMap SortedMap}, or 78 * {@link java.util.SortedSet SortedSet} for more information. 79 * 80 * @author Michael McCloskey 81 * @see java.lang.StringBuffer 82 * @see java.lang.String 83 * @since 1.5 84 */ 85 public final class StringBuilder 86 extends AbstractStringBuilder 87 implements java.io.Serializable, Comparable<StringBuilder>, CharSequence 88 { 89 90 /** use serialVersionUID for interoperability */ 91 static final long serialVersionUID = 4383685877147921099L; 92 93 /** 94 * Constructs a string builder with no characters in it and an 95 * initial capacity of 16 characters. 96 */ 97 @HotSpotIntrinsicCandidate 98 public StringBuilder() { 99 super(16); 100 } 101 102 /** 103 * Constructs a string builder with no characters in it and an 104 * initial capacity specified by the {@code capacity} argument. 105 * 106 * @param capacity the initial capacity. 107 * @throws NegativeArraySizeException if the {@code capacity} 108 * argument is less than {@code 0}. 109 */ 110 @HotSpotIntrinsicCandidate 111 public StringBuilder(int capacity) { 112 super(capacity); 113 } 114 115 /** 116 * Constructs a string builder initialized to the contents of the 117 * specified string. The initial capacity of the string builder is 118 * {@code 16} plus the length of the string argument. 119 * 120 * @param str the initial contents of the buffer. 121 */ 122 @HotSpotIntrinsicCandidate 123 public StringBuilder(String str) { 124 super(str); 125 } 126 127 /** 128 * Constructs a string builder that contains the same characters 129 * as the specified {@code CharSequence}. The initial capacity of 130 * the string builder is {@code 16} plus the length of the 131 * {@code CharSequence} argument. 132 * 133 * @param seq the sequence to copy. 134 */ 135 public StringBuilder(CharSequence seq) { 136 super(seq); 137 } 138 139 /** 140 * Compares two {@code StringBuilder} instances lexicographically. This method 141 * follows the same rules for lexicographical comparison as defined in the 142 * {@linkplain java.lang.CharSequence#compare(java.lang.CharSequence, 143 * java.lang.CharSequence) CharSequence.compare(this, another)} method. 144 * 145 * <p> 146 * For finer-grained, locale-sensitive String comparison, refer to 147 * {@link java.text.Collator}. 148 * 149 * @param another the {@code StringBuilder} to be compared with 150 * 151 * @return the value {@code 0} if this {@code StringBuilder} contains the same 152 * character sequence as that of the argument {@code StringBuilder}; a negative integer 153 * if this {@code StringBuilder} is lexicographically less than the 154 * {@code StringBuilder} argument; or a positive integer if this {@code StringBuilder} 155 * is lexicographically greater than the {@code StringBuilder} argument. 156 * 157 * @since 11 158 */ 159 @Override 160 public int compareTo(StringBuilder another) { 161 return super.compareTo(another); 162 } 163 164 @Override 165 public StringBuilder append(Object obj) { 166 return append(String.valueOf(obj)); 167 } 168 169 @Override 170 @HotSpotIntrinsicCandidate 171 public StringBuilder append(String str) { 172 super.append(str); 173 return this; 174 } 175 176 /** 177 * Appends the specified {@code StringBuffer} to this sequence. 178 * <p> 179 * The characters of the {@code StringBuffer} argument are appended, 180 * in order, to this sequence, increasing the 181 * length of this sequence by the length of the argument. 182 * If {@code sb} is {@code null}, then the four characters 183 * {@code "null"} are appended to this sequence. 184 * <p> 185 * Let <i>n</i> be the length of this character sequence just prior to 186 * execution of the {@code append} method. Then the character at index 187 * <i>k</i> in the new character sequence is equal to the character at 188 * index <i>k</i> in the old character sequence, if <i>k</i> is less than 189 * <i>n</i>; otherwise, it is equal to the character at index <i>k-n</i> 190 * in the argument {@code sb}. 191 * 192 * @param sb the {@code StringBuffer} to append. 193 * @return a reference to this object. 194 */ 195 public StringBuilder append(StringBuffer sb) { 196 super.append(sb); 197 return this; 198 } 199 200 @Override 201 public StringBuilder append(CharSequence s) { 202 super.append(s); 203 return this; 204 } 205 206 /** 207 * @throws IndexOutOfBoundsException {@inheritDoc} 208 */ 209 @Override 210 public StringBuilder append(CharSequence s, int start, int end) { 211 super.append(s, start, end); 212 return this; 213 } 214 215 @Override 216 public StringBuilder append(char[] str) { 217 super.append(str); 218 return this; 219 } 220 221 /** 222 * @throws IndexOutOfBoundsException {@inheritDoc} 223 */ 224 @Override 225 public StringBuilder append(char[] str, int offset, int len) { 226 super.append(str, offset, len); 227 return this; 228 } 229 230 @Override 231 public StringBuilder append(boolean b) { 232 super.append(b); 233 return this; 234 } 235 236 @Override 237 @HotSpotIntrinsicCandidate 238 public StringBuilder append(char c) { 239 super.append(c); 240 return this; 241 } 242 243 @Override 244 @HotSpotIntrinsicCandidate 245 public StringBuilder append(int i) { 246 super.append(i); 247 return this; 248 } 249 250 @Override 251 public StringBuilder append(long lng) { 252 super.append(lng); 253 return this; 254 } 255 256 @Override 257 public StringBuilder append(float f) { 258 super.append(f); 259 return this; 260 } 261 262 @Override 263 public StringBuilder append(double d) { 264 super.append(d); 265 return this; 266 } 267 268 /** 269 * @since 1.5 270 */ 271 @Override 272 public StringBuilder appendCodePoint(int codePoint) { 273 super.appendCodePoint(codePoint); 274 return this; 275 } 276 277 /** 278 * @throws StringIndexOutOfBoundsException {@inheritDoc} 279 */ 280 @Override 281 public StringBuilder delete(int start, int end) { 282 super.delete(start, end); 283 return this; 284 } 285 286 /** 287 * @throws StringIndexOutOfBoundsException {@inheritDoc} 288 */ 289 @Override 290 public StringBuilder deleteCharAt(int index) { 291 super.deleteCharAt(index); 292 return this; 293 } 294 295 /** 296 * @throws StringIndexOutOfBoundsException {@inheritDoc} 297 */ 298 @Override 299 public StringBuilder replace(int start, int end, String str) { 300 super.replace(start, end, str); 301 return this; 302 } 303 304 /** 305 * @throws StringIndexOutOfBoundsException {@inheritDoc} 306 */ 307 @Override 308 public StringBuilder insert(int index, char[] str, int offset, 309 int len) 310 { 311 super.insert(index, str, offset, len); 312 return this; 313 } 314 315 /** 316 * @throws StringIndexOutOfBoundsException {@inheritDoc} 317 */ 318 @Override 319 public StringBuilder insert(int offset, Object obj) { 320 super.insert(offset, obj); 321 return this; 322 } 323 324 /** 325 * @throws StringIndexOutOfBoundsException {@inheritDoc} 326 */ 327 @Override 328 public StringBuilder insert(int offset, String str) { 329 super.insert(offset, str); 330 return this; 331 } 332 333 /** 334 * @throws StringIndexOutOfBoundsException {@inheritDoc} 335 */ 336 @Override 337 public StringBuilder insert(int offset, char[] str) { 338 super.insert(offset, str); 339 return this; 340 } 341 342 /** 343 * @throws IndexOutOfBoundsException {@inheritDoc} 344 */ 345 @Override 346 public StringBuilder insert(int dstOffset, CharSequence s) { 347 super.insert(dstOffset, s); 348 return this; 349 } 350 351 /** 352 * @throws IndexOutOfBoundsException {@inheritDoc} 353 */ 354 @Override 355 public StringBuilder insert(int dstOffset, CharSequence s, 356 int start, int end) 357 { 358 super.insert(dstOffset, s, start, end); 359 return this; 360 } 361 362 /** 363 * @throws StringIndexOutOfBoundsException {@inheritDoc} 364 */ 365 @Override 366 public StringBuilder insert(int offset, boolean b) { 367 super.insert(offset, b); 368 return this; 369 } 370 371 /** 372 * @throws IndexOutOfBoundsException {@inheritDoc} 373 */ 374 @Override 375 public StringBuilder insert(int offset, char c) { 376 super.insert(offset, c); 377 return this; 378 } 379 380 /** 381 * @throws StringIndexOutOfBoundsException {@inheritDoc} 382 */ 383 @Override 384 public StringBuilder insert(int offset, int i) { 385 super.insert(offset, i); 386 return this; 387 } 388 389 /** 390 * @throws StringIndexOutOfBoundsException {@inheritDoc} 391 */ 392 @Override 393 public StringBuilder insert(int offset, long l) { 394 super.insert(offset, l); 395 return this; 396 } 397 398 /** 399 * @throws StringIndexOutOfBoundsException {@inheritDoc} 400 */ 401 @Override 402 public StringBuilder insert(int offset, float f) { 403 super.insert(offset, f); 404 return this; 405 } 406 407 /** 408 * @throws StringIndexOutOfBoundsException {@inheritDoc} 409 */ 410 @Override 411 public StringBuilder insert(int offset, double d) { 412 super.insert(offset, d); 413 return this; 414 } 415 416 @Override 417 public int indexOf(String str) { 418 return super.indexOf(str); 419 } 420 421 @Override 422 public int indexOf(String str, int fromIndex) { 423 return super.indexOf(str, fromIndex); 424 } 425 426 @Override 427 public int lastIndexOf(String str) { 428 return super.lastIndexOf(str); 429 } 430 431 @Override 432 public int lastIndexOf(String str, int fromIndex) { 433 return super.lastIndexOf(str, fromIndex); 434 } 435 436 @Override 437 public StringBuilder reverse() { 438 super.reverse(); 439 return this; 440 } 441 442 @Override 443 @HotSpotIntrinsicCandidate 444 public String toString() { 445 // Create a copy, don't share the array 446 return isLatin1() ? StringLatin1.newString(value, 0, count) 447 : StringUTF16.newString(value, 0, count); 448 } 449 450 /** 451 * Save the state of the {@code StringBuilder} instance to a stream 452 * (that is, serialize it). 453 * 454 * @serialData the number of characters currently stored in the string 455 * builder ({@code int}), followed by the characters in the 456 * string builder ({@code char[]}). The length of the 457 * {@code char} array may be greater than the number of 458 * characters currently stored in the string builder, in which 459 * case extra characters are ignored. 460 */ 461 private void writeObject(java.io.ObjectOutputStream s) 462 throws java.io.IOException { 463 s.defaultWriteObject(); 464 s.writeInt(count); 465 char[] val = new char[capacity()]; 466 if (isLatin1()) { 467 StringLatin1.getChars(value, 0, count, val, 0); 468 } else { 469 StringUTF16.getChars(value, 0, count, val, 0); 470 } 471 s.writeObject(val); 472 } 473 474 /** 475 * readObject is called to restore the state of the StringBuffer from 476 * a stream. 477 */ 478 private void readObject(java.io.ObjectInputStream s) 479 throws java.io.IOException, ClassNotFoundException { 480 s.defaultReadObject(); 481 count = s.readInt(); 482 char[] val = (char[]) s.readObject(); 483 initBytes(val, 0, val.length); 484 } 485 486 }