1 /* StringBuilder.java -- Unsynchronized growable strings
2 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2008
3 Free Software Foundation, Inc.
5 This file is part of GNU Classpath.
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)
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.
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
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
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. */
41 import java
.io
.Serializable
;
44 * <code>StringBuilder</code> represents a changeable <code>String</code>.
45 * It provides the operations required to modify the
46 * <code>StringBuilder</code>, including insert, replace, delete, append,
47 * and reverse. It like <code>StringBuffer</code>, but is not
48 * synchronized. It is ideal for use when it is known that the
49 * object will only be used from a single thread.
51 * <p><code>StringBuilder</code>s are variable-length in nature, so even if
52 * you initialize them to a certain size, they can still grow larger than
53 * that. <em>Capacity</em> indicates the number of characters the
54 * <code>StringBuilder</code> can have in it before it has to grow (growing
55 * the char array is an expensive operation involving <code>new</code>).
57 * <p>Incidentally, compilers often implement the String operator "+"
58 * by using a <code>StringBuilder</code> operation:<br>
59 * <code>a + b</code><br>
61 * <code>new StringBuilder().append(a).append(b).toString()</code>.
63 * <p>Classpath's StringBuilder is capable of sharing memory with Strings for
64 * efficiency. This will help when a StringBuilder is converted to a String
65 * and the StringBuilder is not changed after that (quite common when
66 * performing string concatenation).
71 * @author Eric Blake (ebb9@email.byu.edu)
77 public final class StringBuilder
78 extends AbstractStringBuffer
79 implements Serializable
, CharSequence
, Appendable
81 // Implementation note: if you change this class, you usually will
82 // want to change StringBuffer as well.
85 * For compatability with Sun's JDK
87 private static final long serialVersionUID
= 4383685877147921099L;
90 * Create a new StringBuilder with default capacity 16.
92 public StringBuilder()
98 * Create an empty <code>StringBuilder</code> with the specified initial
101 * @param capacity the initial capacity
102 * @throws NegativeArraySizeException if capacity is negative
104 public StringBuilder(int capacity
)
110 * Create a new <code>StringBuilder</code> with the characters in the
111 * specified <code>String</code>. Initial capacity will be the size of the
114 * @param str the <code>String</code> to convert
115 * @throws NullPointerException if str is null
117 public StringBuilder(String str
)
123 * Create a new <code>StringBuilder</code> with the characters in the
124 * specified <code>CharSequence</code>. Initial capacity will be the
125 * length of the sequence plus 16; if the sequence reports a length
126 * less than or equal to 0, then the initial capacity will be 16.
128 * @param seq the initializing <code>CharSequence</code>
129 * @throws NullPointerException if str is null
131 public StringBuilder(CharSequence seq
)
137 * Get the length of the <code>String</code> this <code>StringBuilder</code>
138 * would create. Not to be confused with the <em>capacity</em> of the
139 * <code>StringBuilder</code>.
141 * @return the length of this <code>StringBuilder</code>
143 * @see #setLength(int)
151 * Get the total number of characters this <code>StringBuilder</code> can
152 * support before it must be grown. Not to be confused with <em>length</em>.
154 * @return the capacity of this <code>StringBuilder</code>
156 * @see #ensureCapacity(int)
158 public int capacity()
164 * Append the <code>String</code> value of the argument to this
165 * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
166 * to <code>String</code>.
168 * @param obj the <code>Object</code> to convert and append
169 * @return this <code>StringBuilder</code>
170 * @see String#valueOf(Object)
171 * @see #append(String)
173 public StringBuilder
append(Object obj
)
180 * Append the <code>String</code> to this <code>StringBuilder</code>. If
181 * str is null, the String "null" is appended.
183 * @param str the <code>String</code> to append
184 * @return this <code>StringBuilder</code>
186 public StringBuilder
append(String str
)
193 * Append the <code>StringBuilder</code> value of the argument to this
194 * <code>StringBuilder</code>. This behaves the same as
195 * <code>append((Object) stringBuffer)</code>, except it is more efficient.
197 * @param stringBuffer the <code>StringBuilder</code> to convert and append
198 * @return this <code>StringBuilder</code>
199 * @see #append(Object)
201 public StringBuilder
append(StringBuffer stringBuffer
)
203 super.append(stringBuffer
);
208 * Append the <code>char</code> array to this <code>StringBuilder</code>.
209 * This is similar (but more efficient) than
210 * <code>append(new String(data))</code>, except in the case of null.
212 * @param data the <code>char[]</code> to append
213 * @return this <code>StringBuilder</code>
214 * @throws NullPointerException if <code>str</code> is <code>null</code>
215 * @see #append(char[], int, int)
217 public StringBuilder
append(char[] data
)
219 super.append(data
, 0, data
.length
);
224 * Append part of the <code>char</code> array to this
225 * <code>StringBuilder</code>. This is similar (but more efficient) than
226 * <code>append(new String(data, offset, count))</code>, except in the case
229 * @param data the <code>char[]</code> to append
230 * @param offset the start location in <code>str</code>
231 * @param count the number of characters to get from <code>str</code>
232 * @return this <code>StringBuilder</code>
233 * @throws NullPointerException if <code>str</code> is <code>null</code>
234 * @throws IndexOutOfBoundsException if offset or count is out of range
235 * (while unspecified, this is a StringIndexOutOfBoundsException)
237 public StringBuilder
append(char[] data
, int offset
, int count
)
239 super.append(data
, offset
, count
);
244 * Append the <code>String</code> value of the argument to this
245 * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
246 * to <code>String</code>.
248 * @param bool the <code>boolean</code> to convert and append
249 * @return this <code>StringBuilder</code>
250 * @see String#valueOf(boolean)
252 public StringBuilder
append(boolean bool
)
259 * Append the <code>char</code> to this <code>StringBuilder</code>.
261 * @param ch the <code>char</code> to append
262 * @return this <code>StringBuilder</code>
264 public StringBuilder
append(char ch
)
271 * Append the characters in the <code>CharSequence</code> to this
274 * @param seq the <code>CharSequence</code> providing the characters
275 * @return this <code>StringBuilder</code>
277 public StringBuilder
append(CharSequence seq
)
279 super.append(seq
, 0, seq
.length());
284 * Append some characters from the <code>CharSequence</code> to this
285 * buffer. If the argument is null, the four characters "null" are
288 * @param seq the <code>CharSequence</code> providing the characters
289 * @param start the starting index
290 * @param end one past the final index
291 * @return this <code>StringBuilder</code>
293 public StringBuilder
append(CharSequence seq
, int start
,
296 super.append(seq
, start
, end
);
301 * Append the <code>String</code> value of the argument to this
302 * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
303 * to <code>String</code>.
305 * @param inum the <code>int</code> to convert and append
306 * @return this <code>StringBuilder</code>
307 * @see String#valueOf(int)
309 // This is native in libgcj, for efficiency.
310 public StringBuilder
append(int inum
)
317 * Append the <code>String</code> value of the argument to this
318 * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
319 * to <code>String</code>.
321 * @param lnum the <code>long</code> to convert and append
322 * @return this <code>StringBuilder</code>
323 * @see String#valueOf(long)
325 public StringBuilder
append(long lnum
)
332 * Append the <code>String</code> value of the argument to this
333 * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
334 * to <code>String</code>.
336 * @param fnum the <code>float</code> to convert and append
337 * @return this <code>StringBuilder</code>
338 * @see String#valueOf(float)
340 public StringBuilder
append(float fnum
)
347 * Append the <code>String</code> value of the argument to this
348 * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
349 * to <code>String</code>.
351 * @param dnum the <code>double</code> to convert and append
352 * @return this <code>StringBuilder</code>
353 * @see String#valueOf(double)
355 public StringBuilder
append(double dnum
)
362 * Append the code point to this <code>StringBuilder</code>.
363 * This is like #append(char), but will append two characters
364 * if a supplementary code point is given.
366 * @param code the code point to append
367 * @return this <code>StringBuilder</code>
368 * @see Character#toChars(int, char[], int)
371 public StringBuilder
appendCodePoint(int code
)
373 super.appendCodePoint(code
);
378 * Delete characters from this <code>StringBuilder</code>.
379 * <code>delete(10, 12)</code> will delete 10 and 11, but not 12. It is
380 * harmless for end to be larger than length().
382 * @param start the first character to delete
383 * @param end the index after the last character to delete
384 * @return this <code>StringBuilder</code>
385 * @throws StringIndexOutOfBoundsException if start or end are out of bounds
387 public StringBuilder
delete(int start
, int end
)
389 super.delete(start
, end
);
394 * Delete a character from this <code>StringBuilder</code>.
396 * @param index the index of the character to delete
397 * @return this <code>StringBuilder</code>
398 * @throws StringIndexOutOfBoundsException if index is out of bounds
400 public StringBuilder
deleteCharAt(int index
)
402 super.deleteCharAt(index
);
407 * Replace characters between index <code>start</code> (inclusive) and
408 * <code>end</code> (exclusive) with <code>str</code>. If <code>end</code>
409 * is larger than the size of this StringBuilder, all characters after
410 * <code>start</code> are replaced.
412 * @param start the beginning index of characters to delete (inclusive)
413 * @param end the ending index of characters to delete (exclusive)
414 * @param str the new <code>String</code> to insert
415 * @return this <code>StringBuilder</code>
416 * @throws StringIndexOutOfBoundsException if start or end are out of bounds
417 * @throws NullPointerException if str is null
419 public StringBuilder
replace(int start
, int end
, String str
)
421 super.replace(start
, end
, str
);
426 * Creates a substring of this StringBuilder, starting at a specified index
427 * and ending at the end of this StringBuilder.
429 * @param beginIndex index to start substring (base 0)
430 * @return new String which is a substring of this StringBuilder
431 * @throws StringIndexOutOfBoundsException if beginIndex is out of bounds
432 * @see #substring(int, int)
434 public String
substring(int beginIndex
)
436 return substring(beginIndex
, count
);
440 * Creates a substring of this StringBuilder, starting at a specified index
441 * and ending at one character before a specified index. This is implemented
442 * the same as <code>substring(beginIndex, endIndex)</code>, to satisfy
443 * the CharSequence interface.
445 * @param beginIndex index to start at (inclusive, base 0)
446 * @param endIndex index to end at (exclusive)
447 * @return new String which is a substring of this StringBuilder
448 * @throws IndexOutOfBoundsException if beginIndex or endIndex is out of
450 * @see #substring(int, int)
452 public CharSequence
subSequence(int beginIndex
, int endIndex
)
454 return substring(beginIndex
, endIndex
);
458 * Creates a substring of this StringBuilder, starting at a specified index
459 * and ending at one character before a specified index.
461 * @param beginIndex index to start at (inclusive, base 0)
462 * @param endIndex index to end at (exclusive)
463 * @return new String which is a substring of this StringBuilder
464 * @throws StringIndexOutOfBoundsException if beginIndex or endIndex is out
467 public String
substring(int beginIndex
, int endIndex
)
469 int len
= endIndex
- beginIndex
;
470 if (beginIndex
< 0 || endIndex
> count
|| endIndex
< beginIndex
)
471 throw new StringIndexOutOfBoundsException();
474 return new String(value
, beginIndex
, len
);
478 * Insert a subarray of the <code>char[]</code> argument into this
479 * <code>StringBuilder</code>.
481 * @param offset the place to insert in this buffer
482 * @param str the <code>char[]</code> to insert
483 * @param str_offset the index in <code>str</code> to start inserting from
484 * @param len the number of characters to insert
485 * @return this <code>StringBuilder</code>
486 * @throws NullPointerException if <code>str</code> is <code>null</code>
487 * @throws StringIndexOutOfBoundsException if any index is out of bounds
489 public StringBuilder
insert(int offset
,
490 char[] str
, int str_offset
, int len
)
492 super.insert(offset
, str
, str_offset
, len
);
497 * Insert the <code>String</code> value of the argument into this
498 * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
499 * to <code>String</code>.
501 * @param offset the place to insert in this buffer
502 * @param obj the <code>Object</code> to convert and insert
503 * @return this <code>StringBuilder</code>
504 * @exception StringIndexOutOfBoundsException if offset is out of bounds
505 * @see String#valueOf(Object)
507 public StringBuilder
insert(int offset
, Object obj
)
509 super.insert(offset
, obj
);
514 * Insert the <code>String</code> argument into this
515 * <code>StringBuilder</code>. If str is null, the String "null" is used
518 * @param offset the place to insert in this buffer
519 * @param str the <code>String</code> to insert
520 * @return this <code>StringBuilder</code>
521 * @throws StringIndexOutOfBoundsException if offset is out of bounds
523 public StringBuilder
insert(int offset
, String str
)
525 super.insert(offset
, str
);
530 * Insert the <code>CharSequence</code> argument into this
531 * <code>StringBuilder</code>. If the sequence is null, the String
532 * "null" is used instead.
534 * @param offset the place to insert in this buffer
535 * @param sequence the <code>CharSequence</code> to insert
536 * @return this <code>StringBuilder</code>
537 * @throws IndexOutOfBoundsException if offset is out of bounds
539 public StringBuilder
insert(int offset
, CharSequence sequence
)
541 super.insert(offset
, sequence
);
546 * Insert a subsequence of the <code>CharSequence</code> argument into this
547 * <code>StringBuilder</code>. If the sequence is null, the String
548 * "null" is used instead.
550 * @param offset the place to insert in this buffer
551 * @param sequence the <code>CharSequence</code> to insert
552 * @param start the starting index of the subsequence
553 * @param end one past the ending index of the subsequence
554 * @return this <code>StringBuilder</code>
555 * @throws IndexOutOfBoundsException if offset, start,
556 * or end are out of bounds
558 public StringBuilder
insert(int offset
, CharSequence sequence
,
561 super.insert(offset
, sequence
, start
, end
);
566 * Insert the <code>char[]</code> argument into this
567 * <code>StringBuilder</code>.
569 * @param offset the place to insert in this buffer
570 * @param data the <code>char[]</code> to insert
571 * @return this <code>StringBuilder</code>
572 * @throws NullPointerException if <code>data</code> is <code>null</code>
573 * @throws StringIndexOutOfBoundsException if offset is out of bounds
574 * @see #insert(int, char[], int, int)
576 public StringBuilder
insert(int offset
, char[] data
)
578 super.insert(offset
, data
);
583 * Insert the <code>String</code> value of the argument into this
584 * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
585 * to <code>String</code>.
587 * @param offset the place to insert in this buffer
588 * @param bool the <code>boolean</code> to convert and insert
589 * @return this <code>StringBuilder</code>
590 * @throws StringIndexOutOfBoundsException if offset is out of bounds
591 * @see String#valueOf(boolean)
593 public StringBuilder
insert(int offset
, boolean bool
)
595 super.insert(offset
, bool
);
600 * Insert the <code>char</code> argument into this <code>StringBuilder</code>.
602 * @param offset the place to insert in this buffer
603 * @param ch the <code>char</code> to insert
604 * @return this <code>StringBuilder</code>
605 * @throws StringIndexOutOfBoundsException if offset is out of bounds
607 public StringBuilder
insert(int offset
, char ch
)
609 super.insert(offset
, ch
);
614 * Insert the <code>String</code> value of the argument into this
615 * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
616 * to <code>String</code>.
618 * @param offset the place to insert in this buffer
619 * @param inum the <code>int</code> to convert and insert
620 * @return this <code>StringBuilder</code>
621 * @throws StringIndexOutOfBoundsException if offset is out of bounds
622 * @see String#valueOf(int)
624 public StringBuilder
insert(int offset
, int inum
)
626 super.insert(offset
, inum
);
631 * Insert the <code>String</code> value of the argument into this
632 * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
633 * to <code>String</code>.
635 * @param offset the place to insert in this buffer
636 * @param lnum the <code>long</code> to convert and insert
637 * @return this <code>StringBuilder</code>
638 * @throws StringIndexOutOfBoundsException if offset is out of bounds
639 * @see String#valueOf(long)
641 public StringBuilder
insert(int offset
, long lnum
)
643 super.insert(offset
, lnum
);
648 * Insert the <code>String</code> value of the argument into this
649 * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
650 * to <code>String</code>.
652 * @param offset the place to insert in this buffer
653 * @param fnum the <code>float</code> to convert and insert
654 * @return this <code>StringBuilder</code>
655 * @throws StringIndexOutOfBoundsException if offset is out of bounds
656 * @see String#valueOf(float)
658 public StringBuilder
insert(int offset
, float fnum
)
660 super.insert(offset
, fnum
);
665 * Insert the <code>String</code> value of the argument into this
666 * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
667 * to <code>String</code>.
669 * @param offset the place to insert in this buffer
670 * @param dnum the <code>double</code> to convert and insert
671 * @return this <code>StringBuilder</code>
672 * @throws StringIndexOutOfBoundsException if offset is out of bounds
673 * @see String#valueOf(double)
675 public StringBuilder
insert(int offset
, double dnum
)
677 super.insert(offset
, dnum
);
682 * Reverse the characters in this StringBuilder. The same sequence of
683 * characters exists, but in the reverse index ordering.
685 * @return this <code>StringBuilder</code>
687 public StringBuilder
reverse()
694 * Convert this <code>StringBuilder</code> to a <code>String</code>. The
695 * String is composed of the characters currently in this StringBuilder. Note
696 * that the result is a copy, and that future modifications to this buffer
697 * do not affect the String.
699 * @return the characters in this StringBuilder
701 public String
toString()
703 return new String(this);