001/* CharArrayWriter.java -- Write chars to a buffer
002   Copyright (C) 1998, 1999, 2001, 2002, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010 
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.io;
040
041/**
042  * This class allows data to be written to a char array buffer and
043  * and then retrieved by an application.   The internal char array
044  * buffer is dynamically resized to hold all the data written.  Please
045  * be aware that writing large amounts to data to this stream will
046  * cause large amounts of memory to be allocated.
047  * <p>
048  * The size of the internal buffer defaults to 32 and it is resized
049  * in increments of 1024 chars.  This behavior can be over-ridden by using the
050  * following two properties:
051  * <p>
052  * <ul>
053  * <li><xmp>gnu.java.io.CharArrayWriter.initialBufferSize</xmp></li>
054  * <li><xmp>gnu.java.io.CharArrayWriter.bufferIncrementSize</xmp></li>
055  * </ul>
056  * <p>
057  * There is a constructor that specified the initial buffer size and
058  * that is the preferred way to set that value because it it portable
059  * across all Java class library implementations.
060  * <p>
061  *
062  * @author Aaron M. Renn (arenn@urbanophile.com)
063  * @author Tom Tromey (tromey@cygnus.com)
064  */
065public class CharArrayWriter extends Writer
066{
067  /**
068   * The default initial buffer size
069   */
070  private static final int DEFAULT_INITIAL_BUFFER_SIZE = 32;
071
072  /**
073   * This method initializes a new <code>CharArrayWriter</code> with
074   * the default buffer size of 32 chars.  If a different initial
075   * buffer size is desired, see the constructor
076   * <code>CharArrayWriter(int size)</code>.
077   */
078  public CharArrayWriter ()
079  {
080    this (DEFAULT_INITIAL_BUFFER_SIZE);
081  }
082
083  /**
084   * This method initializes a new <code>CharArrayWriter</code> with
085   * a specified initial buffer size.
086   *
087   * @param size The initial buffer size in chars
088   */
089  public CharArrayWriter (int size)
090  {
091    super ();
092    buf = new char[size];
093  }
094
095  /**
096   * Closes the stream.  This method is guaranteed not to free the contents
097   * of the internal buffer, which can still be retrieved.
098   */
099  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}