001 /* StringBuilder.java -- Unsynchronized 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>StringBuilder</code> represents a changeable <code>String</code>.
045 * It provides the operations required to modify the
046 * <code>StringBuilder</code>, including insert, replace, delete, append,
047 * and reverse. It like <code>StringBuffer</code>, but is not
048 * synchronized. It is ideal for use when it is known that the
049 * object will only be used from a single thread.
050 *
051 * <p><code>StringBuilder</code>s are variable-length in nature, so even if
052 * you initialize them to a certain size, they can still grow larger than
053 * that. <em>Capacity</em> indicates the number of characters the
054 * <code>StringBuilder</code> can have in it before it has to grow (growing
055 * the char array is an expensive operation involving <code>new</code>).
056 *
057 * <p>Incidentally, compilers often implement the String operator "+"
058 * by using a <code>StringBuilder</code> operation:<br>
059 * <code>a + b</code><br>
060 * is the same as<br>
061 * <code>new StringBuilder().append(a).append(b).toString()</code>.
062 *
063 * <p>Classpath's StringBuilder is capable of sharing memory with Strings for
064 * efficiency. This will help when a StringBuilder is converted to a String
065 * and the StringBuilder is not changed after that (quite common when
066 * performing string concatenation).
067 *
068 * @author Paul Fisher
069 * @author John Keiser
070 * @author Tom Tromey
071 * @author Eric Blake (ebb9@email.byu.edu)
072 * @see String
073 * @see StringBuffer
074 *
075 * @since 1.5
076 */
077 public final class StringBuilder
078 extends AbstractStringBuffer
079 implements Serializable, CharSequence, Appendable
080 {
081 // Implementation note: if you change this class, you usually will
082 // want to change StringBuffer as well.
083
084 /**
085 * For compatability with Sun's JDK
086 */
087 private static final long serialVersionUID = 4383685877147921099L;
088
089 /**
090 * Create a new StringBuilder with default capacity 16.
091 */
092 public StringBuilder()
093 {
094 super();
095 }
096
097 /**
098 * Create an empty <code>StringBuilder</code> with the specified initial
099 * capacity.
100 *
101 * @param capacity the initial capacity
102 * @throws NegativeArraySizeException if capacity is negative
103 */
104 public StringBuilder(int capacity)
105 {
106 super(capacity);
107 }
108
109 /**
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
112 * String plus 16.
113 *
114 * @param str the <code>String</code> to convert
115 * @throws NullPointerException if str is null
116 */
117 public StringBuilder(String str)
118 {
119 super(str);
120 }
121
122 /**
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.
127 *
128 * @param seq the initializing <code>CharSequence</code>
129 * @throws NullPointerException if str is null
130 */
131 public StringBuilder(CharSequence seq)
132 {
133 super(seq);
134 }
135
136 /**
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>.
140 *
141 * @return the length of this <code>StringBuilder</code>
142 * @see #capacity()
143 * @see #setLength(int)
144 */
145 public int length()
146 {
147 return count;
148 }
149
150 /**
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>.
153 *
154 * @return the capacity of this <code>StringBuilder</code>
155 * @see #length()
156 * @see #ensureCapacity(int)
157 */
158 public int capacity()
159 {
160 return value.length;
161 }
162
163 /**
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>.
167 *
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)
172 */
173 public StringBuilder append(Object obj)
174 {
175 super.append(obj);
176 return this;
177 }
178
179 /**
180 * Append the <code>String</code> to this <code>StringBuilder</code>. If
181 * str is null, the String "null" is appended.
182 *
183 * @param str the <code>String</code> to append
184 * @return this <code>StringBuilder</code>
185 */
186 public StringBuilder append(String str)
187 {
188 super.append(str);
189 return this;
190 }
191
192 /**
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.
196 *
197 * @param stringBuffer the <code>StringBuilder</code> to convert and append
198 * @return this <code>StringBuilder</code>
199 * @see #append(Object)
200 */
201 public StringBuilder append(StringBuffer stringBuffer)
202 {
203 super.append(stringBuffer);
204 return this;
205 }
206
207 /**
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.
211 *
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)
216 */
217 public StringBuilder append(char[] data)
218 {
219 super.append(data, 0, data.length);
220 return this;
221 }
222
223 /**
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
227 * of null.
228 *
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)
236 */
237 public StringBuilder append(char[] data, int offset, int count)
238 {
239 super.append(data, offset, count);
240 return this;
241 }
242
243 /**
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>.
247 *
248 * @param bool the <code>boolean</code> to convert and append
249 * @return this <code>StringBuilder</code>
250 * @see String#valueOf(boolean)
251 */
252 public StringBuilder append(boolean bool)
253 {
254 super.append(bool);
255 return this;
256 }
257
258 /**
259 * Append the <code>char</code> to this <code>StringBuilder</code>.
260 *
261 * @param ch the <code>char</code> to append
262 * @return this <code>StringBuilder</code>
263 */
264 public StringBuilder append(char ch)
265 {
266 super.append(ch);
267 return this;
268 }
269
270 /**
271 * Append the characters in the <code>CharSequence</code> to this
272 * buffer.
273 *
274 * @param seq the <code>CharSequence</code> providing the characters
275 * @return this <code>StringBuilder</code>
276 */
277 public StringBuilder append(CharSequence seq)
278 {
279 super.append(seq, 0, seq.length());
280 return this;
281 }
282
283 /**
284 * Append some characters from the <code>CharSequence</code> to this
285 * buffer. If the argument is null, the four characters "null" are
286 * appended.
287 *
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>
292 */
293 public StringBuilder append(CharSequence seq, int start,
294 int end)
295 {
296 super.append(seq, start, end);
297 return this;
298 }
299
300 /**
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>.
304 *
305 * @param inum the <code>int</code> to convert and append
306 * @return this <code>StringBuilder</code>
307 * @see String#valueOf(int)
308 */
309 // This is native in libgcj, for efficiency.
310 public StringBuilder append(int inum)
311 {
312 super.append(inum);
313 return this;
314 }
315
316 /**
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>.
320 *
321 * @param lnum the <code>long</code> to convert and append
322 * @return this <code>StringBuilder</code>
323 * @see String#valueOf(long)
324 */
325 public StringBuilder append(long lnum)
326 {
327 super.append(lnum);
328 return this;
329 }
330
331 /**
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>.
335 *
336 * @param fnum the <code>float</code> to convert and append
337 * @return this <code>StringBuilder</code>
338 * @see String#valueOf(float)
339 */
340 public StringBuilder append(float fnum)
341 {
342 super.append(fnum);
343 return this;
344 }
345
346 /**
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>.
350 *
351 * @param dnum the <code>double</code> to convert and append
352 * @return this <code>StringBuilder</code>
353 * @see String#valueOf(double)
354 */
355 public StringBuilder append(double dnum)
356 {
357 super.append(dnum);
358 return this;
359 }
360
361 /**
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.
365 *
366 * @param code the code point to append
367 * @return this <code>StringBuilder</code>
368 * @see Character#toChars(int, char[], int)
369 * @since 1.5
370 */
371 public StringBuilder appendCodePoint(int code)
372 {
373 super.appendCodePoint(code);
374 return this;
375 }
376
377 /**
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().
381 *
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
386 */
387 public StringBuilder delete(int start, int end)
388 {
389 super.delete(start, end);
390 return this;
391 }
392
393 /**
394 * Delete a character from this <code>StringBuilder</code>.
395 *
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
399 */
400 public StringBuilder deleteCharAt(int index)
401 {
402 super.deleteCharAt(index);
403 return this;
404 }
405
406 /**
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.
411 *
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
418 */
419 public StringBuilder replace(int start, int end, String str)
420 {
421 super.replace(start, end, str);
422 return this;
423 }
424
425 /**
426 * Creates a substring of this StringBuilder, starting at a specified index
427 * and ending at the end of this StringBuilder.
428 *
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)
433 */
434 public String substring(int beginIndex)
435 {
436 return substring(beginIndex, count);
437 }
438
439 /**
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.
444 *
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
449 * bounds
450 * @see #substring(int, int)
451 */
452 public CharSequence subSequence(int beginIndex, int endIndex)
453 {
454 return substring(beginIndex, endIndex);
455 }
456
457 /**
458 * Creates a substring of this StringBuilder, starting at a specified index
459 * and ending at one character before a specified index.
460 *
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
465 * of bounds
466 */
467 public String substring(int beginIndex, int endIndex)
468 {
469 int len = endIndex - beginIndex;
470 if (beginIndex < 0 || endIndex > count || endIndex < beginIndex)
471 throw new StringIndexOutOfBoundsException();
472 if (len == 0)
473 return "";
474 return new String(value, beginIndex, len);
475 }
476
477 /**
478 * Insert a subarray of the <code>char[]</code> argument into this
479 * <code>StringBuilder</code>.
480 *
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
488 */
489 public StringBuilder insert(int offset,
490 char[] str, int str_offset, int len)
491 {
492 super.insert(offset, str, str_offset, len);
493 return this;
494 }
495
496 /**
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>.
500 *
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)
506 */
507 public StringBuilder insert(int offset, Object obj)
508 {
509 super.insert(offset, obj);
510 return this;
511 }
512
513 /**
514 * Insert the <code>String</code> argument into this
515 * <code>StringBuilder</code>. If str is null, the String "null" is used
516 * instead.
517 *
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
522 */
523 public StringBuilder insert(int offset, String str)
524 {
525 super.insert(offset, str);
526 return this;
527 }
528
529 /**
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.
533 *
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
538 */
539 public StringBuilder insert(int offset, CharSequence sequence)
540 {
541 super.insert(offset, sequence);
542 return this;
543 }
544
545 /**
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.
549 *
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
557 */
558 public StringBuilder insert(int offset, CharSequence sequence,
559 int start, int end)
560 {
561 super.insert(offset, sequence, start, end);
562 return this;
563 }
564
565 /**
566 * Insert the <code>char[]</code> argument into this
567 * <code>StringBuilder</code>.
568 *
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)
575 */
576 public StringBuilder insert(int offset, char[] data)
577 {
578 super.insert(offset, data);
579 return this;
580 }
581
582 /**
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>.
586 *
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)
592 */
593 public StringBuilder insert(int offset, boolean bool)
594 {
595 super.insert(offset, bool);
596 return this;
597 }
598
599 /**
600 * Insert the <code>char</code> argument into this <code>StringBuilder</code>.
601 *
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
606 */
607 public StringBuilder insert(int offset, char ch)
608 {
609 super.insert(offset, ch);
610 return this;
611 }
612
613 /**
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>.
617 *
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)
623 */
624 public StringBuilder insert(int offset, int inum)
625 {
626 super.insert(offset, inum);
627 return this;
628 }
629
630 /**
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>.
634 *
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)
640 */
641 public StringBuilder insert(int offset, long lnum)
642 {
643 super.insert(offset, lnum);
644 return this;
645 }
646
647 /**
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>.
651 *
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)
657 */
658 public StringBuilder insert(int offset, float fnum)
659 {
660 super.insert(offset, fnum);
661 return this;
662 }
663
664 /**
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>.
668 *
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)
674 */
675 public StringBuilder insert(int offset, double dnum)
676 {
677 super.insert(offset, dnum);
678 return this;
679 }
680
681 /**
682 * Reverse the characters in this StringBuilder. The same sequence of
683 * characters exists, but in the reverse index ordering.
684 *
685 * @return this <code>StringBuilder</code>
686 */
687 public StringBuilder reverse()
688 {
689 super.reverse();
690 return this;
691 }
692
693 /**
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.
698 *
699 * @return the characters in this StringBuilder
700 */
701 public String toString()
702 {
703 return new String(this);
704 }
705
706 }