Class Bitstream<T>


  • public class Bitstream<T>
    extends Object
    Versatile Bitstream implementation supporting:
    • Utilize I/O operations on I/O streams, buffers and arrays
    • Consider MSBfirst / LSBfirst mode
    • Linear bit R/W operations
    • Bulk R/W operations w/ endian related type conversion
    • Allow mark/reset and switching streams and input/output mode
    • Optimized operations
    • Field Detail

      • EOS

        public static final int EOS
        End of stream marker, -1 or 0xFFFFFFFF
        See Also:
        Constant Field Values
    • Method Detail

      • setThrowIOExceptionOnEOF

        public final void setThrowIOExceptionOnEOF​(boolean enable)
        Enables or disables throwing an IOException in case EOS appears.

        Default behavior for I/O methods is not to throw an IOException, but to return EOS.

      • getThrowIOExceptionOnEOF

        public final boolean getThrowIOExceptionOnEOF()
        Returns true if I/O methods throw an IOException if EOS appears, otherwise false (default).
      • close

        public final void close()
                         throws IOException
        Closing the underlying stream, implies flush().

        Implementation will null the stream references, hence #setStream(Object) must be called before re-using instance.

        If the closed stream was in output mode, flush() is being called.

        Throws:
        IOException
      • canInput

        public final boolean canInput()
        Return true if stream can handle input, i.e. readBit(boolean).
      • canOutput

        public final boolean canOutput()
        Return true if stream can handle output, i.e. writeBit(boolean, int).
      • mark

        public final void mark​(int readLimit)
                        throws IllegalStateException
        Set markpos to current position, allowing the stream to be reset().
        Parameters:
        readlimit - maximum number of bytes able to read before invalidating the markpos.
        Throws:
        IllegalStateException - if not in input mode or stream closed
      • getBitCount

        public final int getBitCount()
        Number of remaining bits in cache to read before next byte-read (input mode) or number of remaining bits to be cached before next byte-write (output mode).

        Counting down from 7..0 7..0, starting with 0.

        In input mode, zero indicates reading a new byte and cont. w/ 7. In output mode, the cached byte is written when flipping over to 0.

      • getLastBitPos

        public final int getLastBitPos()
        Return the last bit number read or written counting from [0..7]. If no bit access has been performed, 7 is returned.

        Returned value is normalized [0..7], i.e. independent from msb or lsb read order.

      • getBitPosition

        public final int getBitPosition()
        Return the next bit number to be read or write counting from [0..7]. If no bit access has been performed, 0 is returned.

        Returned value is normalized [0..7], i.e. independent from msb or lsb read order.

      • getBitBuffer

        public final int getBitBuffer()
        Returns the current bit buffer.
        See Also:
        getBitCount()
      • position

        public final long position()
        Returns the bit position in the stream.
      • writeBit

        public final int writeBit​(boolean msbFirst,
                                  int bit)
                           throws IllegalStateException,
                                  IOException
        Parameters:
        msbFirst - if true outgoing stream bit order is MSB to LSB, otherwise LSB to MSB.
        bit -
        Returns:
        the currently written byte or EOS if end-of-stream is reached.
        Throws:
        IOException
        IllegalStateException - if not in output mode or stream closed
      • readUInt16

        public final int readUInt16​(boolean bigEndian)
                             throws IllegalStateException,
                                    IOException
        Return incoming uint16_t as read via readBits31(int) LSB-first as little-endian, hence bytes are swapped if bigEndian.

        In case of a int16_t 2-complement signed value, simply cast the result to short after checking for EOS.

        Parameters:
        bigEndian - if true, swap incoming bytes to little-endian, otherwise leave them as little-endian.
        Returns:
        EOS or the 16bit unsigned value within the lower bits.
        Throws:
        IllegalStateException - if not in input mode or stream closed
        IOException
      • readUInt16

        public static final int readUInt16​(boolean bigEndian,
                                           byte[] bytes,
                                           int offset)
                                    throws IndexOutOfBoundsException
        Return incoming uint16_t value and swap bytes according to bigEndian.

        In case of a int16_t 2-complement signed value, simply cast the result to short.

        Parameters:
        bigEndian - if false, swap incoming bytes to little-endian, otherwise leave them as big-endian.
        Returns:
        the 16bit unsigned value within the lower bits.
        Throws:
        IndexOutOfBoundsException
      • writeInt16

        public final int writeInt16​(boolean bigEndian,
                                    short int16)
                             throws IllegalStateException,
                                    IOException
        Write the given 16 bits via writeBits31(int, int) LSB-first as little-endian, hence bytes are swapped if bigEndian.
        Parameters:
        bigEndian - if true, swap given bytes to little-endian, otherwise leave them as little-endian.
        Returns:
        EOS or the written 16bit value.
        Throws:
        IllegalStateException - if not in output mode or stream closed
        IOException
      • readUInt32

        public final long readUInt32​(boolean bigEndian)
                              throws IllegalStateException,
                                     IOException
        Return incoming uint32_t as read via readBits31(int) LSB-first as little-endian, hence bytes are swapped if bigEndian.

        In case of a int32_t 2-complement signed value, simply cast the result to int after checking for EOS.

        Parameters:
        bigEndian - if true, swap incoming bytes to little-endian, otherwise leave them as little-endian.
        Returns:
        EOS or the 32bit unsigned value within the lower bits.
        Throws:
        IllegalStateException - if not in input mode or stream closed
        IOException
      • readUInt32

        public static final long readUInt32​(boolean bigEndian,
                                            byte[] bytes,
                                            int offset)
                                     throws IndexOutOfBoundsException
        Return incoming uint32_t and swap bytes according to bigEndian.

        In case of a int32_t 2-complement signed value, simply cast the result to int.

        Parameters:
        bigEndian - if false, swap incoming bytes to little-endian, otherwise leave them as big-endian.
        Returns:
        the 32bit unsigned value within the lower bits.
        Throws:
        IndexOutOfBoundsException
      • writeInt32

        public final int writeInt32​(boolean bigEndian,
                                    int int32)
                             throws IllegalStateException,
                                    IOException
        Write the given 32 bits via writeBits31(int, int) LSB-first as little-endian, hence bytes are swapped if bigEndian.
        Parameters:
        bigEndian - if true, swap given bytes to little-endian, otherwise leave them as little-endian.
        Returns:
        EOS or the written 32bit value.
        Throws:
        IllegalStateException - if not in output mode or stream closed
        IOException
      • toUInt32Long

        public static final long toUInt32Long​(int int32)
        Reinterpret the given int32_t value as uint32_t, i.e. perform the following cast to long:
           final long l = 0xffffffffL & int32;
         
      • toUInt32Int

        public static final int toUInt32Int​(int int32)
        Returns the reinterpreted given int32_t value as uint32_t if ≤ Integer.MAX_VALUE as within an int storage. Otherwise return -1.
      • uint32LongToInt

        public static final int uint32LongToInt​(long uint32)
        Returns the given uint32_t value long value as int if ≤ Integer.MAX_VALUE. Otherwise return -1.
      • toStringImpl

        protected String toStringImpl()
      • toBinString

        public static String toBinString​(boolean msbFirst,
                                         int v,
                                         int bitCount)
      • toHexBinString

        public static String toHexBinString​(boolean msbFirst,
                                            int v,
                                            int bitCount)
      • toHexBinString

        public static final String toHexBinString​(boolean msbFirst,
                                                  byte[] data,
                                                  int offset,
                                                  int len)
      • toHexBinString

        public static final String toHexBinString​(boolean msbFirst,
                                                  ByteBuffer data,
                                                  int offset,
                                                  int len)