libjava/classpath/java/io/CharArrayWriter.java

   1 /* CharArrayWriter.java -- Write chars to a buffer
   2    Copyright (C) 1998, 1999, 2001, 2002, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.io;
  40
  41 /**
  42   * This class allows data to be written to a char array buffer and
  43   * and then retrieved by an application.   The internal char array
  44   * buffer is dynamically resized to hold all the data written.  Please
  45   * be aware that writing large amounts to data to this stream will
  46   * cause large amounts of memory to be allocated.
  47   * <p>
  48   * The size of the internal buffer defaults to 32 and it is resized
  49   * in increments of 1024 chars.  This behavior can be over-ridden by using the
  50   * following two properties:
  51   * <p>
  52   * <ul>
  53   * <li><xmp>gnu.java.io.CharArrayWriter.initialBufferSize</xmp></li>
  54   * <li><xmp>gnu.java.io.CharArrayWriter.bufferIncrementSize</xmp></li>
  55   * </ul>
  56   * <p>
  57   * There is a constructor that specified the initial buffer size and
  58   * that is the preferred way to set that value because it it portable
  59   * across all Java class library implementations.
  60   * <p>
  61   *
  62   * @author Aaron M. Renn (arenn@urbanophile.com)
  63   * @author Tom Tromey (tromey@cygnus.com)
  64   */
  65 public class CharArrayWriter extends Writer
  66 {
  67   /**
  68    * The default initial buffer size
  69    */
  70   private static final int DEFAULT_INITIAL_BUFFER_SIZE = 32;
  71
  72   /**
  73    * This method initializes a new <code>CharArrayWriter</code> with
  74    * the default buffer size of 32 chars.  If a different initial
  75    * buffer size is desired, see the constructor
  76    * <code>CharArrayWriter(int size)</code>.
  77    */
  78   public CharArrayWriter ()
  79   {
  80     this (DEFAULT_INITIAL_BUFFER_SIZE);
  81   }
  82
  83   /**
  84    * This method initializes a new <code>CharArrayWriter</code> with
  85    * a specified initial buffer size.
  86    *
  87    * @param size The initial buffer size in chars
  88    */
  89   public CharArrayWriter (int size)
  90   {
  91     super ();
  92     buf = new char[size];
  93   }
  94
  95   /**
  96    * Closes the stream.  This method is guaranteed not to free the contents
  97    * of the internal buffer, which can still be retrieved.
  98    */
  99   public void close ()
 100   {
 101   }
 102
 103   /**
 104    * This method flushes all buffered chars to the stream.
 105    */
 106   public void flush ()
 107   {
 108   }
 109
 110   /**
 111    * This method discards all of the chars that have been written to the
 112    * internal buffer so far by setting the <code>count</code> variable to
 113    * 0.  The internal buffer remains at its currently allocated size.
 114    */
 115   public void reset ()
 116   {
 117     synchronized (lock)
 118       {
 119         count = 0;
 120       }
 121   }
 122
 123   /**
 124    * This method returns the number of chars that have been written to
 125    * the buffer so far.  This is the same as the value of the protected
 126    * <code>count</code> variable.  If the <code>reset</code> method is
 127    * called, then this value is reset as well.  Note that this method does
 128    * not return the length of the internal buffer, but only the number
 129    * of chars that have been written to it.
 130    *
 131    * @return The number of chars in the internal buffer
 132    *
 133    * @see #reset()
 134    */
 135   public int size ()
 136   {
 137     return count;
 138   }
 139
 140   /**
 141    * This method returns a char array containing the chars that have been
 142    * written to this stream so far.  This array is a copy of the valid
 143    * chars in the internal buffer and its length is equal to the number of
 144    * valid chars, not necessarily to the the length of the current
 145    * internal buffer.  Note that since this method allocates a new array,
 146    * it should be used with caution when the internal buffer is very large.
 147    */
 148   public char[] toCharArray ()
 149   {
 150     synchronized (lock)
 151       {
 152         char[] nc = new char[count];
 153         System.arraycopy(buf, 0, nc, 0, count);
 154         return nc;
 155       }
 156   }
 157
 158   /**
 159    * Returns the chars in the internal array as a <code>String</code>.  The
 160    * chars in the buffer are converted to characters using the system default
 161    * encoding.  There is an overloaded <code>toString()</code> method that
 162    * allows an application specified character encoding to be used.
 163    *
 164    * @return A <code>String</code> containing the data written to this
 165    *         stream so far
 166    */
 167   public String toString ()
 168   {
 169     synchronized (lock)
 170       {
 171         return new String (buf, 0, count);
 172       }
 173   }
 174
 175   /**
 176    * This method writes the writes the specified char into the internal
 177    * buffer.
 178    *
 179    * @param oneChar The char to be read passed as an int
 180    */
 181   public void write (int oneChar)
 182   {
 183     synchronized (lock)
 184       {
 185         resize (1);
 186         buf[count++] = (char) oneChar;
 187       }
 188   }
 189
 190   /**
 191    * This method writes <code>len</code> chars from the passed in array
 192    * <code>buf</code> starting at index <code>offset</code> into that buffer
 193    *
 194    * @param buffer The char array to write data from
 195    * @param offset The index into the buffer to start writing data from
 196    * @param len The number of chars to write
 197    */
 198   public void write (char[] buffer, int offset, int len)
 199   {
 200     synchronized (lock)
 201       {
 202         if (len >= 0)
 203           resize (len);
 204         System.arraycopy(buffer, offset, buf, count, len);
 205         count += len;
 206       }
 207   }
 208
 209   /**
 210    * This method writes <code>len</code> chars from the passed in
 211    * <code>String</code> <code>buf</code> starting at index
 212    * <code>offset</code> into the internal buffer.
 213    *
 214    * @param str The <code>String</code> to write data from
 215    * @param offset The index into the string to start writing data from
 216    * @param len The number of chars to write
 217    */
 218   public void write (String str, int offset, int len)
 219   {
 220     synchronized (lock)
 221       {
 222         if (len >= 0)
 223           resize (len);
 224         str.getChars(offset, offset + len, buf, count);
 225         count += len;
 226       }
 227   }
 228
 229   /**
 230    * This method writes all the chars that have been written to this stream
 231    * from the internal buffer to the specified <code>Writer</code>.
 232    *
 233    * @param out The <code>Writer</code> to write to
 234    *
 235    * @exception IOException If an error occurs
 236    */
 237   public void writeTo (Writer out) throws IOException
 238   {
 239     synchronized (lock)
 240       {
 241         out.write(buf, 0, count);
 242       }
 243   }
 244
 245   /**
 246    * Appends the Unicode character, <code>c</code>, to the output stream
 247    * underlying this writer.  This is equivalent to <code>write(c)</code>.
 248    *
 249    * @param c the character to append.
 250    * @return a reference to this object.
 251    * @since 1.5
 252    */
 253   public CharArrayWriter append(char c)
 254   {
 255     write(c);
 256     return this;
 257   }
 258
 259   /**
 260    * Appends the specified sequence of Unicode characters to the
 261    * output stream underlying this writer.  This is equivalent to
 262    * appending the results of calling <code>toString()</code> on the
 263    * character sequence.  As a result, the entire sequence may not be
 264    * appended, as it depends on the implementation of
 265    * <code>toString()</code> provided by the
 266    * <code>CharSequence</code>.  For example, if the character
 267    * sequence is wrapped around an input buffer, the results will
 268    * depend on the current position and length of that buffer.
 269    *
 270    * @param seq the character sequence to append.  If seq is null,
 271    *        then the string "null" (the string representation of null)
 272    *        is appended.
 273    * @return a reference to this object.
 274    * @since 1.5
 275    */
 276   public CharArrayWriter append(CharSequence cs)
 277   {
 278     try
 279       {
 280         write(cs == null ? "null" : cs.toString());
 281       }
 282     catch (IOException _)
 283       {
 284         // Can't happen.
 285       }
 286     return this;
 287   }
 288
 289   /**
 290    * Appends the specified subsequence of Unicode characters to the
 291    * output stream underlying this writer, starting and ending at the
 292    * specified positions within the sequence.  The behaviour of this
 293    * method matches the behaviour of writing the result of
 294    * <code>append(seq.subSequence(start,end))</code> when the sequence
 295    * is not null.
 296    *
 297    * @param seq the character sequence to append.  If seq is null,
 298    *        then the string "null" (the string representation of null)
 299    *        is appended.
 300    * @param start the index of the first Unicode character to use from
 301    *        the sequence.
 302    * @param end the index of the last Unicode character to use from the
 303    *        sequence.
 304    * @return a reference to this object.
 305    * @throws IndexOutOfBoundsException if either of the indices are negative,
 306    *         the start index occurs after the end index, or the end index is
 307    *         beyond the end of the sequence.
 308    * @since 1.5
 309    */
 310   public CharArrayWriter append(CharSequence cs, int start, int end)
 311   {
 312     try
 313       {
 314         write(cs == null ? "null" : cs.subSequence(start, end).toString());
 315       }
 316     catch (IOException _)
 317       {
 318         // Can't happen.
 319       }
 320     return this;
 321   }
 322
 323   /**
 324    * This private method makes the buffer bigger when we run out of room
 325    * by allocating a larger buffer and copying the valid chars from the
 326    * old array into it.  This is obviously slow and should be avoided by
 327    * application programmers by setting their initial buffer size big
 328    * enough to hold everything if possible.
 329    */
 330   private void resize (int len)
 331   {
 332     if (count + len >= buf.length)
 333       {
 334         int newlen = buf.length * 2;
 335         if (count + len > newlen)
 336           newlen = count + len;
 337         char[] newbuf = new char[newlen];
 338         System.arraycopy(buf, 0, newbuf, 0, count);
 339         buf = newbuf;
 340       }
 341   }
 342
 343   /**
 344    * The internal buffer where the data written is stored
 345    */
 346   protected char[] buf;
 347
 348   /**
 349    * The number of chars that have been written to the buffer
 350    */
 351   protected int count;
 352 }