org.at4j.support.io
Interface BitInput

All Superinterfaces:
Closeable
All Known Implementing Classes:
LittleEndianBitInputStream

public interface BitInput
extends Closeable

This interface identifies a source for bits.

The source is assumed to have a position which may or may not be at a byte boundary (every eight bits).

If an implementing class also extends InputStream it can be used as an input stream. This interface redefines InputStream 's read methods with the extra condition that they may only be used if the current position of the source is at a byte boundary. The readBytes(byte[], int, int) method does not have that limitation.

Since:
1.1
Author:
Karl Gustafsson
See Also:
InputStream, BitOutput

Method Summary
 int available()
          Get the number of bytes available in the input.
 boolean isAtEof()
          Has the input come to its end? If so, nothing more can be read from it.
 int read()
          Read a single byte from the input.
 int read(byte[] barr)
          Read bytes into the supplied array.
 int read(byte[] barr, int offset, int len)
          Read bytes into the supplied array.
 boolean readBit()
          Read the value of the next bit in the stream.
 int readBits(int no)
          Read up to eight bits from the input.
 int readBitsLittleEndian(int no)
          Read up to 32 bits from the input.
 byte[] readBytes(byte[] barr, int off, int len)
          Read bytes from the input.
 long skip(long n)
          Skip bytes in the input.
 void skipToByteBoundary()
          Move the position to the next byte boundary.
 
Methods inherited from interface java.io.Closeable
close
 

Method Detail

isAtEof

boolean isAtEof()
Has the input come to its end? If so, nothing more can be read from it.

Returns:
true if no more can be read from this input.

skipToByteBoundary

void skipToByteBoundary()
                        throws IOException
Move the position to the next byte boundary. If the current position is already at a byte boundary, this method does nothing.

Throws:
IOException - On I/O errors or if this input is already at the end of the available data.

readBit

boolean readBit()
                throws IOException
Read the value of the next bit in the stream.

Returns:
true if the value is 1, false if it is 0.
Throws:
IOException - On I/O errors or if this input is already at the end of the available data.

readBits

int readBits(int no)
             throws IndexOutOfBoundsException,
                    IOException
Read up to eight bits from the input.

Parameters:
no - The number of bits to read.
Returns:
The bits as the least significant bits of the returned integer. For instance, if 1011 is read, the returned integer will have the value 1 * 8 + 0 * 4 + 1 * 2 + 1 * 1 == 11.
Throws:
IndexOutOfBoundsException - If no is less than 0 or greater than 8.
IOException - On I/O errors or if this input is already at the end of the available data.
See Also:
readBitsLittleEndian(int)

readBitsLittleEndian

int readBitsLittleEndian(int no)
                         throws IndexOutOfBoundsException,
                                IOException
Read up to 32 bits from the input. The first eight bits that is read will be the most significant byte of the returned integer.

Parameters:
no - The number of bits to read.
Returns:
The bits read as the least significant bits of the returned integer. (Just like for readBits(int).
Throws:
IndexOutOfBoundsException - If no is less than 0 or greater than 32.
IOException - On I/O errors or if this input is already at the end of the available data.
See Also:
readBits(int)

readBytes

byte[] readBytes(byte[] barr,
                 int off,
                 int len)
                 throws IndexOutOfBoundsException,
                        IOException
Read bytes from the input. Unlike read(byte[], int, int), this method does not require that the current position is at a byte boundary.

Another difference to read(byte[], int, int) is that this method throws an IOException if it cannot read all requested bytes.

Parameters:
barr - The byte array to read bytes into.
off - The offset in the array to start writing read bytes at.
len - The number of bytes to read.
Returns:
barr.
Throws:
IndexOutOfBoundsException - If the length or the offset is negative or if the sum of the length and the offset is greater than the length of the supplied byte array.
IOException - On I/O errors or if there was not enough bytes to read from the input.
See Also:
read(byte[], int, int)

read

int read()
         throws IOException
Read a single byte from the input. See InputStream.read() .

This method requires that the current position in the input is at a byte boundary.

Returns:
The read byte or -1 if the current position is at the end of the input.
Throws:
IOException - On I/O errors or if the current position is not at a byte boundary.
See Also:
InputStream.read()

read

int read(byte[] barr)
         throws IOException
Read bytes into the supplied array. See InputStream.read(byte[]).

This method requires that the current position in the input is at a byte boundary.

Parameters:
barr - The byte array to read bytes into.
Returns:
The number of bytes read.
Throws:
IOException - On I/O errors or if the current position is not at a byte boundary.
See Also:
InputStream.read(byte[])

read

int read(byte[] barr,
         int offset,
         int len)
         throws IndexOutOfBoundsException,
                IOException
Read bytes into the supplied array. See InputStream.read(byte[], int, int).

This method requires that the current position in the input is at a byte boundary.

Parameters:
barr - The byte array to read bytes into.
offset - The offset position in the array to start write read bytes to.
len - The number of bytes to read.
Returns:
The number of bytes actually read.
Throws:
IndexOutOfBoundsException - If the offset or the length is negative or if the sum of the offset and the length is greater than the length of the supplied byte array.
IOException - On I/O errors or if the current position is not at a byte boundary.

skip

long skip(long n)
          throws IOException
Skip bytes in the input. See InputStream.skip(long).

This method requires that the current position in the input is at a byte boundary.

Parameters:
n - The number of bytes to skip.
Returns:
The number of bytes skipped.
Throws:
IOException - On I/O errors or if the current position is not at a byte boundary.

available

int available()
              throws IOException
Get the number of bytes available in the input. See InputStream.available().

This method requires that the current position in the input is at a byte boundary.

Throws:
IOException - On I/O errors or if the current position is not at a byte boundary.