001 /* StringBuffer.java -- Growable strings
002 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2008
003 Free Software Foundation, Inc.
004
005 This file is part of GNU Classpath.
006
007 GNU Classpath is free software; you can redistribute it and/or modify
008 it under the terms of the GNU General Public License as published by
009 the Free Software Foundation; either version 2, or (at your option)
010 any later version.
011
012 GNU Classpath is distributed in the hope that it will be useful, but
013 WITHOUT ANY WARRANTY; without even the implied warranty of
014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 General Public License for more details.
016
017 You should have received a copy of the GNU General Public License
018 along with GNU Classpath; see the file COPYING. If not, write to the
019 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
020 02110-1301 USA.
021
022 Linking this library statically or dynamically with other modules is
023 making a combined work based on this library. Thus, the terms and
024 conditions of the GNU General Public License cover the whole
025 combination.
026
027 As a special exception, the copyright holders of this library give you
028 permission to link this library with independent modules to produce an
029 executable, regardless of the license terms of these independent
030 modules, and to copy and distribute the resulting executable under
031 terms of your choice, provided that you also meet, for each linked
032 independent module, the terms and conditions of the license of that
033 module. An independent module is a module which is not derived from
034 or based on this library. If you modify this library, you may extend
035 this exception to your version of the library, but you are not
036 obligated to do so. If you do not wish to do so, delete this
037 exception statement from your version. */
038
039 package java.lang;
040
041 import java.io.Serializable;
042
043 /**
044 * <code>StringBuffer</code> represents a changeable <code>String</code>.
045 * It provides the operations required to modify the
046 * <code>StringBuffer</code>, including insert, replace, delete, append,
047 * and reverse. It is thread-safe; meaning that all modifications to a buffer
048 * are in synchronized methods.
049 *
050 * <p><code>StringBuffer</code>s are variable-length in nature, so even if
051 * you initialize them to a certain size, they can still grow larger than
052 * that. <em>Capacity</em> indicates the number of characters the
053 * <code>StringBuffer</code> can have in it before it has to grow (growing
054 * the char array is an expensive operation involving <code>new</code>).
055 *
056 * <p>Incidentally, compilers often implement the String operator "+"
057 * by using a <code>StringBuffer</code> operation:<br>
058 * <code>a + b</code><br>
059 * is the same as<br>
060 * <code>new StringBuffer().append(a).append(b).toString()</code>.
061 *
062 * <p>Classpath's StringBuffer is capable of sharing memory with Strings for
063 * efficiency. This will help when a StringBuffer is converted to a String
064 * and the StringBuffer is not changed after that (quite common when performing
065 * string concatenation).
066 *
067 * @author Paul Fisher
068 * @author John Keiser
069 * @author Tom Tromey
070 * @author Eric Blake (ebb9@email.byu.edu)
071 * @see String
072 * @since 1.0
073 * @status updated to 1.4
074 */
075 public final class StringBuffer
076 extends AbstractStringBuffer
077 implements Serializable, CharSequence, Appendable
078 {
079 // Implementation note: if you change this class, you usually will
080 // want to change StringBuilder as well.
081
082 /**
083 * Compatible with JDK 1.0+.
084 */
085 private static final long serialVersionUID = 3388685877147921107L;
086
087 /**
088 * True if the buffer is shared with another object (StringBuffer or
089 * String); this means the buffer must be copied before writing to it again.
090 * Note that this has permissions set this way so that String can get the
091 * value.
092 *
093 * @serial whether the buffer is shared
094 */
095 boolean shared;
096
097 /**
098 * Create a new StringBuffer with default capacity 16.
099 */
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 }