Package eu.svjatoslav.commons.data

Class BitOutputStream

java.lang.Object
eu.svjatoslav.commons.data.BitOutputStream
public class BitOutputStream extends Object
Writes individual bits to an output stream.

This class provides bit-level writing capabilities, allowing you to write any number of bits to an underlying output stream. Bits are written from most significant to least significant within each byte.

Writing starts from the most significant bit (bit 7) of each byte and proceeds to the least significant bit (bit 0). When a byte is complete (8 bits written), it is flushed to the underlying stream automatically.

Example usage:


 ByteArrayOutputStream output = new ByteArrayOutputStream();
 BitOutputStream bos = new BitOutputStream(output);

 bos.storeBits(0b101, 3);      // Writes 3 bits: 101
 bos.storeBits(0b11110000, 8); // Writes 8 bits: 11110000
 bos.storeBits(0b11, 2);       // Writes 2 bits: 11
 bos.finishByte();             // Flushes partial byte if any

 byte[] result = output.toByteArray();

This class is useful for applications that create bit-packed data formats, such as custom compression algorithms, network protocols, or binary file formats where data is not byte-aligned.

Important: Always call finishByte() when done writing to ensure any partially written byte is flushed to the output stream.

See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    BitOutputStream(OutputStream outputStream)
    Creates a new BitOutputStream that writes bits to the specified output stream.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    finishByte()
    Finishes writing the current incomplete byte to the output stream.
    void
    storeBits(int data, int bitCount)
    Writes the specified number of bits from the data value to the output stream.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • BitOutputStream

      public BitOutputStream(OutputStream outputStream)
      Creates a new BitOutputStream that writes bits to the specified output stream.

      The output stream is not modified until at least 8 bits have been written, or finishByte() is called.

      Parameters:
      outputStream - the underlying output stream to write bytes to. Must not be null.

  • Method Details

    • finishByte

      public void finishByte() throws IOException
      Finishes writing the current incomplete byte to the output stream.

      If less than 8 bits have been written to the current byte, the remaining bits are filled with zeros and the byte is written. If exactly 8 bits have been written (byte already flushed), this method does nothing.

      Important: Always call this method when finished writing to ensure all data is flushed to the output stream. Otherwise, the last partial byte may be lost.

      Throws:
      IOException - if an I/O error occurs while writing to the underlying stream.

    • storeBits

      public void storeBits(int data, int bitCount) throws IOException
      Writes the specified number of bits from the data value to the output stream.

      Bits are taken from the most significant positions of the data value. For example, calling storeBits(0b1011, 3) will write the 3 most significant bits: 101.

      Bits are written from most significant to least significant within each byte. When a byte is completed (8 bits), it is automatically flushed to the underlying stream.

      Writing zero bits does nothing and does not advance the byte pointer.

      Parameters:
      data - the integer value containing the bits to write. Only the specified number of most significant bits are used.
      bitCount - the number of bits to write (0 to 32). Values greater than 32 may produce unexpected results.
      Throws:
      IOException - if an I/O error occurs while writing to the underlying stream.