Package it.unimi.dsi.fastutil.io

Class FastBufferedInputStream

java.lang.Object
java.io.InputStream
it.unimi.dsi.fastutil.io.MeasurableInputStream
it.unimi.dsi.fastutil.io.FastBufferedInputStream
All Implemented Interfaces:
MeasurableStream, RepositionableStream, java.io.Closeable, java.lang.AutoCloseable
public class FastBufferedInputStream
extends MeasurableInputStream
implements RepositionableStream
Lightweight, unsynchronized, aligned input stream buffering class with true skipping, measurability, repositionability and line reading support.

This class provides buffering for input streams, but it does so with purposes and an internal logic that are radically different from the ones adopted in BufferedInputStream. The main features follow.

  • There is no support for marking. All methods are unsychronized.

  • As an additional feature, this class implements the RepositionableStream and MeasurableStream interfaces. An instance of this class will try to cast the underlying byte stream to a RepositionableStream and to fetch by reflection the FileChannel underlying the given output stream, in this order. If either reference can be successfully fetched, you can use position(long) to reposition the stream. Much in the same way, an instance of this class will try to cast the the underlying byte stream to a MeasurableStream, and if this operation is successful, or if a FileChannel can be detected, then position() and length() will work as expected.

  • Due to erratic and unpredictable behaviour of InputStream.skip(long), which does not correspond to its specification and which Sun refuses to fix (see bug 6222822; don't be fooled by the “closed, fixed” label), this class peeks at the underlying stream and if it is System.in it uses repeated reads instead of calling InputStream.skip(long) on the underlying stream; moreover, skips and reads are tried alternately, so to guarantee that skipping less bytes than requested can be caused only by reaching the end of file.

  • This class keeps also track of the number of bytes read so far, so to be able to implement MeasurableStream.position() independently of underlying input stream.

  • This class has limited support for “reading a line” (whatever that means) from the underlying input stream. You can choose the set of line terminators that delimit lines.

Warning: Since fastutil 6.0.0, this class detects a implementations of MeasurableStream instead of subclasses MeasurableInputStream (which is deprecated).

Since:
4.4

  • Nested Class Summary

    Nested Classes
    Modifier and Type Class Description
    static class  FastBufferedInputStream.LineTerminator
    An enumeration of the supported line terminators.

  • Field Summary

    Fields
    Modifier and Type Field Description
    static java.util.EnumSet<FastBufferedInputStream.LineTerminator> ALL_TERMINATORS
    A set containing all available line terminators.
    static int DEFAULT_BUFFER_SIZE
    The default size of the internal buffer in bytes (8Ki).

  • Constructor Summary

    Constructors
    Constructor Description
    FastBufferedInputStream​(java.io.InputStream is)
    Creates a new fast buffered input stream by wrapping a given input stream with a buffer of DEFAULT_BUFFER_SIZE bytes.
    FastBufferedInputStream​(java.io.InputStream is, byte[] buffer)
    Creates a new fast buffered input stream by wrapping a given input stream with a given buffer.
    FastBufferedInputStream​(java.io.InputStream is, int bufferSize)
    Creates a new fast buffered input stream by wrapping a given input stream with a given buffer size.

  • Method Summary

    Modifier and Type Method Description
    int available()  
    void close()  
    void flush()
    Resets the internal logic of this fast buffered input stream, clearing the buffer.
    long length()
    Returns the length of the underlying input stream, if it is measurable.
    long position()
    Returns the current stream position.
    void position​(long newPosition)
    Sets the current stream position.
    int read()  
    int read​(byte[] b, int offset, int length)  
    int readLine​(byte[] array)
    Reads a line into the given byte array using all terminators.
    int readLine​(byte[] array, int off, int len)
    Reads a line into the given byte-array fragment using all terminators.
    int readLine​(byte[] array, int off, int len, java.util.EnumSet<FastBufferedInputStream.LineTerminator> terminators)
    Reads a line into the given byte-array fragment.
    int readLine​(byte[] array, java.util.EnumSet<FastBufferedInputStream.LineTerminator> terminators)
    Reads a line into the given byte array.
    void reset()
    Deprecated.
    As of fastutil 5.0.4, replaced by flush().
    long skip​(long n)
    Skips over and discards the given number of bytes of data from this fast buffered input stream.

    Methods inherited from class java.io.InputStream

    mark, markSupported, nullInputStream, read, readAllBytes, readNBytes, readNBytes, skipNBytes, transferTo

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • DEFAULT_BUFFER_SIZE

      public static final int DEFAULT_BUFFER_SIZE
      The default size of the internal buffer in bytes (8Ki).
      See Also:
      Constant Field Values

    • ALL_TERMINATORS

      public static final java.util.EnumSet<FastBufferedInputStream.LineTerminator> ALL_TERMINATORS
      A set containing all available line terminators.

  • Constructor Details

    • FastBufferedInputStream

      public FastBufferedInputStream​(java.io.InputStream is, byte[] buffer)
      Creates a new fast buffered input stream by wrapping a given input stream with a given buffer.
      Parameters:
      is - an input stream to wrap.
      buffer - a buffer of positive length.

    • FastBufferedInputStream

      public FastBufferedInputStream​(java.io.InputStream is, int bufferSize)
      Creates a new fast buffered input stream by wrapping a given input stream with a given buffer size.
      Parameters:
      is - an input stream to wrap.
      bufferSize - the size in bytes of the internal buffer (greater than zero).

    • FastBufferedInputStream

      public FastBufferedInputStream​(java.io.InputStream is)
      Creates a new fast buffered input stream by wrapping a given input stream with a buffer of DEFAULT_BUFFER_SIZE bytes.
      Parameters:
      is - an input stream to wrap.

  • Method Details

    • read

      public int read() throws java.io.IOException
      Specified by:
      read in class java.io.InputStream
      Throws:
      java.io.IOException

    • read

      public int read​(byte[] b, int offset, int length) throws java.io.IOException
      Overrides:
      read in class java.io.InputStream
      Throws:
      java.io.IOException

    • readLine

      public int readLine​(byte[] array) throws java.io.IOException
      Reads a line into the given byte array using all terminators.
      Parameters:
      array - byte array where the next line will be stored.
      Returns:
      the number of bytes actually placed in array, or -1 at end of file.
      Throws:
      java.io.IOException
      See Also:
      readLine(byte[], int, int, EnumSet)

    • readLine

      public int readLine​(byte[] array, java.util.EnumSet<FastBufferedInputStream.LineTerminator> terminators) throws java.io.IOException
      Reads a line into the given byte array.
      Parameters:
      array - byte array where the next line will be stored.
      terminators - a set containing the line termination sequences that we want to consider as valid.
      Returns:
      the number of bytes actually placed in array, or -1 at end of file.
      Throws:
      java.io.IOException
      See Also:
      readLine(byte[], int, int, EnumSet)

    • readLine

      public int readLine​(byte[] array, int off, int len) throws java.io.IOException
      Reads a line into the given byte-array fragment using all terminators.
      Parameters:
      array - byte array where the next line will be stored.
      off - the first byte to use in array.
      len - the maximum number of bytes to read.
      Returns:
      the number of bytes actually placed in array, or -1 at end of file.
      Throws:
      java.io.IOException
      See Also:
      readLine(byte[], int, int, EnumSet)

    • readLine

      public int readLine​(byte[] array, int off, int len, java.util.EnumSet<FastBufferedInputStream.LineTerminator> terminators) throws java.io.IOException
      Reads a line into the given byte-array fragment.

      Reading lines (i.e., characters) out of a byte stream is not always sensible (methods available to that purpose in old versions of Java have been mercilessly deprecated). Nonetheless, in several situations, such as when decoding network protocols or headers known to be ASCII, it is very useful to be able to read a line from a byte stream.

      This method will attempt to read the next line into array starting at off, reading at most len bytes. The read, however, will be stopped by the end of file or when meeting a line terminator. Of course, for this operation to be sensible the encoding of the text contained in the stream, if any, must not generate spurious carriage returns or line feeds. Note that the termination detection uses a maximisation criterion, so if you specify both FastBufferedInputStream.LineTerminator.CR and FastBufferedInputStream.LineTerminator.CR_LF meeting a pair CR/LF will consider the whole pair a terminator.

      Terminators are not copied into array or included in the returned count. The returned integer can be used to check whether the line is complete: if it is smaller than len, then more bytes might be available, but note that this method (contrarily to read(byte[], int, int)) can legitimately return zero when len is nonzero just because a terminator was found as the first character. Thus, the intended usage of this method is to call it on a given array, check whether len bytes have been read, and if so try again (possibly extending the array) until a number of read bytes strictly smaller than len (possibly, -1) is returned.

      If you need to guarantee that a full line is read, use the following idiom: 

       int start = off, len;
 while((len = fbis.readLine(array, start, array.length - start, terminators)) == array.length - start) {
     start += len;
     array = ByteArrays.grow(array, array.length + 1);
 }

      At the end of the loop, the line will be placed in array starting at off (inclusive) and ending at start + Math.max(len, 0) (exclusive).

      Parameters:
      array - byte array where the next line will be stored.
      off - the first byte to use in array.
      len - the maximum number of bytes to read.
      terminators - a set containing the line termination sequences that we want to consider as valid.
      Returns:
      the number of bytes actually placed in array, or -1 at end of file. Note that the returned number will be len if no line termination sequence specified in terminators has been met before scanning len byte, and if also we did not meet the end of file.
      Throws:
      java.io.IOException

    • position

      public void position​(long newPosition) throws java.io.IOException
      Description copied from interface: RepositionableStream
      Sets the current stream position.
      Specified by:
      position in interface RepositionableStream
      Parameters:
      newPosition - the new stream position.
      Throws:
      java.io.IOException

    • position

      public long position() throws java.io.IOException
      Description copied from interface: RepositionableStream
      Returns the current stream position.
      Specified by:
      position in interface MeasurableStream
      Specified by:
      position in interface RepositionableStream
      Returns:
      the current stream position.
      Throws:
      java.io.IOException

    • length

      public long length() throws java.io.IOException
      Returns the length of the underlying input stream, if it is measurable.
      Specified by:
      length in interface MeasurableStream
      Returns:
      the length of the underlying input stream.
      Throws:
      java.lang.UnsupportedOperationException - if the underlying input stream is not measurable and cannot provide a FileChannel.
      java.io.IOException

    • skip

      public long skip​(long n) throws java.io.IOException
      Skips over and discards the given number of bytes of data from this fast buffered input stream.

      As explained in the class documentation, the semantics of InputStream.skip(long) is fatally flawed. This method provides additional semantics as follows: it will skip the provided number of bytes, unless the end of file has been reached.

      Additionally, if the underlying input stream is System.in this method will use repeated reads instead of invoking InputStream.skip(long).

      Overrides:
      skip in class java.io.InputStream
      Parameters:
      n - the number of bytes to skip.
      Returns:
      the number of bytes actually skipped; it can be smaller than n only if the end of file has been reached.
      Throws:
      java.io.IOException
      See Also:
      InputStream.skip(long)

    • available

      public int available() throws java.io.IOException
      Overrides:
      available in class java.io.InputStream
      Throws:
      java.io.IOException

    • close

      public void close() throws java.io.IOException
      Specified by:
      close in interface java.lang.AutoCloseable
      Specified by:
      close in interface java.io.Closeable
      Overrides:
      close in class java.io.InputStream
      Throws:
      java.io.IOException

    • flush

      public void flush()
      Resets the internal logic of this fast buffered input stream, clearing the buffer.

      All buffering information is discarded, and the number of bytes read so far (and thus, also the current position) is adjusted to reflect this fact.

      This method is mainly useful for re-reading files that have been overwritten externally.

    • reset

      @Deprecated public void reset()
      Deprecated.
      As of fastutil 5.0.4, replaced by flush(). The old semantics of this method does not contradict InputStream's contract, as the semantics of reset() is undefined if InputStream.markSupported() returns false. On the other hand, the name was really a poor choice.
      Resets the internal logic of this fast buffered input stream.
      Overrides:
      reset in class java.io.InputStream