java.io
Class PushbackReader

java.lang.Object
  java.io.Reader
      java.io.FilterReader
          java.io.PushbackReader

All Implemented Interfaces:

Closeable, Readable

public class PushbackReader
extends FilterReader

PushbackReader is a filter class which allows chars read to be pushed back into the stream so that they can be reread. Parsers may find this useful. There is a progammable limit to the number of chars which may be pushed back. If the buffer of pushed back chars is empty, chars are read from the source reader.

Field Summary

(package private) char[]	buf The char array containing the chars to read.
(package private) int	pos The current position within the char array buf.

Fields inherited from class java.io.FilterReader

in

Fields inherited from class java.io.Reader

lock

Constructor Summary

PushbackReader(Reader in)
Constructs a new PushbackReader on the Reader in.

PushbackReader(Reader in, int size)
Constructs a new PushbackReader on the Reader in.

Method Summary

void	close() Close this PushbackReader.
void	mark(int readAheadLimit) Mark this PushbackReader.
boolean	markSupported() Returns a boolean indicating whether or not this PushbackReader supports mark() and reset().
int	read() Reads a single character from this PushbackReader and returns the result as an int.
int	read(char[] buffer, int offset, int count) Reads at most count chars from this PushbackReader and stores them in char array buffer starting at offset.
boolean	ready() Returns a boolean indicating whether or not this PushbackReader is ready to be read without blocking.
void	reset() Resets this PushbackReader.
long	skip(long count) Skips count number of characters in this Reader.
void	unread(char[] buffer) Push back all the chars in buffer.
void	unread(char[] buffer, int offset, int count) Push back count number of chars in buffer starting at offset.
void	unread(int oneChar) Push back one char.

Methods inherited from class java.io.Reader

read, read

Methods inherited from class java.lang.Object

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

Field Detail

buf

char[] buf

The char array containing the chars to read.

pos

int pos

The current position within the char array buf. A value equal to buf.length indicates no chars available. A value of 0 indicates the buffer is full.

Constructor Detail

PushbackReader

public PushbackReader(Reader in)

Constructs a new PushbackReader on the Reader in. The size of the pushback buffer is set to the default, or 1 character.

Parameters:

in - the Reader to allow pushback operations on.

PushbackReader

public PushbackReader(Reader in,
                      int size)

Constructs a new PushbackReader on the Reader in. The size of the pushback buffer is set to size characters.

Parameters:

in - the Reader to allow pushback operations on.

size - the size of the pushback buffer (size>=0) in characters.

Throws:

IllegalArgumentException - if size <= 0

Method Detail

close

public void close()
           throws IOException

Close this PushbackReader. This implementation closes this reader, releases the buffer used to pushback characters, and closes the target reader.

Specified by:

close in interface Closeable

Overrides:

close in class FilterReader

Throws:

IOException - If an error occurs attempting to close this Reader.

mark

public void mark(int readAheadLimit)
          throws IOException

Mark this PushbackReader. Since mark is not supported, this method will always throw IOException.

Overrides:

mark in class FilterReader

Parameters:

readAheadLimit - ignored, this method always throws IOException.

Throws:

IOException - Since mark is not supported byt PushbackReader.

markSupported

public boolean markSupported()

Returns a boolean indicating whether or not this PushbackReader supports mark() and reset(). This implementation always returns false since PushbackReaders do not support mark/reset.

Overrides:

markSupported in class FilterReader

Returns:

boolean indicates whether or not mark() and reset() are supported.

read

public int read()
         throws IOException

Reads a single character from this PushbackReader and returns the result as an int. The 2 lowest-order bytes are returned or -1 of the end of stream was encountered. If the pushback buffer does not contain any available chars then a char from the target input reader is returned.

Overrides:

read in class FilterReader

Returns:

int The char read or -1 if end of stream.

Throws:

IOException - If an IOException occurs.

read

public int read(char[] buffer,
                int offset,
                int count)
         throws IOException

Reads at most count chars from this PushbackReader and stores them in char array buffer starting at offset. Answer the number of chars actually read or -1 if no chars were read and end of stream was encountered. This implementation reads chars from the pushback buffer first, then the target stream if more chars are required to satisfy count.

Overrides:

read in class FilterReader

Parameters:

buffer - the char array in which to store the read chars.

offset - the offset in buffer to store the read chars.

count - the maximum number of chars to store in buffer.

Returns:

the number of chars actually read or -1 if end of stream.

Throws:

IOException - If an IOException occurs.

ready

public boolean ready()
              throws IOException

Returns a boolean indicating whether or not this PushbackReader is ready to be read without blocking. If the result is true, the next read() will not block. If the result is false this Reader may or may not block when read() is sent.

Overrides:

ready in class FilterReader

Returns:

boolean true if the receiver will not block when read() is called, false if unknown or blocking will occur.

Throws:

IOException - If the Reader is already closed or some other IO error occurs.

reset

public void reset()
           throws IOException

Resets this PushbackReader. Since mark is not supported, always throw IOException.

Overrides:

reset in class FilterReader

Throws:

IOException - Since mark is not supported.

unread

public void unread(char[] buffer)
            throws IOException

Push back all the chars in buffer. The chars are pushed so that they would be read back buffer[0], buffer[1], etc. If the push back buffer cannot handle the entire contents of buffer, an IOException will be thrown. Some of the buffer may already be in the buffer after the exception is thrown.

Parameters:

buffer - the char array containing chars to push back into the reader.

Throws:

IOException - If the pushback buffer becomes, or is, full.

unread

public void unread(char[] buffer,
                   int offset,
                   int count)
            throws IOException

Push back count number of chars in buffer starting at offset. The chars are pushed so that they would be read back buffer[offset], buffer[offset+1], etc. If the push back buffer cannot handle the chars copied from buffer, an IOException will be thrown. Some of the chars may already be in the buffer after the exception is thrown.

Parameters:

buffer - the char array containing chars to push back into the reader.

offset - the location to start taking chars to push back.

count - the number of chars to push back.

Throws:

IOException - If the pushback buffer becomes, or is, full.

unread

public void unread(int oneChar)
            throws IOException

Push back one char. Takes the char oneChar and puts in in the local buffer of chars to read back before accessing the target input stream.

Parameters:

oneChar - the char to push back into the stream.

Throws:

IOException - If the pushback buffer is already full.

skip

public long skip(long count)
          throws IOException

Skips count number of characters in this Reader. Subsequent read()'s will not return these characters unless reset() is used.

Overrides:

skip in class FilterReader

Parameters:

count - the maximum number of characters to skip.

Returns:

the number of characters actually skipped.

Throws:

IOException - If the Reader is already closed or some other IO error occurs.

IllegalArgumentException - If count is negative.