Package java.io

Class PushbackReader

java.lang.Object
java.io.Reader
java.io.FilterReader
java.io.PushbackReader
All Implemented Interfaces:
Closeable, AutoCloseable, Readable
public class PushbackReader
extends FilterReader
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.

  • Field Summary

    Fields inherited from class java.io.FilterReader

    in

    Fields inherited from class java.io.Reader

    lock

  • Constructor Summary

    Constructors
    Constructor Description
    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.

  • Method Summary

    Modifier and Type Method Description
    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()
    Reads a single character from this reader and returns it as an integer with the two higher-order bytes set to 0.
    int read​(char[] buffer, int offset, int count)
    Reads up to count characters from this reader and stores them in character array buffer starting at offset.
    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 charCount)
    Skips charCount 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 length)
    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.

    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

  • Constructor Details

    • PushbackReader

      public PushbackReader​(Reader in)
      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.

    • PushbackReader

      public PushbackReader​(Reader in, int size)
      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.

  • Method Details

    • close

      public void close() throws IOException
      Closes this reader. This implementation closes the source reader and releases the pushback buffer.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Overrides:
      close in class FilterReader
      Throws:
      IOException - if an error occurs while closing this reader.

    • mark

      public void mark​(int readAheadLimit) throws IOException
      Marks the current position in this stream. Setting a mark is not supported in this class; this implementation always throws an IOException.
      Overrides:
      mark in class FilterReader
      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.
      See Also:
      FilterReader.markSupported(), FilterReader.reset()

    • markSupported

      public boolean markSupported()
      Indicates whether this reader supports the mark(int) and reset() methods. PushbackReader does not support them, so it returns false.
      Overrides:
      markSupported in class FilterReader
      Returns:
      always false.
      See Also:
      mark(int), reset()

    • read

      public int read() throws IOException
      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.
      Overrides:
      read in class FilterReader
      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.

    • read

      public int read​(char[] buffer, int offset, int count) throws IOException
      Reads up to count characters from this reader and stores them in character 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. Returns the number of bytes read or -1 if the end of the source reader has been reached.
      Overrides:
      read in class FilterReader
      Throws:
      IndexOutOfBoundsException - if offset < 0 || count < 0 || offset + count > buffer.length.
      IOException - if this reader is closed or another I/O error occurs while reading from this reader.

    • ready

      public boolean ready() throws IOException
      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.
      Overrides:
      ready in class FilterReader
      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:
      read(), read(char[], int, int)

    • reset

      public void reset() throws IOException
      Resets this reader to the last marked position. Resetting the reader is not supported in this class; this implementation always throws an IOException.
      Overrides:
      reset in class FilterReader
      Throws:
      IOException - if this method is called.
      See Also:
      FilterReader.mark(int), FilterReader.markSupported()

    • unread

      public void unread​(char[] buffer) throws IOException
      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.

    • unread

      public void unread​(char[] buffer, int offset, int length) throws IOException
      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.
      length - 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.

    • unread

      public void unread​(int oneChar) throws IOException
      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.

    • skip

      public long skip​(long charCount) throws IOException
      Skips charCount characters in this reader. This implementation skips characters in the pushback buffer first and then in the source reader if necessary.
      Overrides:
      skip in class FilterReader
      Returns:
      the number of characters actually skipped.
      Throws:
      IllegalArgumentException - if charCount < 0.
      IOException - if this reader is closed or another I/O error occurs.
      See Also:
      FilterReader.mark(int), FilterReader.markSupported(), FilterReader.reset()