PushbackInputStream

The java.io.PushbackInputStream class provides a pushback buffer so a program can "unread" bytes. In other words, it can add bytes to the stream and then read them. These may be bytes the program has read from the underlying InputStream or they may be completely different bytes. In effect, PushbackInputStream allows programs to add data to a stream while they're reading it. The next time data is read from the stream, the unread bytes are reread.

public void unread(int b) throws IOException
public void unread(byte[] data, int offset, int length) throws IOException
public void unread(byte[] data) throws IOException

By default, the buffer is only 1 byte long, and trying to unread more than 1 byte throws an IOException. However, you can change the default buffer size with the second constructor:

public PushbackInputStream(InputStream in)
public PushbackInputStream(InputStream in, int size)

Unread data is pushed onto a stack. In other words, the last byte you unread is the first byte you read. This code fragment prints 2, 1, 0; not 0, 1, 2:

PushbackInputStream in = new PushbackInputStream(System.in, 5);
in.unread(0);
in.unread(1);
in.unread(2);
System.out.println(in.read( ));
System.out.println(in.read( ));
System.out.println(in.read( ));

One common use for PushbackInputStream is tokenizing source code. For example, suppose a compiler is reading the Java statement int count=7;. Because Java variable names can have any length, the compiler doesn't know that the last character is t until it has read the equals sign (=). However, by the time it knows this, it has already read the equals sign. A PushbackInputStream allows the compiler to unread the equals sign and continue, this time treating the sign as an operator rather than as a piece of an identifier. Other times, the program may want to add something to the stream that wasn't there before and then read it in the usual way. For instance, to convert a Mac text file to a Windows text file, a program could unread a linefeed after it reads a carriage return.

Although both PushbackInputStream and BufferedInputStream use buffers, only a PushbackInputStream allows unreading, and only a BufferedInputStream allows marking and resetting. In a PushbackInputStream, markSupported( ) returns false.

The read( ) and available( ) methods are invoked exactly as they are with normal input streams. However, they first attempt to read from the pushback buffer.