1 /* 2 * Copyright (c) 1994, 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 java.util.Arrays; 29 import jdk.internal.HotSpotIntrinsicCandidate; 30 31 /** 32 * A thread-safe, mutable sequence of characters. 33 * A string buffer is like a {@link String}, but can be modified. At any 34 * point in time it contains some particular sequence of characters, but 35 * the length and content of the sequence can be changed through certain 36 * method calls. 37 * <p> 38 * String buffers are safe for use by multiple threads. The methods 39 * are synchronized where necessary so that all the operations on any 40 * particular instance behave as if they occur in some serial order 41 * that is consistent with the order of the method calls made by each of 42 * the individual threads involved. 43 * <p> 44 * The principal operations on a {@code StringBuffer} are the 45 * {@code append} and {@code insert} methods, which are 46 * overloaded so as to accept data of any type. Each effectively 47 * converts a given datum to a string and then appends or inserts the 48 * characters of that string to the string buffer. The 49 * {@code append} method always adds these characters at the end 50 * of the buffer; the {@code insert} method adds the characters at 51 * a specified point. 52 * <p> 53 * For example, if {@code z} refers to a string buffer object 54 * whose current contents are {@code "start"}, then 55 * the method call {@code z.append("le")} would cause the string 56 * buffer to contain {@code "startle"}, whereas 57 * {@code z.insert(4, "le")} would alter the string buffer to 58 * contain {@code "starlet"}. 59 * <p> 60 * In general, if sb refers to an instance of a {@code StringBuffer}, 61 * then {@code sb.append(x)} has the same effect as 62 * {@code sb.insert(sb.length(), x)}. 63 * <p> 64 * Whenever an operation occurs involving a source sequence (such as 65 * appending or inserting from a source sequence), this class synchronizes 66 * only on the string buffer performing the operation, not on the source. 67 * Note that while {@code StringBuffer} is designed to be safe to use 68 * concurrently from multiple threads, if the constructor or the 69 * {@code append} or {@code insert} operation is passed a source sequence 70 * that is shared across threads, the calling code must ensure 71 * that the operation has a consistent and unchanging view of the source 72 * sequence for the duration of the operation. 73 * This could be satisfied by the caller holding a lock during the 74 * operation's call, by using an immutable source sequence, or by not 75 * sharing the source sequence across threads. 76 * <p> 77 * Every string buffer has a capacity. As long as the length of the 78 * character sequence contained in the string buffer does not exceed 79 * the capacity, it is not necessary to allocate a new internal 80 * buffer array. If the internal buffer overflows, it is 81 * automatically made larger. 82 * <p> 83 * Unless otherwise noted, passing a {@code null} argument to a constructor 84 * or method in this class will cause a {@link NullPointerException} to be 85 * thrown. 86 * <p> 87 * As of release JDK 5, this class has been supplemented with an equivalent 88 * class designed for use by a single thread, {@link StringBuilder}. The 89 * {@code StringBuilder} class should generally be used in preference to 90 * this one, as it supports all of the same operations but it is faster, as 91 * it performs no synchronization. 92 * 93 * @author Arthur van Hoff 94 * @see java.lang.StringBuilder 95 * @see java.lang.String 96 * @since 1.0 97 */ 98 public final class StringBuffer 99 extends AbstractStringBuilder 100 implements java.io.Serializable, CharSequence 101 { 102 103 /** 104 * A cache of the last value returned by toString. Cleared 105 * whenever the StringBuffer is modified. 106 */ 107 private transient String toStringCache; 108 109 /** use serialVersionUID from JDK 1.0.2 for interoperability */ 110 static final long serialVersionUID = 3388685877147921107L; 111 112 /** 113 * Constructs a string buffer with no characters in it and an 114 * initial capacity of 16 characters. 115 */ 116 @HotSpotIntrinsicCandidate 117 public StringBuffer() { 118 super(16); 119 } 120 121 /** 122 * Constructs a string buffer with no characters in it and 123 * the specified initial capacity. 124 * 125 * @param capacity the initial capacity. 126 * @exception NegativeArraySizeException if the {@code capacity} 127 * argument is less than {@code 0}. 128 */ 129 @HotSpotIntrinsicCandidate 130 public StringBuffer(int capacity) { 131 super(capacity); 132 } 133 134 /** 135 * Constructs a string buffer initialized to the contents of the 136 * specified string. The initial capacity of the string buffer is 137 * {@code 16} plus the length of the string argument. 138 * 139 * @param str the initial contents of the buffer. 140 */ 141 @HotSpotIntrinsicCandidate 142 public StringBuffer(String str) { 143 super(str.length() + 16); 144 append(str); 145 } 146 147 /** 148 * Constructs a string buffer that contains the same characters 149 * as the specified {@code CharSequence}. The initial capacity of 150 * the string buffer is {@code 16} plus the length of the 151 * {@code CharSequence} argument. 152 * <p> 153 * If the length of the specified {@code CharSequence} is 154 * less than or equal to zero, then an empty buffer of capacity 155 * {@code 16} is returned. 156 * 157 * @param seq the sequence to copy. 158 * @since 1.5 159 */ 160 public StringBuffer(CharSequence seq) { 161 this(seq.length() + 16); 162 append(seq); 163 } 164 165 @Override 166 public synchronized int length() { 167 return count; 168 } 169 170 @Override 171 public synchronized int capacity() { 172 return super.capacity(); 173 } 174 175 176 @Override 177 public synchronized void ensureCapacity(int minimumCapacity) { 178 super.ensureCapacity(minimumCapacity); 179 } 180 181 /** 182 * @since 1.5 183 */ 184 @Override 185 public synchronized void trimToSize() { 186 super.trimToSize(); 187 } 188 189 /** 190 * @throws IndexOutOfBoundsException {@inheritDoc} 191 * @see #length() 192 */ 193 @Override 194 public synchronized void setLength(int newLength) { 195 toStringCache = null; 196 super.setLength(newLength); 197 } 198 199 /** 200 * @throws IndexOutOfBoundsException {@inheritDoc} 201 * @see #length() 202 */ 203 @Override 204 public synchronized char charAt(int index) { 205 return super.charAt(index); 206 } 207 208 /** 209 * @throws IndexOutOfBoundsException {@inheritDoc} 210 * @since 1.5 211 */ 212 @Override 213 public synchronized int codePointAt(int index) { 214 return super.codePointAt(index); 215 } 216 217 /** 218 * @throws IndexOutOfBoundsException {@inheritDoc} 219 * @since 1.5 220 */ 221 @Override 222 public synchronized int codePointBefore(int index) { 223 return super.codePointBefore(index); 224 } 225 226 /** 227 * @throws IndexOutOfBoundsException {@inheritDoc} 228 * @since 1.5 229 */ 230 @Override 231 public synchronized int codePointCount(int beginIndex, int endIndex) { 232 return super.codePointCount(beginIndex, endIndex); 233 } 234 235 /** 236 * @throws IndexOutOfBoundsException {@inheritDoc} 237 * @since 1.5 238 */ 239 @Override 240 public synchronized int offsetByCodePoints(int index, int codePointOffset) { 241 return super.offsetByCodePoints(index, codePointOffset); 242 } 243 244 /** 245 * @throws IndexOutOfBoundsException {@inheritDoc} 246 */ 247 @Override 248 public synchronized void getChars(int srcBegin, int srcEnd, char[] dst, 249 int dstBegin) 250 { 251 super.getChars(srcBegin, srcEnd, dst, dstBegin); 252 } 253 254 /** 255 * @throws IndexOutOfBoundsException {@inheritDoc} 256 * @see #length() 257 */ 258 @Override 259 public synchronized void setCharAt(int index, char ch) { 260 toStringCache = null; 261 super.setCharAt(index, ch); 262 } 263 264 @Override 265 public synchronized StringBuffer append(Object obj) { 266 toStringCache = null; 267 super.append(String.valueOf(obj)); 268 return this; 269 } 270 271 @Override 272 @HotSpotIntrinsicCandidate 273 public synchronized StringBuffer append(String str) { 274 toStringCache = null; 275 super.append(str); 276 return this; 277 } 278 279 /** 280 * Appends the specified {@code StringBuffer} to this sequence. 281 * <p> 282 * The characters of the {@code StringBuffer} argument are appended, 283 * in order, to the contents of this {@code StringBuffer}, increasing the 284 * length of this {@code StringBuffer} by the length of the argument. 285 * If {@code sb} is {@code null}, then the four characters 286 * {@code "null"} are appended to this {@code StringBuffer}. 287 * <p> 288 * Let <i>n</i> be the length of the old character sequence, the one 289 * contained in the {@code StringBuffer} just prior to execution of the 290 * {@code append} method. Then the character at index <i>k</i> in 291 * the new character sequence is equal to the character at index <i>k</i> 292 * in the old character sequence, if <i>k</i> is less than <i>n</i>; 293 * otherwise, it is equal to the character at index <i>k-n</i> in the 294 * argument {@code sb}. 295 * <p> 296 * This method synchronizes on {@code this}, the destination 297 * object, but does not synchronize on the source ({@code sb}). 298 * 299 * @param sb the {@code StringBuffer} to append. 300 * @return a reference to this object. 301 * @since 1.4 302 */ 303 public synchronized StringBuffer append(StringBuffer sb) { 304 toStringCache = null; 305 super.append(sb); 306 return this; 307 } 308 309 /** 310 * @since 1.8 311 */ 312 @Override 313 synchronized StringBuffer append(AbstractStringBuilder asb) { 314 toStringCache = null; 315 super.append(asb); 316 return this; 317 } 318 319 /** 320 * Appends the specified {@code CharSequence} to this 321 * sequence. 322 * <p> 323 * The characters of the {@code CharSequence} argument are appended, 324 * in order, increasing the length of this sequence by the length of the 325 * argument. 326 * 327 * <p>The result of this method is exactly the same as if it were an 328 * invocation of this.append(s, 0, s.length()); 329 * 330 * <p>This method synchronizes on {@code this}, the destination 331 * object, but does not synchronize on the source ({@code s}). 332 * 333 * <p>If {@code s} is {@code null}, then the four characters 334 * {@code "null"} are appended. 335 * 336 * @param s the {@code CharSequence} to append. 337 * @return a reference to this object. 338 * @since 1.5 339 */ 340 @Override 341 public synchronized StringBuffer append(CharSequence s) { 342 toStringCache = null; 343 super.append(s); 344 return this; 345 } 346 347 /** 348 * @throws IndexOutOfBoundsException {@inheritDoc} 349 * @since 1.5 350 */ 351 @Override 352 public synchronized StringBuffer append(CharSequence s, int start, int end) 353 { 354 toStringCache = null; 355 super.append(s, start, end); 356 return this; 357 } 358 359 @Override 360 public synchronized StringBuffer append(char[] str) { 361 toStringCache = null; 362 super.append(str); 363 return this; 364 } 365 366 /** 367 * @throws IndexOutOfBoundsException {@inheritDoc} 368 */ 369 @Override 370 public synchronized StringBuffer append(char[] str, int offset, int len) { 371 toStringCache = null; 372 super.append(str, offset, len); 373 return this; 374 } 375 376 @Override 377 public synchronized StringBuffer append(boolean b) { 378 toStringCache = null; 379 super.append(b); 380 return this; 381 } 382 383 @Override 384 @HotSpotIntrinsicCandidate 385 public synchronized StringBuffer append(char c) { 386 toStringCache = null; 387 super.append(c); 388 return this; 389 } 390 391 @Override 392 @HotSpotIntrinsicCandidate 393 public synchronized StringBuffer append(int i) { 394 toStringCache = null; 395 super.append(i); 396 return this; 397 } 398 399 /** 400 * @since 1.5 401 */ 402 @Override 403 public synchronized StringBuffer appendCodePoint(int codePoint) { 404 toStringCache = null; 405 super.appendCodePoint(codePoint); 406 return this; 407 } 408 409 @Override 410 public synchronized StringBuffer append(long lng) { 411 toStringCache = null; 412 super.append(lng); 413 return this; 414 } 415 416 @Override 417 public synchronized StringBuffer append(float f) { 418 toStringCache = null; 419 super.append(f); 420 return this; 421 } 422 423 @Override 424 public synchronized StringBuffer append(double d) { 425 toStringCache = null; 426 super.append(d); 427 return this; 428 } 429 430 /** 431 * @throws StringIndexOutOfBoundsException {@inheritDoc} 432 * @since 1.2 433 */ 434 @Override 435 public synchronized StringBuffer delete(int start, int end) { 436 toStringCache = null; 437 super.delete(start, end); 438 return this; 439 } 440 441 /** 442 * @throws StringIndexOutOfBoundsException {@inheritDoc} 443 * @since 1.2 444 */ 445 @Override 446 public synchronized StringBuffer deleteCharAt(int index) { 447 toStringCache = null; 448 super.deleteCharAt(index); 449 return this; 450 } 451 452 /** 453 * @throws StringIndexOutOfBoundsException {@inheritDoc} 454 * @since 1.2 455 */ 456 @Override 457 public synchronized StringBuffer replace(int start, int end, String str) { 458 toStringCache = null; 459 super.replace(start, end, str); 460 return this; 461 } 462 463 /** 464 * @throws StringIndexOutOfBoundsException {@inheritDoc} 465 * @since 1.2 466 */ 467 @Override 468 public synchronized String substring(int start) { 469 return substring(start, count); 470 } 471 472 /** 473 * @throws IndexOutOfBoundsException {@inheritDoc} 474 * @since 1.4 475 */ 476 @Override 477 public synchronized CharSequence subSequence(int start, int end) { 478 return super.substring(start, end); 479 } 480 481 /** 482 * @throws StringIndexOutOfBoundsException {@inheritDoc} 483 * @since 1.2 484 */ 485 @Override 486 public synchronized String substring(int start, int end) { 487 return super.substring(start, end); 488 } 489 490 /** 491 * @throws StringIndexOutOfBoundsException {@inheritDoc} 492 * @since 1.2 493 */ 494 @Override 495 public synchronized StringBuffer insert(int index, char[] str, int offset, 496 int len) 497 { 498 toStringCache = null; 499 super.insert(index, str, offset, len); 500 return this; 501 } 502 503 /** 504 * @throws StringIndexOutOfBoundsException {@inheritDoc} 505 */ 506 @Override 507 public synchronized StringBuffer insert(int offset, Object obj) { 508 toStringCache = null; 509 super.insert(offset, String.valueOf(obj)); 510 return this; 511 } 512 513 /** 514 * @throws StringIndexOutOfBoundsException {@inheritDoc} 515 */ 516 @Override 517 public synchronized StringBuffer insert(int offset, String str) { 518 toStringCache = null; 519 super.insert(offset, str); 520 return this; 521 } 522 523 /** 524 * @throws StringIndexOutOfBoundsException {@inheritDoc} 525 */ 526 @Override 527 public synchronized StringBuffer insert(int offset, char[] str) { 528 toStringCache = null; 529 super.insert(offset, str); 530 return this; 531 } 532 533 /** 534 * @throws IndexOutOfBoundsException {@inheritDoc} 535 * @since 1.5 536 */ 537 @Override 538 public StringBuffer insert(int dstOffset, CharSequence s) { 539 // Note, synchronization achieved via invocations of other StringBuffer methods 540 // after narrowing of s to specific type 541 // Ditto for toStringCache clearing 542 super.insert(dstOffset, s); 543 return this; 544 } 545 546 /** 547 * @throws IndexOutOfBoundsException {@inheritDoc} 548 * @since 1.5 549 */ 550 @Override 551 public synchronized StringBuffer insert(int dstOffset, CharSequence s, 552 int start, int end) 553 { 554 toStringCache = null; 555 super.insert(dstOffset, s, start, end); 556 return this; 557 } 558 559 /** 560 * @throws StringIndexOutOfBoundsException {@inheritDoc} 561 */ 562 @Override 563 public StringBuffer insert(int offset, boolean b) { 564 // Note, synchronization achieved via invocation of StringBuffer insert(int, String) 565 // after conversion of b to String by super class method 566 // Ditto for toStringCache clearing 567 super.insert(offset, b); 568 return this; 569 } 570 571 /** 572 * @throws IndexOutOfBoundsException {@inheritDoc} 573 */ 574 @Override 575 public synchronized StringBuffer insert(int offset, char c) { 576 toStringCache = null; 577 super.insert(offset, c); 578 return this; 579 } 580 581 /** 582 * @throws StringIndexOutOfBoundsException {@inheritDoc} 583 */ 584 @Override 585 public StringBuffer insert(int offset, int i) { 586 // Note, synchronization achieved via invocation of StringBuffer insert(int, String) 587 // after conversion of i to String by super class method 588 // Ditto for toStringCache clearing 589 super.insert(offset, i); 590 return this; 591 } 592 593 /** 594 * @throws StringIndexOutOfBoundsException {@inheritDoc} 595 */ 596 @Override 597 public StringBuffer insert(int offset, long l) { 598 // Note, synchronization achieved via invocation of StringBuffer insert(int, String) 599 // after conversion of l to String by super class method 600 // Ditto for toStringCache clearing 601 super.insert(offset, l); 602 return this; 603 } 604 605 /** 606 * @throws StringIndexOutOfBoundsException {@inheritDoc} 607 */ 608 @Override 609 public StringBuffer insert(int offset, float f) { 610 // Note, synchronization achieved via invocation of StringBuffer insert(int, String) 611 // after conversion of f to String by super class method 612 // Ditto for toStringCache clearing 613 super.insert(offset, f); 614 return this; 615 } 616 617 /** 618 * @throws StringIndexOutOfBoundsException {@inheritDoc} 619 */ 620 @Override 621 public StringBuffer insert(int offset, double d) { 622 // Note, synchronization achieved via invocation of StringBuffer insert(int, String) 623 // after conversion of d to String by super class method 624 // Ditto for toStringCache clearing 625 super.insert(offset, d); 626 return this; 627 } 628 629 /** 630 * @since 1.4 631 */ 632 @Override 633 public int indexOf(String str) { 634 // Note, synchronization achieved via invocations of other StringBuffer methods 635 return super.indexOf(str); 636 } 637 638 /** 639 * @since 1.4 640 */ 641 @Override 642 public synchronized int indexOf(String str, int fromIndex) { 643 return super.indexOf(str, fromIndex); 644 } 645 646 /** 647 * @since 1.4 648 */ 649 @Override 650 public int lastIndexOf(String str) { 651 // Note, synchronization achieved via invocations of other StringBuffer methods 652 return lastIndexOf(str, count); 653 } 654 655 /** 656 * @since 1.4 657 */ 658 @Override 659 public synchronized int lastIndexOf(String str, int fromIndex) { 660 return super.lastIndexOf(str, fromIndex); 661 } 662 663 /** 664 * @since 1.0.2 665 */ 666 @Override 667 public synchronized StringBuffer reverse() { 668 toStringCache = null; 669 super.reverse(); 670 return this; 671 } 672 673 @Override 674 @HotSpotIntrinsicCandidate 675 public synchronized String toString() { 676 if (toStringCache == null) { 677 return toStringCache = 678 isLatin1() ? StringLatin1.newString(value, 0, count) 679 : StringUTF16.newString(value, 0, count); 680 } 681 return new String(toStringCache); 682 } 683 684 /** 685 * Serializable fields for StringBuffer. 686 * 687 * @serialField value char[] 688 * The backing character array of this StringBuffer. 689 * @serialField count int 690 * The number of characters in this StringBuffer. 691 * @serialField shared boolean 692 * A flag indicating whether the backing array is shared. 693 * The value is ignored upon deserialization. 694 */ 695 private static final java.io.ObjectStreamField[] serialPersistentFields = 696 { 697 new java.io.ObjectStreamField("value", char[].class), 698 new java.io.ObjectStreamField("count", Integer.TYPE), 699 new java.io.ObjectStreamField("shared", Boolean.TYPE), 700 }; 701 702 /** 703 * readObject is called to restore the state of the StringBuffer from 704 * a stream. 705 */ 706 private synchronized void writeObject(java.io.ObjectOutputStream s) 707 throws java.io.IOException { 708 java.io.ObjectOutputStream.PutField fields = s.putFields(); 709 char[] val = new char[capacity()]; 710 if (isLatin1()) { 711 StringLatin1.getChars(value, 0, count, val, 0); 712 } else { 713 StringUTF16.getChars(value, 0, count, val, 0); 714 } 715 fields.put("value", val); 716 fields.put("count", count); 717 fields.put("shared", false); 718 s.writeFields(); 719 } 720 721 /** 722 * readObject is called to restore the state of the StringBuffer from 723 * a stream. 724 */ 725 private void readObject(java.io.ObjectInputStream s) 726 throws java.io.IOException, ClassNotFoundException { 727 java.io.ObjectInputStream.GetField fields = s.readFields(); 728 char[] val = (char[])fields.get("value", null); 729 initBytes(val, 0, val.length); 730 count = fields.get("count", 0); 731 } 732 733 synchronized void getBytes(byte dst[], int dstBegin, byte coder) { 734 super.getBytes(dst, dstBegin, coder); 735 } 736 }