Summary

Add java.io.InputStream.skipNBytes(long) to skip forward an exact number of bytes.

Problem

The existing method java.io.InputStream.skip(long) does not guarantee that the requested number of bytes will actually be skipped.

Solution

Define a new method java.io.InputStream.skipNBytes(long) which will skip exactly the number of bytes requested or throw an exception.

Specification

Changes to java.io.InputStream.nullInputStream() documentation:

     * {@code readAllBytes()}, {@code readNBytes(byte[], int, int)},
     * {@code readNBytes(int)}, {@code skip(long)}, {@code skipNBytes(long)},

Changes to java.io.InputStream.skip(long) documentation:

     * @return     the actual number of bytes skipped which might be zero.
     * @throws     IOException  if an I/O error occurs.
     * @see        java.io.InputStream#skipNBytes(long)

New method java.io.InputStream.skipNBytes(long):

    /**
     * Skips over and discards exactly {@code n} bytes of data from this input
     * stream.  If {@code n} is zero, then no bytes are skipped.
     * If {@code n} is negative, then no bytes are skipped.
     * Subclasses may handle the negative value differently.
     *
     * <p> This method blocks until the requested number of bytes have been
     * skipped, end of file is reached, or an exception is thrown.
     *
     * <p> If end of stream is reached before the stream is at the desired
     * position, then an {@code EOFException} is thrown.
     *
     * <p> If an I/O error occurs, then the input stream may be
     * in an inconsistent state. It is strongly recommended that the
     * stream be promptly closed if an I/O error occurs.
     *
     * @implNote
     * Subclasses are encouraged to provide a more efficient implementation
     * of this method.
     *
     * @implSpec
     * If {@code n} is zero or negative, then no bytes are skipped.
     * If {@code n} is positive, the default implementation of this method
     * invokes {@link #skip(long) skip()} with parameter {@code n}.  If the
     * return value of {@code skip(n)} is non-negative and less than {@code n},
     * then {@link #read()} is invoked repeatedly until the stream is {@code n}
     * bytes beyond its position when this method was invoked or end of stream
     * is reached.  If the return value of {@code skip(n)} is negative or
     * greater than {@code n}, then an {@code IOException} is thrown.  Any
     * exception thrown by {@code skip()} or {@code read()} will be propagated.
     *
     * @param      n   the number of bytes to be skipped.
     * @throws     EOFException if end of stream is encountered before the
     *             stream can be positioned {@code n} bytes beyond its position
     *             when this method was invoked.
     * @throws     IOException  if the stream cannot be positioned properly or
     *             if an I/O error occurs.
     * @see        java.io.InputStream#skip(long)
     */
    public void skipNBytes(long n) throws IOException {}