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