001/* StringBuilder.java -- Unsynchronized growable strings
002   Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2008
003   Free Software Foundation, Inc.
004
005This file is part of GNU Classpath.
006
007GNU Classpath is free software; you can redistribute it and/or modify
008it under the terms of the GNU General Public License as published by
009the Free Software Foundation; either version 2, or (at your option)
010any later version.
011
012GNU Classpath is distributed in the hope that it will be useful, but
013WITHOUT ANY WARRANTY; without even the implied warranty of
014MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015General Public License for more details.
016
017You should have received a copy of the GNU General Public License
018along with GNU Classpath; see the file COPYING.  If not, write to the
019Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02002110-1301 USA.
021
022Linking this library statically or dynamically with other modules is
023making a combined work based on this library.  Thus, the terms and
024conditions of the GNU General Public License cover the whole
025combination.
026
027As a special exception, the copyright holders of this library give you
028permission to link this library with independent modules to produce an
029executable, regardless of the license terms of these independent
030modules, and to copy and distribute the resulting executable under
031terms of your choice, provided that you also meet, for each linked
032independent module, the terms and conditions of the license of that
033module.  An independent module is a module which is not derived from
034or based on this library.  If you modify this library, you may extend
035this exception to your version of the library, but you are not
036obligated to do so.  If you do not wish to do so, delete this
037exception statement from your version. */
038
039package java.lang;
040
041import 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 */
077public 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}