- 001
/* - 002
* @(#)StringBuffer.java 1.101 05/11/17 - 003 *
- 004 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
- 005 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
- 006
*/ - 007
- 008package java.lang;
- 009
- 010
- 011/**
- 012 * A thread-safe, mutable sequence of characters.
- 013 * A string buffer is like a {@link String}, but can be modified. At any
- 014 * point in time it contains some particular sequence of characters, but
- 015 * the length and content of the sequence can be changed through certain
- 016 * method calls.
- 017 * <p>
- 018 * String buffers are safe for use by multiple threads. The methods
- 019 * are synchronized where necessary so that all the operations on any
- 020 * particular instance behave as if they occur in some serial order
- 021 * that is consistent with the order of the method calls made by each of
- 022 * the individual threads involved.
- 023 * <p>
- 024 * The principal operations on a <code>StringBuffer</code> are the
- 025 * <code>append</code> and <code>insert</code> methods, which are
- 026 * overloaded so as to accept data of any type. Each effectively
- 027 * converts a given datum to a string and then appends or inserts the
- 028 * characters of that string to the string buffer. The
- 029 * <code>append</code> method always adds these characters at the end
- 030 * of the buffer; the <code>insert</code> method adds the characters at
- 031 * a specified point.
- 032 * <p>
- 033 * For example, if <code>z</code> refers to a string buffer object
- 034 * whose current contents are "<code>start</code>", then
- 035 * the method call <code>z.append("le")</code> would cause the string
- 036 * buffer to contain "<code>startle</code>", whereas
- 037 * <code>z.insert(4, "le")</code> would alter the string buffer to
- 038 * contain "<code>starlet</code>".
- 039 * <p>
- 040 * In general, if sb refers to an instance of a <code>StringBuffer</code>,
- 041 * then <code>sb.append(x)</code> has the same effect as
- 042 * <code>sb.insert(sb.length(), x)</code>.
- 043 * <p>
- 044 * Whenever an operation occurs involving a source sequence (such as
- 045 * appending or inserting from a source sequence) this class synchronizes
- 046 * only on the string buffer performing the operation, not on the source.
- 047 * <p>
- 048 * Every string buffer has a capacity. As long as the length of the
- 049 * character sequence contained in the string buffer does not exceed
- 050 * the capacity, it is not necessary to allocate a new internal
- 051 * buffer array. If the internal buffer overflows, it is
- 052 * automatically made larger.
- 053 *
- 054 * As of release JDK 5, this class has been supplemented with an equivalent
- 055 * class designed for use by a single thread, {@link StringBuilder}. The
- 056 * <tt>StringBuilder</tt> class should generally be used in preference to
- 057 * this one, as it supports all of the same operations but it is faster, as
- 058 * it performs no synchronization.
- 059 *
- 060 * @author Arthur van Hoff
- 061 * @version 1.101, 11/17/05
- 062 * @see java.lang.StringBuilder
- 063 * @see java.lang.String
- 064 * @since JDK1.0
- 065 */
- 066 public final class StringBuffer
- 067 extends AbstractStringBuilder
- 068 implements java.io.Serializable, CharSequence
- 069{
- 070
- 071 /** use serialVersionUID from JDK 1.0.2 for interoperability */
- 072 static final long serialVersionUID = 3388685877147921107L;
- 073
- 074 /**
- 075 * Constructs a string buffer with no characters in it and an
- 076 * initial capacity of 16 characters.
- 077 */
- 078 public StringBuffer() {
- 079 super(16);
- 080 }
- 081
- 082 /**
- 083 * Constructs a string buffer with no characters in it and
- 084 * the specified initial capacity.
- 085 *
- 086 * @param capacity the initial capacity.
- 087 * @exception NegativeArraySizeException if the <code>capacity</code>
- 088 * argument is less than <code>0</code>.
- 089 */
- 090 public StringBuffer(int capacity) {
- 091 super(capacity);
- 092 }
- 093
- 094 /**
- 095 * Constructs a string buffer initialized to the contents of the
- 096 * specified string. The initial capacity of the string buffer is
- 097 * <code>16</code> plus the length of the string argument.
- 098 *
- 099 * @param str the initial contents of the buffer.
- 100 * @exception NullPointerException if <code>str</code> is <code>null</code>
- 101 */
- 102 public StringBuffer(String str) {
- 103 super(str.length() + 16);
- 104 append(str);
- 105 }
- 106
- 107 /**
- 108 * Constructs a string buffer that contains the same characters
- 109 * as the specified <code>CharSequence</code>. The initial capacity of
- 110 * the string buffer is <code>16</code> plus the length of the
- 111 * <code>CharSequence</code> argument.
- 112 * <p>
- 113 * If the length of the specified <code>CharSequence</code> is
- 114 * less than or equal to zero, then an empty buffer of capacity
- 115 * <code>16</code> is returned.
- 116 *
- 117 * @param seq the sequence to copy.
- 118 * @exception NullPointerException if <code>seq</code> is <code>null</code>
- 119 * @since 1.5
- 120 */
- 121 public StringBuffer(CharSequence seq) {
- 122 this(seq.length() + 16);
- 123 append(seq);
- 124 }
- 125
- 126 public synchronized int length() {
- 127 return count;
- 128 }
- 129
- 130 public synchronized int capacity() {
- 131 return value.length;
- 132 }
- 133
- 134
- 135 public synchronized void ensureCapacity(int minimumCapacity) {
- 136 if (minimumCapacity > value.length) {
- 137 expandCapacity(minimumCapacity);
- 138 }
- 139 }
- 140
- 141 /**
- 142 * @since 1.5
- 143 */
- 144 public synchronized void trimToSize() {
- 145 super.trimToSize();
- 146 }
- 147
- 148 /**
- 149 * @throws IndexOutOfBoundsException {@inheritDoc}
- 150 * @see #length()
- 151 */
- 152 public synchronized void setLength(int newLength) {
- 153 super.setLength(newLength);
- 154 }
- 155
- 156 /**
- 157 * @throws IndexOutOfBoundsException {@inheritDoc}
- 158 * @see #length()
- 159 */
- 160 public synchronized char charAt(int index) {
- 161 if ((index < 0) || (index >= count))
- 162 throw new StringIndexOutOfBoundsException(index);
- 163 return value[index];
- 164 }
- 165
- 166 /**
- 167 * @since 1.5
- 168 */
- 169 public synchronized int codePointAt(int index) {
- 170 return super.codePointAt(index);
- 171 }
- 172
- 173 /**
- 174 * @since 1.5
- 175 */
- 176 public synchronized int codePointBefore(int index) {
- 177 return super.codePointBefore(index);
- 178 }
- 179
- 180 /**
- 181 * @since 1.5
- 182 */
- 183 public synchronized int codePointCount(int beginIndex, int endIndex) {
- 184 return super.codePointCount(beginIndex, endIndex);
- 185 }
- 186
- 187 /**
- 188 * @since 1.5
- 189 */
- 190 public synchronized int offsetByCodePoints(int index, int codePointOffset) {
- 191 return super.offsetByCodePoints(index, codePointOffset);
- 192 }
- 193
- 194 /**
- 195 * @throws NullPointerException {@inheritDoc}
- 196 * @throws IndexOutOfBoundsException {@inheritDoc}
- 197 */
- 198 public synchronized void getChars(int srcBegin, int srcEnd, char dst[],
- 199 int dstBegin)
- 200 {
- 201 super.getChars(srcBegin, srcEnd, dst, dstBegin);
- 202 }
- 203
- 204 /**
- 205 * @throws IndexOutOfBoundsException {@inheritDoc}
- 206 * @see #length()
- 207 */
- 208 public synchronized void setCharAt(int index, char ch) {
- 209 if ((index < 0) || (index >= count))
- 210 throw new StringIndexOutOfBoundsException(index);
- 211 value[index] = ch;
- 212 }
- 213
- 214 /**
- 215 * @see java.lang.String#valueOf(java.lang.Object)
- 216 * @see #append(java.lang.String)
- 217 */
- 218 public synchronized StringBuffer append(Object obj) {
- 219 super.append(String.valueOf(obj));
- 220 return this;
- 221 }
- 222
- 223 public synchronized StringBuffer append(String str) {
- 224 super.append(str);
- 225 return this;
- 226 }
- 227
- 228 /**
- 229 * Appends the specified <tt>StringBuffer</tt> to this sequence.
- 230 * <p>
- 231 * The characters of the <tt>StringBuffer</tt> argument are appended,
- 232 * in order, to the contents of this <tt>StringBuffer</tt>, increasing the
- 233 * length of this <tt>StringBuffer</tt> by the length of the argument.
- 234 * If <tt>sb</tt> is <tt>null</tt>, then the four characters
- 235 * <tt>"null"</tt> are appended to this <tt>StringBuffer</tt>.
- 236 * <p>
- 237 * Let <i>n</i> be the length of the old character sequence, the one
- 238 * contained in the <tt>StringBuffer</tt> just prior to execution of the
- 239 * <tt>append</tt> method. Then the character at index <i>k</i> in
- 240 * the new character sequence is equal to the character at index <i>k</i>
- 241 * in the old character sequence, if <i>k</i> is less than <i>n</i>;
- 242 * otherwise, it is equal to the character at index <i>k-n</i> in the
- 243 * argument <code>sb</code>.
- 244 * <p>
- 245 * This method synchronizes on <code>this</code> (the destination)
- 246 * object but does not synchronize on the source (<code>sb</code>).
- 247 *
- 248 * @param sb the <tt>StringBuffer</tt> to append.
- 249 * @return a reference to this object.
- 250 * @since 1.4
- 251 */
- 252 public synchronized StringBuffer append(StringBuffer sb) {
- 253 super.append(sb);
- 254 return this;
- 255 }
- 256
- 257
- 258 /**
- 259 * Appends the specified <code>CharSequence</code> to this
- 260 * sequence.
- 261 * <p>
- 262 * The characters of the <code>CharSequence</code> argument are appended,
- 263 * in order, increasing the length of this sequence by the length of the
- 264 * argument.
- 265 *
- 266 * <p>The result of this method is exactly the same as if it were an
- 267 * invocation of this.append(s, 0, s.length());
- 268 *
- 269 * <p>This method synchronizes on this (the destination)
- 270 * object but does not synchronize on the source (<code>s</code>).
- 271 *
- 272 * <p>If <code>s</code> is <code>null</code>, then the four characters
- 273 * <code>"null"</code> are appended.
- 274 *
- 275 * @param s the <code>CharSequence</code> to append.
- 276 * @return a reference to this object.
- 277 * @since 1.5
- 278 */
- 279 public StringBuffer append(CharSequence s) {
- 280 // Note, synchronization achieved via other invocations
- 281 if (s == null)
- 282 s = "null";
- 283 if (s instanceof String)
- 284 return this.append((String)s);
- 285 if (s instanceof StringBuffer)
- 286 return this.append((StringBuffer)s);
- 287 return this.append(s, 0, s.length());
- 288 }
- 289
- 290 /**
- 291 * @throws IndexOutOfBoundsException {@inheritDoc}
- 292 * @since 1.5
- 293 */
- 294 public synchronized StringBuffer append(CharSequence s, int start, int end)
- 295 {
- 296 super.append(s, start, end);
- 297 return this;
- 298 }
- 299
- 300 public synchronized StringBuffer append(char str[]) {
- 301 super.append(str);
- 302 return this;
- 303 }
- 304
- 305 public synchronized StringBuffer append(char str[], int offset, int len) {
- 306 super.append(str, offset, len);
- 307 return this;
- 308 }
- 309
- 310 /**
- 311 * @see java.lang.String#valueOf(boolean)
- 312 * @see #append(java.lang.String)
- 313 */
- 314 public synchronized StringBuffer append(boolean b) {
- 315 super.append(b);
- 316 return this;
- 317 }
- 318
- 319 public synchronized StringBuffer append(char c) {
- 320 super.append(c);
- 321 return this;
- 322 }
- 323
- 324 /**
- 325 * @see java.lang.String#valueOf(int)
- 326 * @see #append(java.lang.String)
- 327 */
- 328 public synchronized StringBuffer append(int i) {
- 329 super.append(i);
- 330 return this;
- 331 }
- 332
- 333 /**
- 334 * @since 1.5
- 335 */
- 336 public synchronized StringBuffer appendCodePoint(int codePoint) {
- 337 super.appendCodePoint(codePoint);
- 338 return this;
- 339 }
- 340
- 341 /**
- 342 * @see java.lang.String#valueOf(long)
- 343 * @see #append(java.lang.String)
- 344 */
- 345 public synchronized StringBuffer append(long lng) {
- 346 super.append(lng);
- 347 return this;
- 348 }
- 349
- 350 /**
- 351 * @see java.lang.String#valueOf(float)
- 352 * @see #append(java.lang.String)
- 353 */
- 354 public synchronized StringBuffer append(float f) {
- 355 super.append(f);
- 356 return this;
- 357 }
- 358
- 359 /**
- 360 * @see java.lang.String#valueOf(double)
- 361 * @see #append(java.lang.String)
- 362 */
- 363 public synchronized StringBuffer append(double d) {
- 364 super.append(d);
- 365 return this;
- 366 }
- 367
- 368 /**
- 369 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 370 * @since 1.2
- 371 */
- 372 public synchronized StringBuffer delete(int start, int end) {
- 373 super.delete(start, end);
- 374 return this;
- 375 }
- 376
- 377 /**
- 378 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 379 * @since 1.2
- 380 */
- 381 public synchronized StringBuffer deleteCharAt(int index) {
- 382 super.deleteCharAt(index);
- 383 return this;
- 384 }
- 385
- 386 /**
- 387 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 388 * @since 1.2
- 389 */
- 390 public synchronized StringBuffer replace(int start, int end, String str) {
- 391 super.replace(start, end, str);
- 392 return this;
- 393 }
- 394
- 395 /**
- 396 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 397 * @since 1.2
- 398 */
- 399 public synchronized String substring(int start) {
- 400 return substring(start, count);
- 401 }
- 402
- 403 /**
- 404 * @throws IndexOutOfBoundsException {@inheritDoc}
- 405 * @since 1.4
- 406 */
- 407 public synchronized CharSequence subSequence(int start, int end) {
- 408 return super.substring(start, end);
- 409 }
- 410
- 411 /**
- 412 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 413 * @since 1.2
- 414 */
- 415 public synchronized String substring(int start, int end) {
- 416 return super.substring(start, end);
- 417 }
- 418
- 419 /**
- 420 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 421 * @since 1.2
- 422 */
- 423 public synchronized StringBuffer insert(int index, char str[], int offset,
- 424 int len)
- 425 {
- 426 super.insert(index, str, offset, len);
- 427 return this;
- 428 }
- 429
- 430 /**
- 431 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 432 * @see java.lang.String#valueOf(java.lang.Object)
- 433 * @see #insert(int, java.lang.String)
- 434 * @see #length()
- 435 */
- 436 public synchronized StringBuffer insert(int offset, Object obj) {
- 437 super.insert(offset, String.valueOf(obj));
- 438 return this;
- 439 }
- 440
- 441 /**
- 442 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 443 * @see #length()
- 444 */
- 445 public synchronized StringBuffer insert(int offset, String str) {
- 446 super.insert(offset, str);
- 447 return this;
- 448 }
- 449
- 450 /**
- 451 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 452 */
- 453 public synchronized StringBuffer insert(int offset, char str[]) {
- 454 super.insert(offset, str);
- 455 return this;
- 456 }
- 457
- 458 /**
- 459 * @throws IndexOutOfBoundsException {@inheritDoc}
- 460 * @since 1.5
- 461 */
- 462 public StringBuffer insert(int dstOffset, CharSequence s) {
- 463 // Note, synchronization achieved via other invocations
- 464 if (s == null)
- 465 s = "null";
- 466 if (s instanceof String)
- 467 return this.insert(dstOffset, (String)s);
- 468 return this.insert(dstOffset, s, 0, s.length());
- 469 }
- 470
- 471 /**
- 472 * @throws IndexOutOfBoundsException {@inheritDoc}
- 473 * @since 1.5
- 474 */
- 475 public synchronized StringBuffer insert(int dstOffset, CharSequence s,
- 476 int start, int end)
- 477 {
- 478 super.insert(dstOffset, s, start, end);
- 479 return this;
- 480 }
- 481
- 482 /**
- 483 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 484 * @see java.lang.String#valueOf(boolean)
- 485 * @see #insert(int, java.lang.String)
- 486 * @see #length()
- 487 */
- 488 public StringBuffer insert(int offset, boolean b) {
- 489 return insert(offset, String.valueOf(b));
- 490 }
- 491
- 492 /**
- 493 * @throws IndexOutOfBoundsException {@inheritDoc}
- 494 * @see #length()
- 495 */
- 496 public synchronized StringBuffer insert(int offset, char c) {
- 497 super.insert(offset, c);
- 498 return this;
- 499 }
- 500
- 501 /**
- 502 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 503 * @see java.lang.String#valueOf(int)
- 504 * @see #insert(int, java.lang.String)
- 505 * @see #length()
- 506 */
- 507 public StringBuffer insert(int offset, int i) {
- 508 return insert(offset, String.valueOf(i));
- 509 }
- 510
- 511 /**
- 512 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 513 * @see java.lang.String#valueOf(long)
- 514 * @see #insert(int, java.lang.String)
- 515 * @see #length()
- 516 */
- 517 public StringBuffer insert(int offset, long l) {
- 518 return insert(offset, String.valueOf(l));
- 519 }
- 520
- 521 /**
- 522 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 523 * @see java.lang.String#valueOf(float)
- 524 * @see #insert(int, java.lang.String)
- 525 * @see #length()
- 526 */
- 527 public StringBuffer insert(int offset, float f) {
- 528 return insert(offset, String.valueOf(f));
- 529 }
- 530
- 531 /**
- 532 * @throws StringIndexOutOfBoundsException {@inheritDoc}
- 533 * @see java.lang.String#valueOf(double)
- 534 * @see #insert(int, java.lang.String)
- 535 * @see #length()
- 536 */
- 537 public StringBuffer insert(int offset, double d) {
- 538 return insert(offset, String.valueOf(d));
- 539 }
- 540
- 541 /**
- 542 * @throws NullPointerException {@inheritDoc}
- 543 * @since 1.4
- 544 */
- 545 public int indexOf(String str) {
- 546 return indexOf(str, 0);
- 547 }
- 548
- 549 /**
- 550 * @throws NullPointerException {@inheritDoc}
- 551 * @since 1.4
- 552 */
- 553 public synchronized int indexOf(String str, int fromIndex) {
- 554 return String.indexOf(value, 0, count,
- 555 str.toCharArray(), 0, str.length(), fromIndex);
- 556 }
- 557
- 558 /**
- 559 * @throws NullPointerException {@inheritDoc}
- 560 * @since 1.4
- 561 */
- 562 public int lastIndexOf(String str) {
- 563 // Note, synchronization achieved via other invocations
- 564 return lastIndexOf(str, count);
- 565 }
- 566
- 567 /**
- 568 * @throws NullPointerException {@inheritDoc}
- 569 * @since 1.4
- 570 */
- 571 public synchronized int lastIndexOf(String str, int fromIndex) {
- 572 return String.lastIndexOf(value, 0, count,
- 573 str.toCharArray(), 0, str.length(), fromIndex);
- 574 }
- 575
- 576 /**
- 577 * @since JDK1.0.2
- 578 */
- 579 public synchronized StringBuffer reverse() {
- 580 super.reverse();
- 581 return this;
- 582 }
- 583
- 584 public synchronized String toString() {
- 585 return new String(value, 0, count);
- 586 }
- 587
- 588 /**
- 589 * Serializable fields for StringBuffer.
- 590 *
- 591 * @serialField value char[]
- 592 * The backing character array of this StringBuffer.
- 593 * @serialField count int
- 594 * The number of characters in this StringBuffer.
- 595 * @serialField shared boolean
- 596 * A flag indicating whether the backing array is shared.
- 597 * The value is ignored upon deserialization.
- 598 */
- 599 private static final java.io.ObjectStreamField[] serialPersistentFields =
- 600 {
- 601 new java.io.ObjectStreamField("value", char[].class),
- 602 new java.io.ObjectStreamField("count", Integer.TYPE),
- 603 new java.io.ObjectStreamField("shared", Boolean.TYPE),
- 604 };
- 605
- 606 /**
- 607 * readObject is called to restore the state of the StringBuffer from
- 608 * a stream.
- 609 */
- 610 private synchronized void writeObject(java.io.ObjectOutputStream s)
- 611 throws java.io.IOException {
- 612 java.io.ObjectOutputStream.PutField fields = s.putFields();
- 613 fields.put("value", value);
- 614 fields.put("count", count);
- 615 fields.put("shared", false);
- 616 s.writeFields();
- 617 }
- 618
- 619 /**
- 620 * readObject is called to restore the state of the StringBuffer from
- 621 * a stream.
- 622 */
- 623 private void readObject(java.io.ObjectInputStream s)
- 624 throws java.io.IOException, ClassNotFoundException {
- 625 java.io.ObjectInputStream.GetField fields = s.readFields();
- 626 value = (char[])fields.get("value", null);
- 627 count = (int)fields.get("count", 0);
- 628 }
- 629}
