| Frames | No Frames |
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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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. 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: }