|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectit.unimi.dsi.mg4j.io.InputBitStream
Bit-level input stream.
IMPORTANT: In MG4J 0.6, this class has been completely
rewritten. It is much faster, but there are also incompabilities. Mainly,
unary representations are one-terminated sequences of zeroes (instead of
zero-terminated sequences of ones), and position(long)
sets a
bit, not a byte offset.
This class wraps any InputStream
so that you can treat it as
bit stream. Constructors and methods closely resemble those of
InputStream
. Data can be read from such a stream in several ways:
reading an integer or long in fixed-width, unary, γ, δ, ζ and Golomb
coding, or reading a number of bits that will be stored in a vector of
bytes. There is limited support for mark(int)
/reset()
operations.
This class can also wrap a byte
array; this is much more lightweight than wrapping a FastByteArrayInputStream
wrapping the array. Overflowing the array
will cause an EOFException
.
Note that when reading using a vector of bytes bits are read in the
stream format (see OutputBitStream
): the first bit is bit 7 of the
first byte, the eighth bit is bit 0 of the first byte, the ninth bit is bit
7 of the second byte and so on. When reading integers using some coding,
instead, they are stored in the standard way, that is, in the lower
bits.
Additional features:
java.io
, this class provides a flush()
method that resets the internal state. At this point, you can safely reposition
the underlying stream and read again afterwards. For instance, this is safe
and will perform as expected:
FileInputStream fis = new FileInputStream( ... ); InputBitStream ibs = new InputBitStream( fis ); ... read operations on ibs ... ibs.flush(); fis.getChannel().position( ... ); ... other read operations on ibs ...
As a commodity, 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 input stream, in this
order. If either reference can be successfully fetched, you can use
directly the position()
method with argument
pos
with the same semantics of a flush()
, followed by
a call to position(pos / 8)
(where the latter method belongs
either to the underlying stream or to its underlying file channel), followed
by a skip(pos % 8)
.
UNGET_BUFFER_SIZE
bytes long is allocated to this purpose. The buffer is
cleared on reset()
/flush()
.
InputStream
is met, then zeroes are
subsequently read, and no exception is thrown.
This class is not synchronised. If multiple threads access an instance of this class concurrently, they must be synchronised externally.
OutputBitStream
,
java.io
Field Summary | |
static int |
DEFAULT_BUFFER_SIZE
The default size of the byte buffer in bytes (16Ki). |
static int |
UNGET_BUFFER_SIZE
The size of the unget(boolean) buffer in bytes. |
Constructor Summary | |
protected |
InputBitStream()
This (non-public) constructor exists just to provide fake initialisation. |
|
InputBitStream(byte[] a)
Creates a new input bit stream wrapping a given byte array. |
|
InputBitStream(File file)
Creates a new input bit stream reading from a file. |
|
InputBitStream(File file,
int bufSize)
Creates a new input bit stream reading from a file. |
|
InputBitStream(InputStream is)
Creates a new input bit stream wrapping a given input stream using a buffer of size DEFAULT_BUFFER_SIZE . |
|
InputBitStream(InputStream is,
int bufSize)
Creates a new input bit stream wrapping a given input stream with a specified buffer size. |
|
InputBitStream(String name)
Creates a new input bit stream reading from a file. |
|
InputBitStream(String name,
int bufSize)
Creates a new input bit stream reading from a file. |
Method Summary | |
void |
align()
Aligns the stream. |
long |
available()
Returns the number of bits that can be read (or skipped over) from this bit stream without blocking by the next caller of a method. |
void |
close()
Closes the bit stream. |
void |
flush()
Flushes the bit stream. |
void |
mark(int readLimit)
Marks the current position in this input stream. |
boolean |
markSupported()
Tests if this stream supports the mark(int) and reset() methods. |
boolean |
overflow()
Gets the overflow flag. |
void |
overflow(boolean overflow)
Sets the overflow flag. |
boolean |
pastEOF()
Checks whether we are past EOF. |
void |
position(long position)
Sets this stream bit position, if it is based on a RepositionableStream or on a FileChannel . |
void |
read(byte[] bits,
int len)
Reads a sequence of bits. |
int |
readBit()
Reads a bit. |
long |
readBits()
Returns the number of bits read from this bit stream. |
void |
readBits(long readBits)
Sets the number of bits read from this bit stream. |
int |
readDelta()
Reads a natural number in δ coding. |
int |
readGamma()
Reads a natural number in γ coding. |
int |
readGolomb(int b)
Reads a natural number in Golomb coding. |
int |
readGolomb(int b,
int log2b)
Reads a natural number in Golomb coding. |
int |
readInt(int len)
Reads a fixed number of bits into an integer. |
long |
readLong(int len)
Reads a fixed number of bits into a long. |
long |
readLongDelta()
Reads a long natural number in δ coding. |
long |
readLongGamma()
Reads a long natural number in γ coding. |
long |
readLongGolomb(long b)
Reads a long natural number in Golomb coding. |
long |
readLongGolomb(long b,
int log2b)
Reads a long natural number in Golomb coding. |
long |
readLongMinimalBinary(long b)
Reads a long natural number in a limited range using a minimal binary coding. |
long |
readLongMinimalBinary(long b,
int log2b)
Reads a long natural number in a limited range using a minimal binary coding. |
long |
readLongNibble()
Reads a long natural number in variable-length nibble coding. |
long |
readLongSkewedGolomb(long b)
Reads a long natural number in skewed Golomb coding. |
long |
readLongUnary()
Reads a long natural number in unary coding. |
long |
readLongZeta(int k)
Reads a long natural number in ζ coding. |
int |
readMinimalBinary(int b)
Reads a natural number in a limited range using a minimal binary coding. |
int |
readMinimalBinary(int b,
int log2b)
Reads a natural number in a limited range using a minimal binary coding. |
int |
readNibble()
Reads a natural number in variable-length nibble coding. |
int |
readSkewedGolomb(int b)
Reads a natural number in skewed Golomb coding. |
int |
readUnary()
Reads a natural number in unary coding. |
int |
readZeta(int k)
Reads a natural number in ζ coding. |
void |
reset()
Repositions this bit stream to the position at the time the mark(int) method was last called. |
long |
skip(long n)
Skips the given number of bits. |
void |
unget(boolean bit)
Deprecated. As of MG4J 0.6, replaced by ungetBit(boolean) . |
void |
unget(int bit)
Deprecated. As of MG4J 0.6, replaced by ungetBit(int) . |
void |
ungetBit(boolean bit)
Ungets a bit. |
void |
ungetBit(int bit)
Ungets a bit. |
void |
ungetInt(int x,
int len)
Ungets an integer. |
void |
ungetLong(long x,
int len)
Ungets a long. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final int UNGET_BUFFER_SIZE
unget(boolean)
buffer in bytes.
public static final int DEFAULT_BUFFER_SIZE
Constructor Detail |
protected InputBitStream()
public InputBitStream(InputStream is)
DEFAULT_BUFFER_SIZE
.
is
- the input stream to wrap.public InputBitStream(InputStream is, int bufSize)
is
- the input stream to wrap.bufSize
- the size in byte of the buffer; it may be 0, denoting no buffering.public InputBitStream(byte[] a)
a
- the byte array to wrap.public InputBitStream(String name, int bufSize) throws FileNotFoundException
name
- the name of the file.bufSize
- the size in byte of the buffer; it may be 0, denoting no buffering.public InputBitStream(String name) throws FileNotFoundException
name
- the name of the file.public InputBitStream(File file) throws FileNotFoundException
file
- the file.public InputBitStream(File file, int bufSize) throws FileNotFoundException
file
- the file.bufSize
- the size in byte of the buffer; it may be 0, denoting no buffering.Method Detail |
public void flush()
This method is provided so that users of this class can easily wrap repositionable
streams (for instance, file-based streams, which can be repositioned using
the underlying FileChannel
). It is guaranteed that after calling
this method the underlying stream can be repositioned, and that the next read
will draw data from the stream.
public void close() throws IOException
IOException
public void overflow(boolean overflow)
If this flag is true, then after the end of the underlying InputStream
we will continue returning zeroes (in particular, no
exception will be thrown).
overflow
- the new value of the flag.pastEOF()
public long available() throws IOException
IOException
public boolean overflow()
overflow(boolean)
public boolean pastEOF()
true
if we are reading zeroes past the EOF.overflow(boolean)
public long readBits()
Note that ungetting bits
from this stream
will result in the number of read bits to be decreased.
public void readBits(long readBits)
This method is provided so that, for instance, the
user can reset via readBits(0)
the read-bits count
after a flush()
.
readBits
- the new value for the number of bits read so far.public void align() throws IOException
IOException
public void ungetBit(boolean bit) throws IOException
bit
- a bit.
IOException
public void unget(boolean bit) throws IOException
MG4J
0.6, replaced by ungetBit(boolean)
.
bit
- a bit.
IOException
public void ungetBit(int bit) throws IOException
bit
- a bit.
IOException
unget(boolean)
public void unget(int bit) throws IOException
MG4J
0.6, replaced by ungetBit(int)
.
bit
- a bit.
IOException
public void ungetLong(long x, int len) throws IOException
len
-1
of x
will be the next one to be read from the stream.
x
- a long.len
- the number of (lower) bits to unget from x
.
IOException
public void ungetInt(int x, int len) throws IOException
len
-1
of x
will be the next one to be read from the stream.
x
- an integer.len
- the number of (lower) bits to unget from x
.
IOException
public void read(byte[] bits, int len) throws IOException
bits
- an array of bytes to store the result.len
- the number of bits to read.
IOException
public int readBit() throws IOException
IOException
public int readInt(int len) throws IOException
len
- a bit length.
len
bits are taken from the stream; the rest is zeroed.
IOException
public long readLong(int len) throws IOException
len
- a bit length.
len
bits are taken from the stream; the rest is zeroed.
IOException
public long skip(long n) throws IOException
n
- the number of bits to skip.
IOException
public void position(long position) throws IOException
RepositionableStream
or on a FileChannel
.
Given an underlying stream that implements RepositionableStream
or that can provide a FileChannel
via the getChannel()
method,
a call to this method has the same semantics of a flush()
,
followed by a call to position(position / 8)
on
the byte stream, followed by a skip(position % 8)
.
position
- the new position expressed as a bit offset.
UnsupportedOperationException
- if the underlying byte stream does not implement
RepositionableStream
and if the channel it returns is not a FileChannel
.
IOException
FileChannel.position(long)
public boolean markSupported()
mark(int)
and reset()
methods.
This method will just delegate the test to the underlying InputStream
.
mark(int)
/reset()
.public void mark(int readLimit) throws IOException
reset()
method repositions this stream at the last marked position so
that subsequent reads re-read the same bits.
This method will just delegate the mark to the underlying InputStream
.
Moreover, it will throw an exception if you try to mark outsite byte boundaries.
readLimit
- the maximum limit of bytes that can be read before the mark position becomes invalid.
IOException
- if you try to mark outside byte boundaries.public void reset() throws IOException
mark(int)
method was last called.
This method will just flush the stream
and delegate
the reset to the underlying InputStream
.
IOException
public int readUnary() throws IOException
IOException
public long readLongUnary() throws IOException
IOException
public int readGamma() throws IOException
IOException
public long readLongGamma() throws IOException
IOException
public int readDelta() throws IOException
IOException
public long readLongDelta() throws IOException
IOException
public int readMinimalBinary(int b) throws IOException
b
- a strict upper bound.
IllegalArgumentException
- if you try to read a negative number or use a nonpositive base.
IOException
public int readMinimalBinary(int b, int log2b) throws IOException
readMinimalBinary(int)
because it does not
have to compute log2b
.
b
- a strict upper bound.log2b
- the floor of the base-2 logarithm of the bound.
IllegalArgumentException
- if you try to read a negative number or use a nonpositive base.
IOException
public long readLongMinimalBinary(long b) throws IOException
b
- a strict upper bound.
IllegalArgumentException
- if you try to read a negative number or use a nonpositive base.
IOException
public long readLongMinimalBinary(long b, int log2b) throws IOException
readLongMinimalBinary(long)
because it does not
have to compute log2b
.
b
- a strict upper bound.log2b
- the floor of the base-2 logarithm of the bound.
IllegalArgumentException
- if you try to read a negative number or use a nonpositive base.
IOException
public int readGolomb(int b) throws IOException
This method implements also the case in which b
is 0: in this case,
nothing will be read, and 0 will be returned.
b
- the modulus for the coding.
IllegalArgumentException
- if you use a nonpositive modulus.
IOException
public int readGolomb(int b, int log2b) throws IOException
readGolomb(int)
because it does not
have to compute log2b
.
This method implements also the case in which b
is 0: in this case,
nothing will be read, and 0 will be returned.
b
- the modulus for the coding.log2b
- the floor of the base-2 logarithm of the coding modulus.
IllegalArgumentException
- if you use a nonpositive modulus.
IOException
public long readLongGolomb(long b) throws IOException
This method implements also the case in which b
is 0: in this case,
nothing will be read, and 0 will be returned.
b
- the modulus for the coding.
IllegalArgumentException
- if you use a nonpositive modulus.
IOException
public long readLongGolomb(long b, int log2b) throws IOException
readLongGolomb(long)
because it does not
have to compute log2b
.
This method implements also the case in which b
is 0: in this case,
nothing will be read, and 0 will be returned.
b
- the modulus for the coding.log2b
- the floor of the base-2 logarithm of the coding modulus.
IllegalArgumentException
- if you use a nonpositive modulus.
IOException
public int readSkewedGolomb(int b) throws IOException
This method implements also the case in which b
is 0: in this case,
nothing will be read, and 0 will be returned.
b
- the modulus for the coding.
IllegalArgumentException
- if you use a negative modulus.
IOException
public long readLongSkewedGolomb(long b) throws IOException
This method implements also the case in which b
is 0: in this case,
nothing will be read, and 0 will be returned.
b
- the modulus for the coding.
IllegalArgumentException
- if you use a negative modulus.
IOException
public int readZeta(int k) throws IOException
k
- the shrinking factor.
IllegalArgumentException
- if you use a nonpositive shrinking factor.
IOException
public long readLongZeta(int k) throws IOException
k
- the shrinking factor.
IllegalArgumentException
- if you use a nonpositive shrinking factor.
IOException
public int readNibble() throws IOException
IOException
public long readLongNibble() throws IOException
IOException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |