Robust/src/ClassLibrary/MGC/gnu/StringBuilder.java

   1 /* StringBuilder.java -- Unsynchronized growable strings
   2    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2008
   3    Free Software Foundation, Inc.
   4
   5 This file is part of GNU Classpath.
   6
   7 GNU Classpath is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2, or (at your option)
  10 any later version.
  11
  12 GNU Classpath is distributed in the hope that it will be useful, but
  13 WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GNU Classpath; see the file COPYING.  If not, write to the
  19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20 02110-1301 USA.
  21
  22 Linking this library statically or dynamically with other modules is
  23 making a combined work based on this library.  Thus, the terms and
  24 conditions of the GNU General Public License cover the whole
  25 combination.
  26
  27 As a special exception, the copyright holders of this library give you
  28 permission to link this library with independent modules to produce an
  29 executable, regardless of the license terms of these independent
  30 modules, and to copy and distribute the resulting executable under
  31 terms of your choice, provided that you also meet, for each linked
  32 independent module, the terms and conditions of the license of that
  33 module.  An independent module is a module which is not derived from
  34 or based on this library.  If you modify this library, you may extend
  35 this exception to your version of the library, but you are not
  36 obligated to do so.  If you do not wish to do so, delete this
  37 exception statement from your version. */
  38
  39 package java.lang;
  40
  41
  42 /**
  43  * <code>StringBuilder</code> represents a changeable <code>String</code>.
  44  * It provides the operations required to modify the
  45  * <code>StringBuilder</code>, including insert, replace, delete, append,
  46  * and reverse. It like <code>StringBuffer</code>, but is not
  47  * synchronized.  It is ideal for use when it is known that the
  48  * object will only be used from a single thread.
  49  *
  50  * <p><code>StringBuilder</code>s are variable-length in nature, so even if
  51  * you initialize them to a certain size, they can still grow larger than
  52  * that. <em>Capacity</em> indicates the number of characters the
  53  * <code>StringBuilder</code> can have in it before it has to grow (growing
  54  * the char array is an expensive operation involving <code>new</code>).
  55  *
  56  * <p>Incidentally, compilers often implement the String operator "+"
  57  * by using a <code>StringBuilder</code> operation:<br>
  58  * <code>a + b</code><br>
  59  * is the same as<br>
  60  * <code>new StringBuilder().append(a).append(b).toString()</code>.
  61  *
  62  * <p>Classpath's StringBuilder is capable of sharing memory with Strings for
  63  * efficiency.  This will help when a StringBuilder is converted to a String
  64  * and the StringBuilder is not changed after that (quite common when
  65  * performing string concatenation).
  66  *
  67  * @author Paul Fisher
  68  * @author John Keiser
  69  * @author Tom Tromey
  70  * @author Eric Blake (ebb9@email.byu.edu)
  71  * @see String
  72  * @see StringBuffer
  73  *
  74  * @since 1.5
  75  */
  76 public final class StringBuilder
  77 {
  78   // Implementation note: if you change this class, you usually will
  79   // want to change StringBuffer as well.
  80   int count;
  81
  82   /**
  83    * The buffer.  Note that this has permissions set this way so that String
  84    * can get the value.
  85    *
  86    * @serial the buffer
  87    */
  88   char[] value;
  89
  90   /**
  91    * The default capacity of a buffer.
  92    */
  93   private static final int DEFAULT_CAPACITY = 16;
  94
  95   /**
  96    * For compatability with Sun's JDK
  97    */
  98   private static final long serialVersionUID = 4383685877147921099L;
  99
 100   /**
 101    * Create a new StringBuilder with default capacity 16.
 102    */
 103   public StringBuilder()
 104   {
 105     value = new char[this.DEFAULT_CAPACITY];
 106     this.count = 0;
 107   }
 108
 109   /**
 110    * Create an empty <code>StringBuilder</code> with the specified initial
 111    * capacity.
 112    *
 113    * @param capacity the initial capacity
 114    * @throws NegativeArraySizeException if capacity is negative
 115    */
 116   public StringBuilder(int capacity)
 117   {
 118     value = new char[capacity];
 119     this.count = 0;
 120   }
 121
 122   /**
 123    * Create a new <code>StringBuilder</code> with the characters in the
 124    * specified <code>String</code>. Initial capacity will be the size of the
 125    * String plus 16.
 126    *
 127    * @param str the <code>String</code> to convert
 128    * @throws NullPointerException if str is null
 129    */
 130   public StringBuilder(String str)
 131   {
 132     count = str.count;
 133     value = new char[count + DEFAULT_CAPACITY];
 134     str.getChars(0, count, value, 0);
 135   }
 136
 137   /**
 138    * Get the length of the <code>String</code> this <code>StringBuilder</code>
 139    * would create. Not to be confused with the <em>capacity</em> of the
 140    * <code>StringBuilder</code>.
 141    *
 142    * @return the length of this <code>StringBuilder</code>
 143    * @see #capacity()
 144    * @see #setLength(int)
 145    */
 146   public int length()
 147   {
 148     return count;
 149   }
 150
 151   /**
 152    * Get the total number of characters this <code>StringBuilder</code> can
 153    * support before it must be grown.  Not to be confused with <em>length</em>.
 154    *
 155    * @return the capacity of this <code>StringBuilder</code>
 156    * @see #length()
 157    * @see #ensureCapacity(int)
 158    */
 159   public int capacity()
 160   {
 161     return value.length;
 162   }
 163
 164   void ensureCapacity_unsynchronized(int minimumCapacity)
 165   {
 166     if (minimumCapacity > value.length)
 167       {
 168         int max = value.length * 2 + 2;
 169         minimumCapacity = (minimumCapacity < max ? max : minimumCapacity);
 170         char[] nb = new char[minimumCapacity];
 171         System.arraycopy(value, 0, nb, 0, count);
 172         value = nb;
 173       }
 174   }
 175
 176   /**
 177    * Append the <code>String</code> value of the argument to this
 178    * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
 179    * to <code>String</code>.
 180    *
 181    * @param obj the <code>Object</code> to convert and append
 182    * @return this <code>StringBuilder</code>
 183    * @see String#valueOf(Object)
 184    * @see #append(String)
 185    */
 186   public StringBuilder append(Object obj)
 187   {
 188     append(String.valueOf(obj));
 189     return this;
 190   }
 191
 192   /**
 193    * Append the <code>String</code> to this <code>StringBuilder</code>. If
 194    * str is null, the String "null" is appended.
 195    *
 196    * @param str the <code>String</code> to append
 197    * @return this <code>StringBuilder</code>
 198    */
 199   public StringBuilder append(String str)
 200   {
 201     if (str == null)
 202       str = "null";
 203     int len = str.count;
 204     ensureCapacity_unsynchronized(count + len);
 205     str.getChars(0, len, value, count);
 206     count += len;
 207     return this;
 208   }
 209
 210   /**
 211    * Append the <code>StringBuilder</code> value of the argument to this
 212    * <code>StringBuilder</code>. This behaves the same as
 213    * <code>append((Object) stringBuffer)</code>, except it is more efficient.
 214    *
 215    * @param stringBuffer the <code>StringBuilder</code> to convert and append
 216    * @return this <code>StringBuilder</code>
 217    * @see #append(Object)
 218    */
 219   public StringBuilder append(StringBuffer stringBuffer)
 220   {
 221     if (stringBuffer == null)
 222       return append("null");
 223     synchronized (stringBuffer)
 224     {
 225       int len = stringBuffer.count;
 226       ensureCapacity(count + len);
 227       System.arraycopy(stringBuffer.value, 0, value, count, len);
 228       count += len;
 229     }
 230     return this;
 231   }
 232
 233   public void ensureCapacity(int minimumCapacity)
 234   {
 235     ensureCapacity_unsynchronized(minimumCapacity);
 236   }
 237
 238   /**
 239    * Append the <code>char</code> array to this <code>StringBuilder</code>.
 240    * This is similar (but more efficient) than
 241    * <code>append(new String(data))</code>, except in the case of null.
 242    *
 243    * @param data the <code>char[]</code> to append
 244    * @return this <code>StringBuilder</code>
 245    * @throws NullPointerException if <code>str</code> is <code>null</code>
 246    * @see #append(char[], int, int)
 247    */
 248   public StringBuilder append(char[] data)
 249   {
 250     append(data, 0, data.length);
 251     return this;
 252   }
 253
 254   /**
 255    * Append part of the <code>char</code> array to this
 256    * <code>StringBuilder</code>. This is similar (but more efficient) than
 257    * <code>append(new String(data, offset, count))</code>, except in the case
 258    * of null.
 259    *
 260    * @param data the <code>char[]</code> to append
 261    * @param offset the start location in <code>str</code>
 262    * @param count the number of characters to get from <code>str</code>
 263    * @return this <code>StringBuilder</code>
 264    * @throws NullPointerException if <code>str</code> is <code>null</code>
 265    * @throws IndexOutOfBoundsException if offset or count is out of range
 266    *         (while unspecified, this is a StringIndexOutOfBoundsException)
 267    */
 268   public StringBuilder append(char[] data, int offset, int count)
 269   {
 270     if (offset < 0 || count < 0 || offset > data.length - count)
 271       throw new /*StringIndexOutOfBounds*/Exception("StringIndexOutOfBoundsException");
 272     ensureCapacity_unsynchronized(this.count + count);
 273     System.arraycopy(data, offset, value, this.count, count);
 274     this.count += count;
 275     return this;
 276   }
 277
 278   /**
 279    * Append the <code>String</code> value of the argument to this
 280    * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
 281    * to <code>String</code>.
 282    *
 283    * @param bool the <code>boolean</code> to convert and append
 284    * @return this <code>StringBuilder</code>
 285    * @see String#valueOf(boolean)
 286    */
 287   public StringBuilder append(boolean bool)
 288   {
 289     append(bool?"true":"false");
 290     return this;
 291   }
 292
 293   /**
 294    * Append the <code>char</code> to this <code>StringBuilder</code>.
 295    *
 296    * @param ch the <code>char</code> to append
 297    * @return this <code>StringBuilder</code>
 298    */
 299   public StringBuilder append(char ch)
 300   {
 301     ensureCapacity_unsynchronized(count + 1);
 302     value[count++] = ch;
 303     return this;
 304   }
 305
 306   /**
 307    * Append the <code>String</code> value of the argument to this
 308    * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
 309    * to <code>String</code>.
 310    *
 311    * @param inum the <code>int</code> to convert and append
 312    * @return this <code>StringBuilder</code>
 313    * @see String#valueOf(int)
 314    */
 315   // This is native in libgcj, for efficiency.
 316   public StringBuilder append(int inum)
 317   {
 318     append(String.valueOf(inum));
 319     return this;
 320   }
 321
 322   /**
 323    * Append the <code>String</code> value of the argument to this
 324    * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
 325    * to <code>String</code>.
 326    *
 327    * @param lnum the <code>long</code> to convert and append
 328    * @return this <code>StringBuilder</code>
 329    * @see String#valueOf(long)
 330    */
 331   public StringBuilder append(long lnum)
 332   {
 333     append(String.valueOf(lnum));
 334     return this;
 335   }
 336
 337   /**
 338    * Append the <code>String</code> value of the argument to this
 339    * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
 340    * to <code>String</code>.
 341    *
 342    * @param fnum the <code>float</code> to convert and append
 343    * @return this <code>StringBuilder</code>
 344    * @see String#valueOf(float)
 345    */
 346   public StringBuilder append(float fnum)
 347   {
 348     append(String.valueOf((double)fnum));
 349     return this;
 350   }
 351
 352   /**
 353    * Append the <code>String</code> value of the argument to this
 354    * <code>StringBuilder</code>. Uses <code>String.valueOf()</code> to convert
 355    * to <code>String</code>.
 356    *
 357    * @param dnum the <code>double</code> to convert and append
 358    * @return this <code>StringBuilder</code>
 359    * @see String#valueOf(double)
 360    */
 361   public StringBuilder append(double dnum)
 362   {
 363     append(String.valueOf(dnum));
 364     return this;
 365   }
 366
 367   /**
 368    * Convert this <code>StringBuilder</code> to a <code>String</code>. The
 369    * String is composed of the characters currently in this StringBuilder. Note
 370    * that the result is a copy, and that future modifications to this buffer
 371    * do not affect the String.
 372    *
 373    * @return the characters in this StringBuilder
 374    */
 375   public String toString()
 376   {
 377     return new String(this.value, 0, this.count);
 378   }
 379
 380 }