Character Array Readers and Writers

The ByteArrayInputStream and ByteArrayOutputStream classes use stream methods to read and write arrays of bytes. The CharArrayReader and CharArrayWriter classes use Reader and Writer methods to read and write arrays of chars. Since char arrays are purely internal to Java, this is one of the few uses of readers and writers where you don't need to concern yourself with conversions between different encodings. If you want to read arrays of text encoded in some non-Unicode encoding, you should chain a ByteArrayInputStream to an InputStreamReader instead. Similarly, to write text into a byte array in a non-Unicode encoding, just chain an OutputStreamWriter to a ByteArrayOutputStream.

20.6.1. The CharArrayWriter Class

A CharArrayWriter maintains an internal array of chars into which successive characters are written. The array is expanded as needed. This array is stored in a protected field called buf:

protected char[] buf

The no-argument constructor creates a CharArrayWriter object with a 32-character buffer. This is on the small side, so you can expand it with the second constructor:

public CharArrayWriter( ) public CharArrayWriter(int initialSize)

The write( ) methods write their characters into the buffer. If there's insufficient space in buf to hold the characters, it's expanded to at least the amount necessary to hold the extra text.

The buffer can be read in several ways. The writeTo( ) method copies the text in the buffer onto another Writer object:

public void writeTo(Writer out) throws IOException

The toCharArray( ) method returns a copy of the text in the buffer:

public char[] toCharArray( )

Changes to the copy do not affect the CharArrayWriter's internal data and vice versa.

The toString( ) method returns a string initialized from the characters stored in the buffer:

public String toString( )

The size( ) method returns the number of characters currently stored in the buffer:

public int size( )

Finally, the reset( ) method empties the buffer so that the writer can be reused for new data:

public void reset( )

However, the internal buffer is not freed and still occupies memory. It will only be garbage collected when the writer itself is.

There is a close( ) method, but it's a no-op. In fact, you can continue writing to a CharArrayWriter after it's been closed. This should probably be classified as a bug.

For example, the following code fragment fills a char array with the Unicode Basic Multilingual Plane:

CharArrayWriter caw = new CharArrayWriter(65536); for (int i = 0; i < 65536; i++) { caw.write(i); } caw.close( ); char[] unicode = caw.toCharArray( );

20.6.2. The CharArrayReader Class

A CharArrayReader uses an array of chars as the underlying source of text to read. It is one of the few readers that does not have an underlying input stream; it has an underlying char array instead. This array is set in the constructor. Either an entire array may be used or a specified subarray beginning at offset and continuing for length characters:

public CharArrayReader(char[] text) public CharArrayReader(char[] text, int offset, int length)

The CharArrayReader class stores a reference to the text array in a protected field called buf. A separate copy is not made. Modifying this array from outside the class can violate data encapsulation and potentially cause thread synchronization problems. The reader also stores the current position in the array (the index of the next array component that will be returned by read( )), the number of chars in the array, and the current mark, if any.

protected char[] buf protected int pos protected int count protected int markedPos

The read( ) methods read text from the buf array, updating the pos field as they do so. These methods behave like any other reader's read( ) methods. If the end of the array is reached, they return -1.

CharArrayReaders support marking and resetting to the limit of the length of the array. markSupported( ) returns true. mark( ) marks the current position in the stream by setting markedPos equal to pos. The readAheadLimit argument is for compatibility; its value is ignored. The reset( ) method sets pos equal to markedPos.

Finally, the close( ) method sets buf to null so that the array can be garbage collected. Attempts to read from a CharArrayReader after it's been closed throw IOExceptions.