com.dautelle.util
Class Utf8StreamReader

java.lang.Object
  java.io.Reader
      com.dautelle.util.Utf8StreamReader

public final class Utf8StreamReader

extends java.io.Reader

This class represents an UTF-8 stream reader.

This reader supports surrogate char pairs (representing characters in the range [U+10000 .. U+10FFFF]). It can also be used to read characters unicodes (31 bits) directly (ref. read()).

Each invocation of one of the read() methods may cause one or more bytes to be read from the underlying byte-input stream. To enable the efficient conversion of bytes to characters, more bytes may be read ahead from the underlying stream than are necessary to satisfy the current read operation.

Unlike java.io.InputStreamReader this class does not allocate new buffers (e.g. java.nio.HeapCharBuffer) each time a read() is performed and its execution speed is therefore greatly improved (twice as fast).

Instances of this class can be reused for different input streams and can be part of a higher level component (e.g. parser) in order to avoid dynamic buffer allocation when the input source changes. Also wrapping using a java.io.BufferedReader is unnescessary as instances of this class embed their own data buffers.

Note: This reader is unsynchronized and does not test if the UTF-8 encoding is well-formed (e.g. UTF-8 sequences longer than necessary to encode a character).

This class is public domain (not copyrighted).

Version:

4.6, Jly 14, 2003

Author:

Jean-Marie Dautelle

See Also:

Utf8StreamWriter

Field Summary

Fields inherited from class java.io.Reader

lock

Constructor Summary

Utf8StreamReader()
Default constructor.

Utf8StreamReader(int bufferSize)
Creates a Utf8StreamReader of specified buffer size.

Method Summary

void	close() Closes the stream.
int	read() Reads a single character.
int	read(char[] cbuf, int off, int len) Reads characters into a portion of an array.
boolean	ready() Indicates if this stream is ready to be read.
Utf8StreamReader	setInputStream(java.io.InputStream inStream) Sets the input stream to use for reading until this reader is closed.

Methods inherited from class java.io.Reader

mark, markSupported, read, reset, skip

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Utf8StreamReader

public Utf8StreamReader()

Default constructor.

Utf8StreamReader

public Utf8StreamReader(int bufferSize)

Creates a Utf8StreamReader of specified buffer size.

Parameters:

bufferSize - the buffer size in bytes.

Method Detail

setInputStream

public Utf8StreamReader setInputStream(java.io.InputStream inStream)

Sets the input stream to use for reading until this reader is closed. For example:

     Reader reader = new Utf8StreamReader().setInputStream(inStream);
 

is equivalent but reads twice as fast as

     Reader reader = new java.io.InputStreamReader(inStream, "UTF-8");
 

Parameters:

inStream - the input stream.

Returns:

this UTF-8 reader.

See Also:

close()

ready

public boolean ready()
              throws java.io.IOException

Indicates if this stream is ready to be read.

Returns:

true if the next read() is guaranteed not to block for input; false otherwise.

Throws:

java.io.IOException - if an I/O error occurs.

close

public void close()
           throws java.io.IOException

Closes the stream. Once a stream has been closed, further read(), ready(), mark(), or reset() invocations will throw an IOException. Closing a previously-closed stream, however, has no effect.

Throws:

java.io.IOException - if an I/O error occurs.

read

public int read()
         throws java.io.IOException

Reads a single character. This method will block until a character is available, an I/O error occurs, or the end of the stream is reached.

Returns:

the 31-bits Unicode of the character read, or -1 if the end of the stream has been reached.

Throws:

java.io.IOException - if an I/O error occurs.

read

public int read(char[] cbuf,
                int off,
                int len)
         throws java.io.IOException

Reads characters into a portion of an array. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached.

Note: Characters between U+10000 and U+10FFFF are represented by surrogate pairs (two char).

Parameters:

cbuf - the destination buffer.

off - the offset at which to start storing characters.

len - the maximum number of characters to read

Returns:

the number of characters read, or -1 if the end of the stream has been reached

Throws:

java.io.IOException - if an I/O error occurs.