Java Doc for FastBufferedInputStream.java in  » Development » FastUtil » it » unimi » dsi » fastutil » io » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 java.io.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 MeasurableInputStream interfaces. An instance of this class will try to cast the underlying byte stream to a RepositionableStream and to fetch by reflection the java.nio.channels.FileChannel underlying the given output stream, in this order. If either reference can be successfully fetched, you can use FastBufferedInputStream.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 MeasurableInputStream , and if this operation is successful, or if a java.nio.channels.FileChannel can be detected, then FastBufferedInputStream.position() and FastBufferedInputStream.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 implemented MeasurableInputStream.position independently of underlying input stream.

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

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.

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

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

This method will refill the internal buffer. true if there are no characters in the internal buffer andthe underlying reader is exhausted.

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 . 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 LineTerminator.CR and 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 FastBufferedInputStream.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 = 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.
Parameters:
  off - the first byte to use in array.
Parameters:
  len - the maximum number of bytes to read.
Parameters:
  terminators - a set containing the line termination sequences that we wantto consider as valid. 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.

As explained in the , 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) .
Parameters:
  n - the number of bytes to skip. the number of bytes actually skipped; it can be smaller than nonly if the end of file has been reached.
See Also:   InputStream.skip(long)