com.aliasi.io
Class BitInput

java.lang.Object
  extended by com.aliasi.io.BitInput

public class BitInput
extends Object

A BitInput wraps an underlying input stream to provide bit-level input. Input is read through the method readBit(), which returns a boolean value. Bits are coded as booleans, with true=1 and false=0.

Since:
2.1.1
Version:
2.1.1
Author:
Bob Carpenter

Constructor Summary
BitInput(InputStream in)
          Constructs a bit input wrapping the specified input stream.
 
Method Summary
 long available()
          Returns number of bits available for reading without blocking.
 void close()
          Closes this input stream and releases associated resources.
 boolean endOfStream()
          Returns true if all of the available bits have been read or if this stream has been closed.
 long readBinary(int numBits)
          Reads the next value from the input using a fixed-length binary code of the specified number of bits.
 boolean readBit()
          Reads the next bit from the input stream.
 long readDelta()
          Reads the next value from the input using an Elias delta code.
 long readFibonacci()
          Reads the next value from the input using a Fibonacci code.
 long readGamma()
          Reads the next value from the input using an Elias gamma code.
 long readRice(int numFixedBits)
          Reads the next number from the input using a Rice coding with the specified number of fixed bits for the remainder.
 int readUnary()
          Reads the next value from the input using a unary code.
 long skip(long numBits)
          Skips and discards the specified number of bits in the input.
 void skipDelta()
          Skips over and discards the next value from the input using an Elias delta code.
 void skipFibonacci()
          Skips over and discards the next value from the input using a Fibonacci code.
 void skipGamma()
          Skips over and discards the next value from the input using an Elias gamma code.
 void skipRice(int numFixedBits)
          Skips over and discards the next value from the input using a Rice code with the specified number of fixed bits.
 void skipUnary()
          Skips over and discards the next value from the input using a unary code.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BitInput

public BitInput(InputStream in)
         throws IOException
Constructs a bit input wrapping the specified input stream. The input stream is accessed by the constructor to fill a read-ahead buffer. Thus the constructor will throw an exception if there is a read exception

Parameters:
in - Input stream backing this bit input.
Throws:
IOException - If there is an exception reading from the specified input stream.
Method Detail

available

public long available()
               throws IOException
Returns number of bits available for reading without blocking. This is the sum of the number of bits buffered and the result of querying the number of bytes available from the underlying input stream using InputStream.available().

Returns:
Number of bits available for reading.
Throws:
IOException - If there is an exception while checking availability in the underlying input stream.

close

public void close()
           throws IOException
Closes this input stream and releases associated resources. This method will close the underlying input stream for this bit input by calling InputStream.close(). After calls to this method, available() will return zero and endOfStream() will return true.

Throws:
IOException - If there is an exception closing the underlying input stream.

endOfStream

public boolean endOfStream()
Returns true if all of the available bits have been read or if this stream has been closed.

Returns:
true if all of the available bits have been read.

skip

public long skip(long numBits)
          throws IOException
Skips and discards the specified number of bits in the input. The return value is the number of bits skipped, which may be less than the number requested if the end-of-stream is reached or if the underlying input stream cannot skip the required number of bytes.

Parameters:
numBits - Number of bits to skip.
Returns:
Number of bits actually skipped.
Throws:
IOException - If there is an I/O error skipping on the underlying input stream.
IllegalArgumentException - If the number of bits argument is less than zero.

readBit

public boolean readBit()
                throws IOException
Reads the next bit from the input stream. Bits are encoded as binary values, using true for 1 and false for 0.

The return value is undefined if the end of stream has been reached, but this method will not throw an exception.

Returns:
The boolean value of the next bit.
Throws:
IOException - If there is an exception reading from the underlying stream.

readUnary

public int readUnary()
              throws IOException
Reads the next value from the input using a unary code. If all of the remaining bits are zeros, it throws an I/O exception. If the end of stream has been reached, it returns -1.

See BitOutput.writeUnary(int) for a description of unary coding.

Returns:
The next integer read with unary code.
Throws:
IOException - If the remaining bits are all zeros.

skipUnary

public void skipUnary()
               throws IOException
Skips over and discards the next value from the input using a unary code.

Throws:
IOException - If there is a format error in the input stream or an error reading from the underlying stream.

readGamma

public long readGamma()
               throws IOException
Reads the next value from the input using an Elias gamma code. If the code is incomplete or not well-formed, an I/O exception is raised. If the end of stream has been reached, the value returned is -1.

See BitOutput.writeGamma(long) for a description of gamma coding.

Returns:
The next integer read using gamma coding.
Throws:
IOException - If the prefix of the remaining bits is not a valid gamma code or if there is an error reading from the underlying input stream.

skipGamma

public void skipGamma()
               throws IOException
Skips over and discards the next value from the input using an Elias gamma code.

Throws:
IOException - If there is a format error in the input stream or an error reading from the underlying stream.

readDelta

public long readDelta()
               throws IOException
Reads the next value from the input using an Elias delta code. If the code is incomplete or not well-formed, an I/O exception is raised. If the end of stream has been reached, the value returned is -1.

See BitOutput.writeDelta(long) for a description of gamma coding.

Returns:
The next integer read using delta coding.
Throws:
IOException - If the prefix of the remaining bits is not a valid delta code or there is an error reading from the underlying input stream.

skipDelta

public void skipDelta()
               throws IOException
Skips over and discards the next value from the input using an Elias delta code.

Throws:
IOException - If there is a format error in the input stream or an error reading from the underlying stream.

readBinary

public long readBinary(int numBits)
                throws IOException
Reads the next value from the input using a fixed-length binary code of the specified number of bits. This method throws an exception if there are not enough bits remaining in the input. The number of bits must be greater than zero and not more than 63, so that the result will fit into a long integer (note that the negative numbers are not used).

To skip over a binary encoding of a specified number of bits, just call skip(long) on the number of bits.

See BitOutput.writeBinary(long,int) for a definition of binary encoding and examples.

Parameters:
numBits - Number of bits in encoding.
Returns:
The integer read in binary using the specified number of bits.
Throws:
IOException - If there are not enough bits remaining in the input or there is an error reading from the underlying input stream.
IllegalArgumentException - If the number of bits is less than 1 or greater than 63.

readRice

public long readRice(int numFixedBits)
              throws IOException
Reads the next number from the input using a Rice coding with the specified number of fixed bits for the remainder. This method will throw an exception if the number of fixed bits is greater than 63 or less than 1.

Parameters:
numFixedBits - The number of fixed bits in the Rice code.
Returns:
The next number read using a Rice code with the specified number of fixed bits.
Throws:
IOException - If the coding is illegal.
IllegalArgumentException - If the number of fixed bits is less than 1 or greater than 63.

skipRice

public void skipRice(int numFixedBits)
              throws IOException
Skips over and discards the next value from the input using a Rice code with the specified number of fixed bits.

Throws:
IOException - If there is a format error in the input stream or an error reading from the underlying stream.

readFibonacci

public long readFibonacci()
                   throws IOException
Reads the next value from the input using a Fibonacci code. If the code is not legal, this method throws an I/O exception.

See BitOutput.writeFibonacci(long) for more information on Fibonacci codes.

Returns:
The next number read from the input using a Fibonacci code.
Throws:
IOException - If the remaining bits do not contain a pair of consecutive 1 bits or there is an exception reading from the underlying input stream.

skipFibonacci

public void skipFibonacci()
                   throws IOException
Skips over and discards the next value from the input using a Fibonacci code.

Throws:
IOException - If there is a format error in the input stream or an error reading from the underlying stream.