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:    * 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 cs 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 cs 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: }