1 /* StringBuffer.java -- Growable strings 2 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2008 3 Free Software Foundation, Inc. 4 5 This file is part of GNU Classpath. 6 7 GNU Classpath is free software; you can redistribute it and/or modify 8 it under the terms of the GNU General Public License as published by 9 the Free Software Foundation; either version 2, or (at your option) 10 any later version. 11 12 GNU Classpath is distributed in the hope that it will be useful, but 13 WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 General Public License for more details. 16 17 You should have received a copy of the GNU General Public License 18 along with GNU Classpath; see the file COPYING. If not, write to the 19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 20 02110-1301 USA. 21 22 Linking this library statically or dynamically with other modules is 23 making a combined work based on this library. Thus, the terms and 24 conditions of the GNU General Public License cover the whole 25 combination. 26 27 As a special exception, the copyright holders of this library give you 28 permission to link this library with independent modules to produce an 29 executable, regardless of the license terms of these independent 30 modules, and to copy and distribute the resulting executable under 31 terms of your choice, provided that you also meet, for each linked 32 independent module, the terms and conditions of the license of that 33 module. An independent module is a module which is not derived from 34 or based on this library. If you modify this library, you may extend 35 this exception to your version of the library, but you are not 36 obligated to do so. If you do not wish to do so, delete this 37 exception statement from your version. */ 38 39 package java.lang; 40 41 import java.io.Serializable; 42 43 /** 44 * <code>StringBuffer</code> represents a changeable <code>String</code>. 45 * It provides the operations required to modify the 46 * <code>StringBuffer</code>, including insert, replace, delete, append, 47 * and reverse. It is thread-safe; meaning that all modifications to a buffer 48 * are in synchronized methods. 49 * 50 * <p><code>StringBuffer</code>s are variable-length in nature, so even if 51 * you initialize them to a certain size, they can still grow larger than 52 * that. <em>Capacity</em> indicates the number of characters the 53 * <code>StringBuffer</code> can have in it before it has to grow (growing 54 * the char array is an expensive operation involving <code>new</code>). 55 * 56 * <p>Incidentally, compilers often implement the String operator "+" 57 * by using a <code>StringBuffer</code> operation:<br> 58 * <code>a + b</code><br> 59 * is the same as<br> 60 * <code>new StringBuffer().append(a).append(b).toString()</code>. 61 * 62 * <p>Classpath's StringBuffer is capable of sharing memory with Strings for 63 * efficiency. This will help when a StringBuffer is converted to a String 64 * and the StringBuffer is not changed after that (quite common when performing 65 * string concatenation). 66 * 67 * @author Paul Fisher 68 * @author John Keiser 69 * @author Tom Tromey 70 * @author Eric Blake (ebb9@email.byu.edu) 71 * @see String 72 * @since 1.0 73 * @status updated to 1.4 74 */ 75 public final class StringBuffer 76 extends AbstractStringBuffer 77 implements Serializable, CharSequence, Appendable 78 { 79 // Implementation note: if you change this class, you usually will 80 // want to change StringBuilder as well. 81 82 /** 83 * Compatible with JDK 1.0+. 84 */ 85 private static final long serialVersionUID = 3388685877147921107L; 86 87 /** 88 * True if the buffer is shared with another object (StringBuffer or 89 * String); this means the buffer must be copied before writing to it again. 90 * Note that this has permissions set this way so that String can get the 91 * value. 92 * 93 * @serial whether the buffer is shared 94 */ 95 boolean shared; 96 97 /** 98 * Create a new StringBuffer with default capacity 16. 99 */ StringBuffer()100 public StringBuffer() 101 { 102 super(); 103 } 104 105 /** 106 * Create an empty <code>StringBuffer</code> with the specified initial 107 * capacity. 108 * 109 * @param capacity the initial capacity 110 * @throws NegativeArraySizeException if capacity is negative 111 */ StringBuffer(int capacity)112 public StringBuffer(int capacity) 113 { 114 super(capacity); 115 } 116 117 /** 118 * Create a new <code>StringBuffer</code> with the characters in the 119 * specified <code>String</code>. Initial capacity will be the size of the 120 * String plus 16. 121 * 122 * @param str the <code>String</code> to convert 123 * @throws NullPointerException if str is null 124 */ StringBuffer(String str)125 public StringBuffer(String str) 126 { 127 // Unfortunately, because the size is 16 larger, we cannot share. 128 super(str); 129 } 130 131 /** 132 * Create a new <code>StringBuffer</code> with the characters in the 133 * specified <code>CharSequence</code>. Initial capacity will be the 134 * length of the sequence plus 16; if the sequence reports a length 135 * less than or equal to 0, then the initial capacity will be 16. 136 * 137 * @param seq the initializing <code>CharSequence</code> 138 * @throws NullPointerException if str is null 139 * @since 1.5 140 */ StringBuffer(CharSequence seq)141 public StringBuffer(CharSequence seq) 142 { 143 super(seq); 144 } 145 146 /** 147 * Get the length of the <code>String</code> this <code>StringBuffer</code> 148 * would create. Not to be confused with the <em>capacity</em> of the 149 * <code>StringBuffer</code>. 150 * 151 * @return the length of this <code>StringBuffer</code> 152 * @see #capacity() 153 * @see #setLength(int) 154 */ length()155 public synchronized int length() 156 { 157 return count; 158 } 159 160 /** 161 * Get the total number of characters this <code>StringBuffer</code> can 162 * support before it must be grown. Not to be confused with <em>length</em>. 163 * 164 * @return the capacity of this <code>StringBuffer</code> 165 * @see #length() 166 * @see #ensureCapacity(int) 167 */ capacity()168 public synchronized int capacity() 169 { 170 return value.length; 171 } 172 173 /** 174 * Increase the capacity of this <code>StringBuffer</code>. This will 175 * ensure that an expensive growing operation will not occur until 176 * <code>minimumCapacity</code> is reached. The buffer is grown to the 177 * larger of <code>minimumCapacity</code> and 178 * <code>capacity() * 2 + 2</code>, if it is not already large enough. 179 * 180 * @param minimumCapacity the new capacity 181 * @see #capacity() 182 */ ensureCapacity(int minimumCapacity)183 public synchronized void ensureCapacity(int minimumCapacity) 184 { 185 ensureCapacity_unsynchronized(minimumCapacity); 186 } 187 188 /** 189 * Set the length of this StringBuffer. If the new length is greater than 190 * the current length, all the new characters are set to '\0'. If the new 191 * length is less than the current length, the first <code>newLength</code> 192 * characters of the old array will be preserved, and the remaining 193 * characters are truncated. 194 * 195 * @param newLength the new length 196 * @throws IndexOutOfBoundsException if the new length is negative 197 * (while unspecified, this is a StringIndexOutOfBoundsException) 198 * @see #length() 199 */ setLength(int newLength)200 public synchronized void setLength(int newLength) 201 { 202 super.setLength(newLength); 203 } 204 205 /** 206 * Get the character at the specified index. 207 * 208 * @param index the index of the character to get, starting at 0 209 * @return the character at the specified index 210 * @throws IndexOutOfBoundsException if index is negative or >= length() 211 * (while unspecified, this is a StringIndexOutOfBoundsException) 212 */ charAt(int index)213 public synchronized char charAt(int index) 214 { 215 return super.charAt(index); 216 } 217 218 /** 219 * Get the code point at the specified index. This is like #charAt(int), 220 * but if the character is the start of a surrogate pair, and the 221 * following character completes the pair, then the corresponding 222 * supplementary code point is returned. 223 * @param index the index of the codepoint to get, starting at 0 224 * @return the codepoint at the specified index 225 * @throws IndexOutOfBoundsException if index is negative or >= length() 226 * @since 1.5 227 */ codePointAt(int index)228 public synchronized int codePointAt(int index) 229 { 230 return super.codePointAt(index); 231 } 232 233 /** 234 * Get the code point before the specified index. This is like 235 * #codePointAt(int), but checks the characters at <code>index-1</code> and 236 * <code>index-2</code> to see if they form a supplementary code point. 237 * @param index the index just past the codepoint to get, starting at 0 238 * @return the codepoint at the specified index 239 * @throws IndexOutOfBoundsException if index is negative or >= length() 240 * @since 1.5 241 */ codePointBefore(int index)242 public synchronized int codePointBefore(int index) 243 { 244 return super.codePointBefore(index); 245 } 246 247 /** 248 * Get the specified array of characters. <code>srcOffset - srcEnd</code> 249 * characters will be copied into the array you pass in. 250 * 251 * @param srcOffset the index to start copying from (inclusive) 252 * @param srcEnd the index to stop copying from (exclusive) 253 * @param dst the array to copy into 254 * @param dstOffset the index to start copying into 255 * @throws NullPointerException if dst is null 256 * @throws IndexOutOfBoundsException if any source or target indices are 257 * out of range (while unspecified, source problems cause a 258 * StringIndexOutOfBoundsException, and dest problems cause an 259 * ArrayIndexOutOfBoundsException) 260 * @see System#arraycopy(Object, int, Object, int, int) 261 */ getChars(int srcOffset, int srcEnd, char[] dst, int dstOffset)262 public synchronized void getChars(int srcOffset, int srcEnd, 263 char[] dst, int dstOffset) 264 { 265 super.getChars(srcOffset, srcEnd, dst, dstOffset); 266 } 267 268 /** 269 * Set the character at the specified index. 270 * 271 * @param index the index of the character to set starting at 0 272 * @param ch the value to set that character to 273 * @throws IndexOutOfBoundsException if index is negative or >= length() 274 * (while unspecified, this is a StringIndexOutOfBoundsException) 275 */ setCharAt(int index, char ch)276 public synchronized void setCharAt(int index, char ch) 277 { 278 super.setCharAt(index, ch); 279 } 280 281 /** 282 * Append the <code>String</code> value of the argument to this 283 * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert 284 * to <code>String</code>. 285 * 286 * @param obj the <code>Object</code> to convert and append 287 * @return this <code>StringBuffer</code> 288 * @see String#valueOf(Object) 289 * @see #append(String) 290 */ append(Object obj)291 public synchronized StringBuffer append(Object obj) 292 { 293 super.append(obj); 294 return this; 295 } 296 297 /** 298 * Append the <code>String</code> to this <code>StringBuffer</code>. If 299 * str is null, the String "null" is appended. 300 * 301 * @param str the <code>String</code> to append 302 * @return this <code>StringBuffer</code> 303 */ append(String str)304 public synchronized StringBuffer append(String str) 305 { 306 super.append(str); 307 return this; 308 } 309 310 /** 311 * Append the <code>StringBuffer</code> value of the argument to this 312 * <code>StringBuffer</code>. This behaves the same as 313 * <code>append((Object) stringBuffer)</code>, except it is more efficient. 314 * 315 * @param stringBuffer the <code>StringBuffer</code> to convert and append 316 * @return this <code>StringBuffer</code> 317 * @see #append(Object) 318 * @since 1.4 319 */ append(StringBuffer stringBuffer)320 public synchronized StringBuffer append(StringBuffer stringBuffer) 321 { 322 super.append(stringBuffer); 323 return this; 324 } 325 326 /** 327 * Append the <code>char</code> array to this <code>StringBuffer</code>. 328 * This is similar (but more efficient) than 329 * <code>append(new String(data))</code>, except in the case of null. 330 * 331 * @param data the <code>char[]</code> to append 332 * @return this <code>StringBuffer</code> 333 * @throws NullPointerException if <code>str</code> is <code>null</code> 334 * @see #append(char[], int, int) 335 */ append(char[] data)336 public synchronized StringBuffer append(char[] data) 337 { 338 super.append(data, 0, data.length); 339 return this; 340 } 341 342 /** 343 * Append part of the <code>char</code> array to this 344 * <code>StringBuffer</code>. This is similar (but more efficient) than 345 * <code>append(new String(data, offset, count))</code>, except in the case 346 * of null. 347 * 348 * @param data the <code>char[]</code> to append 349 * @param offset the start location in <code>str</code> 350 * @param count the number of characters to get from <code>str</code> 351 * @return this <code>StringBuffer</code> 352 * @throws NullPointerException if <code>str</code> is <code>null</code> 353 * @throws IndexOutOfBoundsException if offset or count is out of range 354 * (while unspecified, this is a StringIndexOutOfBoundsException) 355 */ append(char[] data, int offset, int count)356 public synchronized StringBuffer append(char[] data, int offset, int count) 357 { 358 super.append(data, offset, count); 359 return this; 360 } 361 362 /** 363 * Append the <code>String</code> value of the argument to this 364 * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert 365 * to <code>String</code>. 366 * 367 * @param bool the <code>boolean</code> to convert and append 368 * @return this <code>StringBuffer</code> 369 * @see String#valueOf(boolean) 370 */ append(boolean bool)371 public synchronized StringBuffer append(boolean bool) 372 { 373 super.append(bool); 374 return this; 375 } 376 377 /** 378 * Append the <code>char</code> to this <code>StringBuffer</code>. 379 * 380 * @param ch the <code>char</code> to append 381 * @return this <code>StringBuffer</code> 382 */ append(char ch)383 public synchronized StringBuffer append(char ch) 384 { 385 super.append(ch); 386 return this; 387 } 388 389 /** 390 * Append the characters in the <code>CharSequence</code> to this 391 * buffer. 392 * 393 * @param seq the <code>CharSequence</code> providing the characters 394 * @return this <code>StringBuffer</code> 395 * @since 1.5 396 */ append(CharSequence seq)397 public synchronized StringBuffer append(CharSequence seq) 398 { 399 super.append(seq, 0, seq.length()); 400 return this; 401 } 402 403 /** 404 * Append some characters from the <code>CharSequence</code> to this 405 * buffer. If the argument is null, the four characters "null" are 406 * appended. 407 * 408 * @param seq the <code>CharSequence</code> providing the characters 409 * @param start the starting index 410 * @param end one past the final index 411 * @return this <code>StringBuffer</code> 412 * @since 1.5 413 */ append(CharSequence seq, int start, int end)414 public synchronized StringBuffer append(CharSequence seq, int start, int end) 415 { 416 super.append(seq, start, end); 417 return this; 418 } 419 420 /** 421 * Append the <code>String</code> value of the argument to this 422 * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert 423 * to <code>String</code>. 424 * 425 * @param inum the <code>int</code> to convert and append 426 * @return this <code>StringBuffer</code> 427 * @see String#valueOf(int) 428 */ 429 // This is native in libgcj, for efficiency. append(int inum)430 public synchronized StringBuffer append(int inum) 431 { 432 super.append(inum); 433 return this; 434 } 435 436 /** 437 * Append the <code>String</code> value of the argument to this 438 * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert 439 * to <code>String</code>. 440 * 441 * @param lnum the <code>long</code> to convert and append 442 * @return this <code>StringBuffer</code> 443 * @see String#valueOf(long) 444 */ append(long lnum)445 public synchronized StringBuffer append(long lnum) 446 { 447 super.append(lnum); 448 return this; 449 } 450 451 /** 452 * Append the <code>String</code> value of the argument to this 453 * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert 454 * to <code>String</code>. 455 * 456 * @param fnum the <code>float</code> to convert and append 457 * @return this <code>StringBuffer</code> 458 * @see String#valueOf(float) 459 */ append(float fnum)460 public synchronized StringBuffer append(float fnum) 461 { 462 super.append(fnum); 463 return this; 464 } 465 466 /** 467 * Append the <code>String</code> value of the argument to this 468 * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert 469 * to <code>String</code>. 470 * 471 * @param dnum the <code>double</code> to convert and append 472 * @return this <code>StringBuffer</code> 473 * @see String#valueOf(double) 474 */ append(double dnum)475 public synchronized StringBuffer append(double dnum) 476 { 477 super.append(dnum); 478 return this; 479 } 480 481 /** 482 * Append the code point to this <code>StringBuffer</code>. 483 * This is like #append(char), but will append two characters 484 * if a supplementary code point is given. 485 * 486 * @param code the code point to append 487 * @return this <code>StringBuffer</code> 488 * @see Character#toChars(int, char[], int) 489 * @since 1.5 490 */ appendCodePoint(int code)491 public synchronized StringBuffer appendCodePoint(int code) 492 { 493 super.appendCodePoint(code); 494 return this; 495 } 496 497 /** 498 * Delete characters from this <code>StringBuffer</code>. 499 * <code>delete(10, 12)</code> will delete 10 and 11, but not 12. It is 500 * harmless for end to be larger than length(). 501 * 502 * @param start the first character to delete 503 * @param end the index after the last character to delete 504 * @return this <code>StringBuffer</code> 505 * @throws StringIndexOutOfBoundsException if start or end are out of bounds 506 * @since 1.2 507 */ delete(int start, int end)508 public synchronized StringBuffer delete(int start, int end) 509 { 510 // This will unshare if required. 511 super.delete(start, end); 512 return this; 513 } 514 515 /** 516 * Delete a character from this <code>StringBuffer</code>. 517 * 518 * @param index the index of the character to delete 519 * @return this <code>StringBuffer</code> 520 * @throws StringIndexOutOfBoundsException if index is out of bounds 521 * @since 1.2 522 */ deleteCharAt(int index)523 public synchronized StringBuffer deleteCharAt(int index) 524 { 525 super.deleteCharAt(index); 526 return this; 527 } 528 529 /** 530 * Replace characters between index <code>start</code> (inclusive) and 531 * <code>end</code> (exclusive) with <code>str</code>. If <code>end</code> 532 * is larger than the size of this StringBuffer, all characters after 533 * <code>start</code> are replaced. 534 * 535 * @param start the beginning index of characters to delete (inclusive) 536 * @param end the ending index of characters to delete (exclusive) 537 * @param str the new <code>String</code> to insert 538 * @return this <code>StringBuffer</code> 539 * @throws StringIndexOutOfBoundsException if start or end are out of bounds 540 * @throws NullPointerException if str is null 541 * @since 1.2 542 */ replace(int start, int end, String str)543 public synchronized StringBuffer replace(int start, int end, String str) 544 { 545 super.replace(start, end, str); 546 return this; 547 } 548 549 /** 550 * Creates a substring of this StringBuffer, starting at a specified index 551 * and ending at the end of this StringBuffer. 552 * 553 * @param beginIndex index to start substring (base 0) 554 * @return new String which is a substring of this StringBuffer 555 * @throws StringIndexOutOfBoundsException if beginIndex is out of bounds 556 * @see #substring(int, int) 557 * @since 1.2 558 */ substring(int beginIndex)559 public String substring(int beginIndex) 560 { 561 return substring(beginIndex, count); 562 } 563 564 /** 565 * Creates a substring of this StringBuffer, starting at a specified index 566 * and ending at one character before a specified index. This is implemented 567 * the same as <code>substring(beginIndex, endIndex)</code>, to satisfy 568 * the CharSequence interface. 569 * 570 * @param beginIndex index to start at (inclusive, base 0) 571 * @param endIndex index to end at (exclusive) 572 * @return new String which is a substring of this StringBuffer 573 * @throws IndexOutOfBoundsException if beginIndex or endIndex is out of 574 * bounds 575 * @see #substring(int, int) 576 * @since 1.4 577 */ subSequence(int beginIndex, int endIndex)578 public CharSequence subSequence(int beginIndex, int endIndex) 579 { 580 return substring(beginIndex, endIndex); 581 } 582 583 /** 584 * Creates a substring of this StringBuffer, starting at a specified index 585 * and ending at one character before a specified index. 586 * 587 * @param beginIndex index to start at (inclusive, base 0) 588 * @param endIndex index to end at (exclusive) 589 * @return new String which is a substring of this StringBuffer 590 * @throws StringIndexOutOfBoundsException if beginIndex or endIndex is out 591 * of bounds 592 * @since 1.2 593 */ substring(int beginIndex, int endIndex)594 public synchronized String substring(int beginIndex, int endIndex) 595 { 596 int len = endIndex - beginIndex; 597 if (beginIndex < 0 || endIndex > count || endIndex < beginIndex) 598 throw new StringIndexOutOfBoundsException(); 599 if (len == 0) 600 return ""; 601 // Don't copy unless substring is smaller than 1/4 of the buffer. 602 boolean share_buffer = ((len << 2) >= value.length); 603 if (share_buffer) 604 this.shared = true; 605 // Package constructor avoids an array copy. 606 return new String(value, beginIndex, len, share_buffer); 607 } 608 609 /** 610 * Insert a subarray of the <code>char[]</code> argument into this 611 * <code>StringBuffer</code>. 612 * 613 * @param offset the place to insert in this buffer 614 * @param str the <code>char[]</code> to insert 615 * @param str_offset the index in <code>str</code> to start inserting from 616 * @param len the number of characters to insert 617 * @return this <code>StringBuffer</code> 618 * @throws NullPointerException if <code>str</code> is <code>null</code> 619 * @throws StringIndexOutOfBoundsException if any index is out of bounds 620 * @since 1.2 621 */ insert(int offset, char[] str, int str_offset, int len)622 public synchronized StringBuffer insert(int offset, 623 char[] str, int str_offset, int len) 624 { 625 super.insert(offset, str, str_offset, len); 626 return this; 627 } 628 629 /** 630 * Insert the <code>String</code> value of the argument into this 631 * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert 632 * to <code>String</code>. 633 * 634 * @param offset the place to insert in this buffer 635 * @param obj the <code>Object</code> to convert and insert 636 * @return this <code>StringBuffer</code> 637 * @exception StringIndexOutOfBoundsException if offset is out of bounds 638 * @see String#valueOf(Object) 639 */ insert(int offset, Object obj)640 public synchronized StringBuffer insert(int offset, Object obj) 641 { 642 super.insert(offset, obj); 643 return this; 644 } 645 646 /** 647 * Insert the <code>String</code> argument into this 648 * <code>StringBuffer</code>. If str is null, the String "null" is used 649 * instead. 650 * 651 * @param offset the place to insert in this buffer 652 * @param str the <code>String</code> to insert 653 * @return this <code>StringBuffer</code> 654 * @throws StringIndexOutOfBoundsException if offset is out of bounds 655 */ insert(int offset, String str)656 public synchronized StringBuffer insert(int offset, String str) 657 { 658 super.insert(offset, str); 659 return this; 660 } 661 662 /** 663 * Insert the <code>CharSequence</code> argument into this 664 * <code>StringBuffer</code>. If the sequence is null, the String 665 * "null" is used instead. 666 * 667 * @param offset the place to insert in this buffer 668 * @param sequence the <code>CharSequence</code> to insert 669 * @return this <code>StringBuffer</code> 670 * @throws IndexOutOfBoundsException if offset is out of bounds 671 * @since 1.5 672 */ insert(int offset, CharSequence sequence)673 public synchronized StringBuffer insert(int offset, CharSequence sequence) 674 { 675 super.insert(offset, sequence); 676 return this; 677 } 678 679 /** 680 * Insert a subsequence of the <code>CharSequence</code> argument into this 681 * <code>StringBuffer</code>. If the sequence is null, the String 682 * "null" is used instead. 683 * 684 * @param offset the place to insert in this buffer 685 * @param sequence the <code>CharSequence</code> to insert 686 * @param start the starting index of the subsequence 687 * @param end one past the ending index of the subsequence 688 * @return this <code>StringBuffer</code> 689 * @throws IndexOutOfBoundsException if offset, start, 690 * or end are out of bounds 691 * @since 1.5 692 */ insert(int offset, CharSequence sequence, int start, int end)693 public synchronized StringBuffer insert(int offset, CharSequence sequence, 694 int start, int end) 695 { 696 super.insert(offset, sequence, start, end); 697 return this; 698 } 699 700 /** 701 * Insert the <code>char[]</code> argument into this 702 * <code>StringBuffer</code>. 703 * 704 * @param offset the place to insert in this buffer 705 * @param data the <code>char[]</code> to insert 706 * @return this <code>StringBuffer</code> 707 * @throws NullPointerException if <code>data</code> is <code>null</code> 708 * @throws StringIndexOutOfBoundsException if offset is out of bounds 709 * @see #insert(int, char[], int, int) 710 */ insert(int offset, char[] data)711 public synchronized StringBuffer insert(int offset, char[] data) 712 { 713 super.insert(offset, data, 0, data.length); 714 return this; 715 } 716 717 /** 718 * Insert the <code>String</code> value of the argument into this 719 * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert 720 * to <code>String</code>. 721 * 722 * @param offset the place to insert in this buffer 723 * @param bool the <code>boolean</code> to convert and insert 724 * @return this <code>StringBuffer</code> 725 * @throws StringIndexOutOfBoundsException if offset is out of bounds 726 * @see String#valueOf(boolean) 727 */ insert(int offset, boolean bool)728 public synchronized StringBuffer insert(int offset, boolean bool) 729 { 730 super.insert(offset, bool); 731 return this; 732 } 733 734 /** 735 * Insert the <code>char</code> argument into this <code>StringBuffer</code>. 736 * 737 * @param offset the place to insert in this buffer 738 * @param ch the <code>char</code> to insert 739 * @return this <code>StringBuffer</code> 740 * @throws StringIndexOutOfBoundsException if offset is out of bounds 741 */ insert(int offset, char ch)742 public synchronized StringBuffer insert(int offset, char ch) 743 { 744 super.insert(offset, ch); 745 return this; 746 } 747 748 /** 749 * Insert the <code>String</code> value of the argument into this 750 * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert 751 * to <code>String</code>. 752 * 753 * @param offset the place to insert in this buffer 754 * @param inum the <code>int</code> to convert and insert 755 * @return this <code>StringBuffer</code> 756 * @throws StringIndexOutOfBoundsException if offset is out of bounds 757 * @see String#valueOf(int) 758 */ insert(int offset, int inum)759 public synchronized StringBuffer insert(int offset, int inum) 760 { 761 super.insert(offset, inum); 762 return this; 763 } 764 765 /** 766 * Insert the <code>String</code> value of the argument into this 767 * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert 768 * to <code>String</code>. 769 * 770 * @param offset the place to insert in this buffer 771 * @param lnum the <code>long</code> to convert and insert 772 * @return this <code>StringBuffer</code> 773 * @throws StringIndexOutOfBoundsException if offset is out of bounds 774 * @see String#valueOf(long) 775 */ insert(int offset, long lnum)776 public synchronized StringBuffer insert(int offset, long lnum) 777 { 778 super.insert(offset, lnum); 779 return this; 780 } 781 782 /** 783 * Insert the <code>String</code> value of the argument into this 784 * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert 785 * to <code>String</code>. 786 * 787 * @param offset the place to insert in this buffer 788 * @param fnum the <code>float</code> to convert and insert 789 * @return this <code>StringBuffer</code> 790 * @throws StringIndexOutOfBoundsException if offset is out of bounds 791 * @see String#valueOf(float) 792 */ insert(int offset, float fnum)793 public synchronized StringBuffer insert(int offset, float fnum) 794 { 795 super.insert(offset, fnum); 796 return this; 797 } 798 799 /** 800 * Insert the <code>String</code> value of the argument into this 801 * <code>StringBuffer</code>. Uses <code>String.valueOf()</code> to convert 802 * to <code>String</code>. 803 * 804 * @param offset the place to insert in this buffer 805 * @param dnum the <code>double</code> to convert and insert 806 * @return this <code>StringBuffer</code> 807 * @throws StringIndexOutOfBoundsException if offset is out of bounds 808 * @see String#valueOf(double) 809 */ insert(int offset, double dnum)810 public synchronized StringBuffer insert(int offset, double dnum) 811 { 812 super.insert(offset, dnum); 813 return this; 814 } 815 816 /** 817 * Finds the first instance of a substring in this StringBuffer. 818 * 819 * @param str String to find 820 * @return location (base 0) of the String, or -1 if not found 821 * @throws NullPointerException if str is null 822 * @see #indexOf(String, int) 823 * @since 1.4 824 */ indexOf(String str)825 public synchronized int indexOf(String str) 826 { 827 return super.indexOf(str, 0); 828 } 829 830 /** 831 * Finds the first instance of a String in this StringBuffer, starting at 832 * a given index. If starting index is less than 0, the search starts at 833 * the beginning of this String. If the starting index is greater than the 834 * length of this String, or the substring is not found, -1 is returned. 835 * 836 * @param str String to find 837 * @param fromIndex index to start the search 838 * @return location (base 0) of the String, or -1 if not found 839 * @throws NullPointerException if str is null 840 * @since 1.4 841 */ indexOf(String str, int fromIndex)842 public synchronized int indexOf(String str, int fromIndex) 843 { 844 return super.indexOf(str, fromIndex); 845 } 846 847 /** 848 * Finds the last instance of a substring in this StringBuffer. 849 * 850 * @param str String to find 851 * @return location (base 0) of the String, or -1 if not found 852 * @throws NullPointerException if str is null 853 * @see #lastIndexOf(String, int) 854 * @since 1.4 855 */ lastIndexOf(String str)856 public synchronized int lastIndexOf(String str) 857 { 858 return super.lastIndexOf(str, count - str.count); 859 } 860 861 /** 862 * Finds the last instance of a String in this StringBuffer, starting at a 863 * given index. If starting index is greater than the maximum valid index, 864 * then the search begins at the end of this String. If the starting index 865 * is less than zero, or the substring is not found, -1 is returned. 866 * 867 * @param str String to find 868 * @param fromIndex index to start the search 869 * @return location (base 0) of the String, or -1 if not found 870 * @throws NullPointerException if str is null 871 * @since 1.4 872 */ lastIndexOf(String str, int fromIndex)873 public synchronized int lastIndexOf(String str, int fromIndex) 874 { 875 return super.lastIndexOf(str, fromIndex); 876 } 877 878 /** 879 * Reverse the characters in this StringBuffer. The same sequence of 880 * characters exists, but in the reverse index ordering. 881 * 882 * @return this <code>StringBuffer</code> 883 */ reverse()884 public synchronized StringBuffer reverse() 885 { 886 super.reverse(); 887 return this; 888 } 889 890 /** 891 * Convert this <code>StringBuffer</code> to a <code>String</code>. The 892 * String is composed of the characters currently in this StringBuffer. Note 893 * that the result is a copy, and that future modifications to this buffer 894 * do not affect the String. 895 * 896 * @return the characters in this StringBuffer 897 */ toString()898 public String toString() 899 { 900 // The string will set this.shared = true. 901 return new String(this); 902 } 903 904 /** 905 * This may reduce the amount of memory used by the StringBuffer, 906 * by resizing the internal array to remove unused space. However, 907 * this method is not required to resize, so this behavior cannot 908 * be relied upon. 909 * @since 1.5 910 */ trimToSize()911 public synchronized void trimToSize() 912 { 913 super.trimToSize(); 914 } 915 916 /** 917 * Return the number of code points between two indices in the 918 * <code>StringBuffer</code>. An unpaired surrogate counts as a 919 * code point for this purpose. Characters outside the indicated 920 * range are not examined, even if the range ends in the middle of a 921 * surrogate pair. 922 * 923 * @param start the starting index 924 * @param end one past the ending index 925 * @return the number of code points 926 * @since 1.5 927 */ codePointCount(int start, int end)928 public synchronized int codePointCount(int start, int end) 929 { 930 return super.codePointCount(start, end); 931 } 932 933 /** 934 * Starting at the given index, this counts forward by the indicated 935 * number of code points, and then returns the resulting index. An 936 * unpaired surrogate counts as a single code point for this 937 * purpose. 938 * 939 * @param start the starting index 940 * @param codePoints the number of code points 941 * @return the resulting index 942 * @since 1.5 943 */ offsetByCodePoints(int start, int codePoints)944 public synchronized int offsetByCodePoints(int start, int codePoints) 945 { 946 return super.offsetByCodePoints(start, codePoints); 947 } 948 949 /** 950 * An unsynchronized version of ensureCapacity, used internally to avoid 951 * the cost of a second lock on the same object. This also has the side 952 * effect of duplicating the array, if it was shared (to form copy-on-write 953 * semantics). 954 * 955 * @param minimumCapacity the minimum capacity 956 * @see #ensureCapacity(int) 957 */ ensureCapacity_unsynchronized(int minimumCapacity)958 void ensureCapacity_unsynchronized(int minimumCapacity) 959 { 960 if (shared || minimumCapacity > value.length) 961 { 962 // We don't want to make a larger vector when `shared' is 963 // set. If we do, then setLength becomes very inefficient 964 // when repeatedly reusing a StringBuffer in a loop. 965 int max = (minimumCapacity > value.length 966 ? value.length * 2 + 2 967 : value.length); 968 minimumCapacity = (minimumCapacity < max ? max : minimumCapacity); 969 char[] nb = new char[minimumCapacity]; 970 System.arraycopy(value, 0, nb, 0, count); 971 value = nb; 972 shared = false; 973 } 974 } 975 976 } 977