org.at4j.support.io
Interface BitOutput

All Superinterfaces:
Closeable
All Known Implementing Classes:
LittleEndianBitOutputStream

public interface BitOutput
extends Closeable

This interface identifies a sink for bits.

The sink 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 OutputStream it can be used as an output stream. This interface redefines OutputStream's write methods with the extra condition that they may only be used if the current position of the sink is at a byte boundary. The writeBytes(byte[], int, int) method does not have that limitation.

Since:
1.1
Author:
Karl Gustafsson
See Also:
OutputStream, BitInput

Method Summary
 int getNumberOfBitsInUnfinishedByte()
          Get the number of bits that have been written to the last byte.
 int getUnfinishedByte()
          Get the value of the unfinished byte.
 void padToByteBoundary()
          Pad the output with zeroes to the next byte boundary.
 void write(byte[] barr)
          See OutputStream.write(byte[]).
 void write(byte[] barr, int off, int len)
          See OutputStream.write(byte[], int, int).
 void write(int b)
          See OutputStream.write(int).
 void writeBit(boolean val)
          Write a single bit.
 void writeBits(int val, int no)
          Write up to eight bits.
 void writeBitsLittleEndian(int val, int no)
          Write up to 32 bits.
 void writeBytes(byte[] barr, int off, int len)
          Write an array of bytes to the output.
 
Methods inherited from interface java.io.Closeable
close
 

Method Detail

padToByteBoundary

void padToByteBoundary()
                       throws IOException
Pad the output with zeroes 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.

getUnfinishedByte

int getUnfinishedByte()
Get the value of the unfinished byte. The value is shifted so that the least significant bit positions are used. getNumberOfBitsInUnfinishedByte() returns how many bit positions that are used.

If the current position is at a byte boundary, 0 is returned.

Returns:
The value of the unfinished byte.

getNumberOfBitsInUnfinishedByte

int getNumberOfBitsInUnfinishedByte()
Get the number of bits that have been written to the last byte.

If the current position is at a byte boundary, 0 is returned.

Returns:
The number of bits that have been written to the last byte. This is a number between 0 and 7 (inclusive).

writeBit

void writeBit(boolean val)
              throws IOException
Write a single bit.

Parameters:
val - The bit (true == 1, false == 0).
Throws:
IOException - On I/O errors.

writeBits

void writeBits(int val,
               int no)
               throws IndexOutOfBoundsException,
                      IOException
Write up to eight bits.

Parameters:
val - The value to write. The bits written are the no rightmost bits of val. It is not verified that val fits within its no rightmost bits. If it does not, the written value is simply truncated.
no - The number of bits to write. This must be between 0 and 8 (inclusive).
Throws:
IndexOutOfBoundsException - If no is less than 0 or greater than 8.
IOException - On I/O errors
See Also:
writeBitsLittleEndian(int, int)

writeBitsLittleEndian

void writeBitsLittleEndian(int val,
                           int no)
                           throws IndexOutOfBoundsException,
                                  IOException
Write up to 32 bits. The bits are written little endian with the most significant bit first.

Parameters:
val - The value to write. The bits written are the no rightmost bits of val. It is not verified that val fits within its no rightmost bits. If it does not, the written value is simply truncated.
no - The number of bits to write. This must be between 0 and 32 (inclusive)
Throws:
IndexOutOfBoundsException - If no is less than 0 or more than 32.
IOException - On I/O errors.
See Also:
writeBits(int, int)

writeBytes

void writeBytes(byte[] barr,
                int off,
                int len)
                throws IndexOutOfBoundsException,
                       IOException
Write an array of bytes to the output. Unlike write(byte[], int, int), this method does not require that the current position is at a byte boundary.

Parameters:
barr - The bytes to write.
off - The offset in the byte array.
len - The number of bytes to write.
Throws:
IndexOutOfBoundsException - If the offset or the length is negative or if the offset + length is larger than the byte array.
IOException - On I/O errors
See Also:
write(byte[], int, int)

write

void write(int b)
           throws IOException
See OutputStream.write(int).

This method requires that the current position of the output is at a byte boundary.

Parameters:
b - The byte to write (0 - 255).
Throws:
IOException - On I/O errors or if the current position is not at a byte boundary.
See Also:
OutputStream.write(int)

write

void write(byte[] barr)
           throws IOException
See OutputStream.write(byte[]).

This method requires that the current position of the output is at a byte boundary.

Parameters:
barr - The bytes to write.
Throws:
IOException - On I/O errors or if the current position is not at a byte boundary.
See Also:
OutputStream.write(byte[])

write

void write(byte[] barr,
           int off,
           int len)
           throws IndexOutOfBoundsException,
                  IOException
See OutputStream.write(byte[], int, int).

This method requires that the current position of the output is at a byte boundary.

Parameters:
barr - The bytes to write.
off - The offset in the byte array.
len - The number of bytes to write.
Throws:
IndexOutOfBoundsException - If the offset or the length is negative or if the offset + length is larger than the byte array.
IOException - On I/O errors or if the current position is not at a byte boundary.
See Also:
OutputStream.write(byte[], int, int), writeBytes(byte[], int, int)