https://openjdk.java.net/ 
/*
 * Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package java.io;



A character-stream reader that allows characters to be pushed back into the
stream.

Author:     Mark Reinhold
Since:      1.1
/**
 * A character-stream reader that allows characters to be pushed back into the
 * stream.
 *
 * @author      Mark Reinhold
 * @since       1.1
 */

public class PushbackReader extends FilterReader {

    
Pushback buffer 
/** Pushback buffer */
    private char[] buf;

    
Current position in buffer 
/** Current position in buffer */
    private int pos;

    
Creates a new pushback reader with a pushback buffer of the given size.

Params:
  • in –   The reader from which characters will be read
  • size – The size of the pushback buffer
Throws:
/**
     * Creates a new pushback reader with a pushback buffer of the given size.
     *
     * @param   in   The reader from which characters will be read
     * @param   size The size of the pushback buffer
     * @throws  IllegalArgumentException if {@code size <= 0}
     */
    public PushbackReader(Reader in, int size) {
        super(in);
        if (size <= 0) {
            throw new IllegalArgumentException("size <= 0");
        }
        this.buf = new char[size];
        this.pos = size;
    }

    
Creates a new pushback reader with a one-character pushback buffer.

Params:
  • in –  The reader from which characters will be read
/**
     * Creates a new pushback reader with a one-character pushback buffer.
     *
     * @param   in  The reader from which characters will be read
     */
    public PushbackReader(Reader in) {
        this(in, 1);
    }

    
Checks to make sure that the stream has not been closed. 
/** Checks to make sure that the stream has not been closed. */
    private void ensureOpen() throws IOException {
        if (buf == null)
            throw new IOException("Stream closed");
    }

    
Reads a single character.

Throws:
Returns:    The character read, or -1 if the end of the stream has been
            reached
/**
     * Reads a single character.
     *
     * @return     The character read, or -1 if the end of the stream has been
     *             reached
     *
     * @throws     IOException  If an I/O error occurs
     */
    public int read() throws IOException {
        synchronized (lock) {
            ensureOpen();
            if (pos < buf.length)
                return buf[pos++];
            else
                return super.read();
        }
    }

    
Reads characters into a portion of an array.

Params:
  • cbuf –  Destination buffer
  • off –   Offset at which to start writing characters
  • len –   Maximum number of characters to read
Throws:
Returns:    The number of characters read, or -1 if the end of the
            stream has been reached
/**
     * Reads characters into a portion of an array.
     *
     * @param      cbuf  Destination buffer
     * @param      off   Offset at which to start writing characters
     * @param      len   Maximum number of characters to read
     *
     * @return     The number of characters read, or -1 if the end of the
     *             stream has been reached
     *
     * @throws     IOException  If an I/O error occurs
     * @throws     IndexOutOfBoundsException {@inheritDoc}
     */
    public int read(char cbuf[], int off, int len) throws IOException {
        synchronized (lock) {
            ensureOpen();
            try {
                if (len <= 0) {
                    if (len < 0) {
                        throw new IndexOutOfBoundsException();
                    } else if ((off < 0) || (off > cbuf.length)) {
                        throw new IndexOutOfBoundsException();
                    }
                    return 0;
                }
                int avail = buf.length - pos;
                if (avail > 0) {
                    if (len < avail)
                        avail = len;
                    System.arraycopy(buf, pos, cbuf, off, avail);
                    pos += avail;
                    off += avail;
                    len -= avail;
                }
                if (len > 0) {
                    len = super.read(cbuf, off, len);
                    if (len == -1) {
                        return (avail == 0) ? -1 : avail;
                    }
                    return avail + len;
                }
                return avail;
            } catch (ArrayIndexOutOfBoundsException e) {
                throw new IndexOutOfBoundsException();
            }
        }
    }

    
Pushes back a single character by copying it to the front of the pushback buffer. After this method returns, the next character to be read will have the value (char)c. 
Params:
  • c –  The int value representing a character to be pushed back
Throws:
  • IOException –  If the pushback buffer is full,
                     or if some other I/O error occurs
/**
     * Pushes back a single character by copying it to the front of the
     * pushback buffer. After this method returns, the next character to be read
     * will have the value {@code (char)c}.
     *
     * @param  c  The int value representing a character to be pushed back
     *
     * @throws IOException  If the pushback buffer is full,
     *                      or if some other I/O error occurs
     */
    public void unread(int c) throws IOException {
        synchronized (lock) {
            ensureOpen();
            if (pos == 0)
                throw new IOException("Pushback buffer overflow");
            buf[--pos] = (char) c;
        }
    }

    
Pushes back a portion of an array of characters by copying it to the front of the pushback buffer. After this method returns, the next character to be read will have the value cbuf[off], the character after that will have the value cbuf[off+1], and so forth. 
Params:
  • cbuf –  Character array
  • off –   Offset of first character to push back
  • len –   Number of characters to push back
Throws:
  • IOException –  If there is insufficient room in the pushback
                         buffer, or if some other I/O error occurs
/**
     * Pushes back a portion of an array of characters by copying it to the
     * front of the pushback buffer.  After this method returns, the next
     * character to be read will have the value {@code cbuf[off]}, the
     * character after that will have the value {@code cbuf[off+1]}, and
     * so forth.
     *
     * @param      cbuf  Character array
     * @param      off   Offset of first character to push back
     * @param      len   Number of characters to push back
     *
     * @throws     IOException  If there is insufficient room in the pushback
     *                          buffer, or if some other I/O error occurs
     */
    public void unread(char cbuf[], int off, int len) throws IOException {
        synchronized (lock) {
            ensureOpen();
            if (len > pos)
                throw new IOException("Pushback buffer overflow");
            pos -= len;
            System.arraycopy(cbuf, off, buf, pos, len);
        }
    }

    
Pushes back an array of characters by copying it to the front of the pushback buffer. After this method returns, the next character to be read will have the value cbuf[0], the character after that will have the value cbuf[1], and so forth. 
Params:
  • cbuf –  Character array to push back
Throws:
  • IOException –  If there is insufficient room in the pushback
                         buffer, or if some other I/O error occurs
/**
     * Pushes back an array of characters by copying it to the front of the
     * pushback buffer.  After this method returns, the next character to be
     * read will have the value {@code cbuf[0]}, the character after that
     * will have the value {@code cbuf[1]}, and so forth.
     *
     * @param      cbuf  Character array to push back
     *
     * @throws     IOException  If there is insufficient room in the pushback
     *                          buffer, or if some other I/O error occurs
     */
    public void unread(char cbuf[]) throws IOException {
        unread(cbuf, 0, cbuf.length);
    }

    
Tells whether this stream is ready to be read.

Throws:
  • IOException –  If an I/O error occurs
/**
     * Tells whether this stream is ready to be read.
     *
     * @throws     IOException  If an I/O error occurs
     */
    public boolean ready() throws IOException {
        synchronized (lock) {
            ensureOpen();
            return (pos < buf.length) || super.ready();
        }
    }

    
Marks the present position in the stream. The mark for class PushbackReader always throws an exception. 
Throws:
/**
     * Marks the present position in the stream. The {@code mark}
     * for class {@code PushbackReader} always throws an exception.
     *
     * @throws     IOException  Always, since mark is not supported
     */
    public void mark(int readAheadLimit) throws IOException {
        throw new IOException("mark/reset not supported");
    }

    
Resets the stream. The reset method of PushbackReader always throws an exception. 
Throws:
/**
     * Resets the stream. The {@code reset} method of
     * {@code PushbackReader} always throws an exception.
     *
     * @throws     IOException  Always, since reset is not supported
     */
    public void reset() throws IOException {
        throw new IOException("mark/reset not supported");
    }

    
Tells whether this stream supports the mark() operation, which it does
not.

/**
     * Tells whether this stream supports the mark() operation, which it does
     * not.
     */
    public boolean markSupported() {
        return false;
    }

    
Closes the stream and releases any system resources associated with
it. Once the stream has been closed, further read(),
unread(), ready(), or skip() invocations will throw an IOException.
Closing a previously closed stream has no effect. This method will block
while there is another thread blocking on the reader.

Throws:
  • IOException –  If an I/O error occurs
/**
     * Closes the stream and releases any system resources associated with
     * it. Once the stream has been closed, further read(),
     * unread(), ready(), or skip() invocations will throw an IOException.
     * Closing a previously closed stream has no effect. This method will block
     * while there is another thread blocking on the reader.
     *
     * @throws     IOException  If an I/O error occurs
     */
    public void close() throws IOException {
        synchronized (lock) {
            super.close();
            buf = null;
        }
    }

    
Skips characters.  This method will block until some characters are
available, an I/O error occurs, or the end of the stream is reached.

Params:
  • n –  The number of characters to skip
Throws:
Returns:   The number of characters actually skipped
/**
     * Skips characters.  This method will block until some characters are
     * available, an I/O error occurs, or the end of the stream is reached.
     *
     * @param     n  The number of characters to skip
     *
     * @return    The number of characters actually skipped
     *
     * @throws    IllegalArgumentException  If {@code n} is negative.
     * @throws    IOException  If an I/O error occurs
     */
    public long skip(long n) throws IOException {
        if (n < 0L)
            throw new IllegalArgumentException("skip value is negative");
        synchronized (lock) {
            ensureOpen();
            int avail = buf.length - pos;
            if (avail > 0) {
                if (n <= avail) {
                    pos += n;
                    return n;
                } else {
                    pos = buf.length;
                    n -= avail;
                }
            }
            return avail + super.skip(n);
        }
    }
}