Source for java.io.CharArrayWriter

   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:    * This private method makes the buffer bigger when we run out of room
 247:    * by allocating a larger buffer and copying the valid chars from the
 248:    * old array into it.  This is obviously slow and should be avoided by
 249:    * application programmers by setting their initial buffer size big
 250:    * enough to hold everything if possible.
 251:    */
 252:   private void resize (int len)
 253:   {
 254:     if (count + len >= buf.length)
 255:       {
 256:     int newlen = buf.length * 2;
 257:     if (count + len > newlen)
 258:       newlen = count + len;
 259:     char[] newbuf = new char[newlen];
 260:     System.arraycopy(buf, 0, newbuf, 0, count);
 261:     buf = newbuf;
 262:       }
 263:   }
 264: 
 265:   /**
 266:    * The internal buffer where the data written is stored
 267:    */
 268:   protected char[] buf;
 269: 
 270:   /**
 271:    * The number of chars that have been written to the buffer
 272:    */
 273:   protected int count;
 274: }