public class

PushbackReader

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

Class Overview

Wraps an existing Reader and adds functionality to "push back" characters that have been read, so that they can be read again. Parsers may find this useful. The number of characters which may be pushed back can be specified during construction. If the buffer of pushed back bytes is empty, characters are read from the underlying reader.

Summary

[Expand]
Inherited Fields
From class java.io.FilterReader
From class java.io.Reader
Public Constructors
PushbackReader(Reader in)
Constructs a new PushbackReader with the specified reader as source.
PushbackReader(Reader in, int size)
Constructs a new PushbackReader with in as source reader.
Public Methods
void close()
Closes this reader.
void mark(int readAheadLimit)
Marks the current position in this stream.
boolean markSupported()
Indicates whether this reader supports the mark(int) and reset() methods.
int read(char[] buffer, int offset, int count)
Reads at most length bytes from this reader and stores them in byte array buffer starting at offset.
int read()
Reads a single character from this reader and returns it as an integer with the two higher-order bytes set to 0.
boolean ready()
Indicates whether this reader is ready to be read without blocking.
void reset()
Resets this reader to the last marked position.
long skip(long count)
Skips count characters in this reader.
void unread(char[] buffer)
Pushes all the characters in buffer back to this reader.
void unread(char[] buffer, int offset, int count)
Pushes a subset of the characters in buffer back to this reader.
void unread(int oneChar)
Pushes the specified character oneChar back to this reader.
[Expand]
Inherited Methods
From class java.io.FilterReader
From class java.io.Reader
From class java.lang.Object
From interface java.io.Closeable
From interface java.lang.Readable

Public Constructors

public PushbackReader (Reader in)

Since: API Level 1

Constructs a new PushbackReader with the specified reader as source. The size of the pushback buffer is set to the default value of 1 character.

Parameters
in the source reader.

public PushbackReader (Reader in, int size)

Since: API Level 1

Constructs a new PushbackReader with in as source reader. The size of the pushback buffer is set to size.

Parameters
in the source reader.
size the size of the pushback buffer.
Throws
IllegalArgumentException if size is negative.

Public Methods

public void close ()

Since: API Level 1

Closes this reader. This implementation closes the source reader and releases the pushback buffer.

Throws
IOException if an error occurs while closing this reader.

public void mark (int readAheadLimit)

Since: API Level 1

Marks the current position in this stream. Setting a mark is not supported in this class; this implementation always throws an IOException.

Parameters
readAheadLimit the number of character that can be read from this reader before the mark is invalidated; this parameter is ignored.
Throws
IOException if this method is called.

public boolean markSupported ()

Since: API Level 1

Indicates whether this reader supports the mark(int) and reset() methods. PushbackReader does not support them, so it returns false.

Returns
  • always false.
See Also

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

Since: API Level 1

Reads at most length bytes from this reader and stores them in byte array buffer starting at offset. Characters are read from the pushback buffer first, then from the source reader if more bytes are required. Blocks until count characters have been read, the end of the source reader is detected or an exception is thrown.

Parameters
buffer the array in which to store the characters read from this reader.
offset the initial position in buffer to store the characters read from this reader.
count the maximum number of bytes to store in buffer.
Returns
  • the number of bytes read or -1 if the end of the source reader has been reached.
Throws
IndexOutOfBoundsException if offset < 0 or count < 0, or if offset + count is greater than the length of buffer.
IOException if this reader is closed or another I/O error occurs while reading from this reader.

public int read ()

Since: API Level 1

Reads a single character from this reader and returns it as an integer with the two higher-order bytes set to 0. Returns -1 if the end of the reader has been reached. If the pushback buffer does not contain any available characters then a character from the source reader is returned. Blocks until one character has been read, the end of the source reader is detected or an exception is thrown.

Returns
  • the character read or -1 if the end of the source reader has been reached.
Throws
IOException if this reader is closed or an I/O error occurs while reading from this reader.

public boolean ready ()

Since: API Level 1

Indicates whether this reader is ready to be read without blocking. Returns true if this reader will not block when read is called, false if unknown or blocking will occur.

Returns
  • true if the receiver will not block when read() is called, false if unknown or blocking will occur.
Throws
IOException if this reader is closed or some other I/O error occurs.
See Also

public void reset ()

Since: API Level 1

Resets this reader to the last marked position. Resetting the reader is not supported in this class; this implementation always throws an IOException.

Throws
IOException if this method is called.

public long skip (long count)

Since: API Level 1

Skips count characters in this reader. This implementation skips characters in the pushback buffer first and then in the source reader if necessary.

Parameters
count the number of characters to skip.
Returns
  • the number of characters actually skipped.
Throws
IllegalArgumentException if count < 0.
IOException if this reader is closed or another I/O error occurs.

public void unread (char[] buffer)

Since: API Level 1

Pushes all the characters in buffer back to this reader. The characters are pushed back in such a way that the next character read from this reader is buffer[0], then buffer[1] and so on.

If this reader's internal pushback buffer cannot store the entire contents of buffer, an IOException is thrown. Parts of buffer may have already been copied to the pushback buffer when the exception is thrown.

Parameters
buffer the buffer containing the characters to push back to this reader.
Throws
IOException if this reader is closed or the free space in the internal pushback buffer is not sufficient to store the contents of buffer.

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

Since: API Level 1

Pushes a subset of the characters in buffer back to this reader. The subset is defined by the start position offset within buffer and the number of characters specified by length. The bytes are pushed back in such a way that the next byte read from this stream is buffer[offset], then buffer[1] and so on.

If this stream's internal pushback buffer cannot store the selected subset of buffer, an IOException is thrown. Parts of buffer may have already been copied to the pushback buffer when the exception is thrown.

Parameters
buffer the buffer containing the characters to push back to this reader.
offset the index of the first byte in buffer to push back.
count the number of bytes to push back.
Throws
IndexOutOfBoundsException if offset < 0 or count < 0, or if offset + count is greater than the length of buffer.
IOException if this reader is closed or the free space in the internal pushback buffer is not sufficient to store the selected contents of buffer.
NullPointerException if buffer is null.

public void unread (int oneChar)

Since: API Level 1

Pushes the specified character oneChar back to this reader. This is done in such a way that the next character read from this reader is (char) oneChar.

If this reader's internal pushback buffer cannot store the character, an IOException is thrown.

Parameters
oneChar the character to push back to this stream.
Throws
IOException if this reader is closed or the internal pushback buffer is full.