com.jogamp.common.util

## Class Bitstream<T>

- java.lang.Object
- - com.jogamp.common.util.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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Bitstream.ByteArrayStream` Specific `byte stream`.
    `static class` | `Bitstream.ByteBufferStream` Specific `byte stream`.
    `static class` | `Bitstream.ByteInputStream` Specific `byte stream`.
    `static class` | `Bitstream.ByteOutputStream` Specific `byte stream`.
    `static interface` | `Bitstream.ByteStream<T>` General byte stream.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `EOS` End of stream marker, -1 or 0xFFFFFFFF

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Bitstream(Bitstream.ByteStream<T> stream, boolean outputMode)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `canInput()` Return true if stream can handle input, i.e.
    `boolean` | `canOutput()` Return true if stream can handle output, i.e.
    `static void` | `checkBounds(byte[] sb, int offset, int remaining)`
    `void` | `close()` Closing the underlying stream, implies `flush()`.
    `int` | `flush()` Synchronizes all underlying `output stream` operations, or do nothing.
    `int` | `getBitBuffer()` Returns the current bit buffer.
    `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).
    `int` | `getBitPosition()` Return the next bit number to be read or write counting from [0..7].
    `int` | `getLastBitPos()` Return the last bit number read or written counting from [0..7].
    `Bitstream.ByteStream<T>` | `getStream()` Returns the currently used `Bitstream.ByteStream`.
    `T` | `getSubStream()` Returns the currently used `Bitstream.ByteStream`'s `Bitstream.ByteStream.getStream()`.
    `boolean` | `getThrowIOExceptionOnEOF()` Returns true if I/O methods throw an `IOException` if `EOS` appears, otherwise false (default).
    `void` | `mark(int readLimit)` Set markpos to current position, allowing the stream to be `reset()`.
    `long` | `position()` Returns the bit position in the stream.
    `int` | `readBit(boolean msbFirst)`
    `int` | `readBits31(boolean msbFirst, int n)` Return incoming bits as read via `readBit(boolean)`.
    `int` | `readUInt16(boolean msbFirst, boolean bigEndian)` Return incoming `uint16_t` as read via `readBits31(boolean, int)` and swap bytes if !bigEndian.
    `static int` | `readUInt16(boolean bigEndian, byte[] bytes, int offset)` Return incoming `uint16_t` value and swap bytes if !bigEndian.
    `long` | `readUInt32(boolean msbFirst, boolean bigEndian)` Return incoming `uint32_t` as read via `readBits31(boolean, int)` and swap bytes if !bigEndian.
    `static long` | `readUInt32(boolean bigEndian, byte[] bytes, int offset)` Return incoming `uint32_t` and swap bytes if !bigEndian.
    `int` | `readUInt8(boolean msbFirst)` Return incoming `uint8_t` as read via `readBits31(boolean, int)`.
    `void` | `reset()` Reset stream position to markpos as set via `mark(int)`.
    `void` | `setStream(T stream, boolean outputMode)` Sets the underlying stream, without `close()`ing the previous one.
    `void` | `setThrowIOExceptionOnEOF(boolean enable)` Enables or disables throwing an `IOException` in case `EOS` appears.
    `long` | `skip(long n)` It is implementation dependent, whether backward skip giving a negative number is supported or not.
    `static String` | `toBinString(int v, int bitCount)`
    `static String` | `toHexBinString(int v, int bitCount)`
    `String` | `toString()`
    `protected String` | `toStringImpl()`
    `static int` | `toUInt32Int(int int32)` Returns the reinterpreted given `int32_t` value as `uint32_t` if ≤ `Integer.MAX_VALUE` as within an `int` storage.
    `static long` | `toUInt32Long(int int32)` Reinterpret the given `int32_t` value as `uint32_t`, i.e.
    `static int` | `uint32LongToInt(long uint32)` Returns the given `uint32_t` value `long` value as `int` if ≤ `Integer.MAX_VALUE`.
    `int` | `writeBit(boolean msbFirst, int bit)`
    `int` | `writeBits31(boolean msbFirst, int n, int bits)` Write the given bits via `writeBit(boolean, int)`.
    `int` | `writeInt16(boolean msbFirst, boolean bigEndian, short int16)` Write the given 16 bits via `writeBits31(boolean, int, int)`, while swapping bytes if !bigEndian beforehand.
    `int` | `writeInt32(boolean msbFirst, boolean bigEndian, int int32)` Write the given 32 bits via `writeBits31(boolean, int, int)`, while swapping bytes if !bigEndian beforehand.
    `int` | `writeInt8(boolean msbFirst, byte int8)` Write the given 8 bits via `writeBits31(boolean, int, int)`.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### EOS

          public static final int EOS

      End of stream marker, -1 or 0xFFFFFFFF
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Bitstream

          public Bitstream(Bitstream.ByteStream<T> stream,
                   boolean outputMode)
                    throws IllegalArgumentException

      Parameters:
        `stream` -
        `outputMode` -
      Throws:
        `IllegalArgumentException` - if requested outputMode doesn't match stream's `canInput()` and `canOutput()`.

  - ### 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).

    - #### setStream

          public final void setStream(T stream,
                       boolean outputMode)
                               throws IllegalArgumentException,
                                      IOException

      Sets the underlying stream, without `close()`ing the previous one.

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

      Throws:
        `IllegalArgumentException` - if requested outputMode doesn't match stream's `canInput()` and `canOutput()`.
        `IOException` - could be caused by `flush()`.

    - #### getStream

          public final Bitstream.ByteStream<T> getStream()

      Returns the currently used `Bitstream.ByteStream`.

    - #### getSubStream

          public final T getSubStream()

      Returns the currently used `Bitstream.ByteStream`'s `Bitstream.ByteStream.getStream()`.

    - #### 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`

    - #### flush

          public final int flush()
                          throws IllegalStateException,
                                 IOException

      Synchronizes all underlying `output stream` operations, or do nothing.

      Method also flushes incomplete bytes to the underlying `Bitstream.ByteStream` and hence skips to the next byte position.

      Returns:
        `EOS` caused by writing, otherwise zero.
      Throws:
        `IllegalStateException` - if not in output mode or stream closed
        `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` -
      Throws:
        `IllegalStateException` - if not in input mode or stream closed

    - #### reset

          public final void reset()
                           throws IllegalStateException,
                                  IOException

      Reset stream position to markpos as set via `mark(int)`.

      markpos is kept, hence `reset()` can be called multiple times.

      Throws:
        `IllegalStateException` - if not in input mode or stream closed
        `IllegalStateException` - if markpos has not been set via `mark(int)` or reset operation failed.
        `IOException` - if reset operation failed.

    - #### 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.

    - #### readBit

          public final int readBit(boolean msbFirst)
                            throws IllegalStateException,
                                   IOException

      Parameters:
        `msbFirst` - if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
      Returns:
        the read bit or `EOS` if end-of-stream is reached.
      Throws:
        `IOException`
        `IllegalStateException` - if not in input mode or stream closed

    - #### 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

    - #### skip

          public long skip(long n)
                    throws IllegalStateException,
                           IOException

      It is implementation dependent, whether backward skip giving a negative number is supported or not.
      Parameters:
        `n` - number of bits to skip
      Returns:
        actual skipped bits
      Throws:
        `IOException`
        `IllegalStateException` - if closed

    - #### readBits31

          public int readBits31(boolean msbFirst,
                       int n)
                         throws IllegalArgumentException,
                                IOException

      Return incoming bits as read via `readBit(boolean)`.

      The incoming bits are stored in MSB-first order, i.e. first on highest position and last bit on lowest position. Hence reading w/ lsbFirst, the bit order will be reversed!

      Parameters:
        `msbFirst` - if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
        `n` - number of bits, maximum 31 bits
      Returns:
        the read bits from 0-n in the given order or `EOS`.
      Throws:
        `IllegalStateException` - if not in input mode or stream closed
        `IllegalArgumentException` - if n > 31
        `IOException`

    - #### writeBits31

          public int writeBits31(boolean msbFirst,
                        int n,
                        int bits)
                          throws IllegalStateException,
                                 IllegalArgumentException,
                                 IOException

      Write the given bits via `writeBit(boolean, int)`.

      The given bits are scanned from LSB-first order. Hence reading w/ msbFirst, the bit order will be reversed!

      Parameters:
        `msbFirst` - if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
        `n` - number of bits, maximum 31 bits
        `bits` - the bits to write
      Returns:
        the written bits or `EOS`.
      Throws:
        `IllegalStateException` - if not in output mode or stream closed
        `IllegalArgumentException` - if n > 31
        `IOException`

    - #### readUInt8

          public final int readUInt8(boolean msbFirst)
                              throws IllegalStateException,
                                     IOException

      Return incoming `uint8_t` as read via `readBits31(boolean, int)`.

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

      Parameters:
        `msbFirst` - if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
      Returns:
        `EOS` or the 8bit unsigned value within the lower bits.
      Throws:
        `IllegalStateException` - if not in input mode or stream closed
        `IOException`

    - #### writeInt8

          public final int writeInt8(boolean msbFirst,
                      byte int8)
                              throws IllegalStateException,
                                     IOException

      Write the given 8 bits via `writeBits31(boolean, int, int)`.
      Parameters:
        `msbFirst` - if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
      Returns:
        `EOS` or the written 8bit value.
      Throws:
        `IllegalStateException` - if not in output mode or stream closed
        `IOException`

    - #### readUInt16

          public final int readUInt16(boolean msbFirst,
                       boolean bigEndian)
                               throws IllegalStateException,
                                      IOException

      Return incoming `uint16_t` as read via `readBits31(boolean, int)` and swap bytes if !bigEndian.

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

      Parameters:
        `msbFirst` - if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
        `bigEndian` - if false, swap incoming bytes to little-endian, otherwise leave them as big-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 if !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 msbFirst,
                       boolean bigEndian,
                       short int16)
                               throws IllegalStateException,
                                      IOException

      Write the given 16 bits via `writeBits31(boolean, int, int)`, while swapping bytes if !bigEndian beforehand.
      Parameters:
        `msbFirst` - if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
        `bigEndian` - if false, swap given bytes to little-endian, otherwise leave them as big-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 msbFirst,
                        boolean bigEndian)
                                throws IllegalStateException,
                                       IOException

      Return incoming `uint32_t` as read via `readBits31(boolean, int)` and swap bytes if !bigEndian.

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

      Parameters:
        `msbFirst` - if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
        `bigEndian` - if false, swap incoming bytes to little-endian, otherwise leave them as big-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 if !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 msbFirst,
                       boolean bigEndian,
                       int int32)
                               throws IllegalStateException,
                                      IOException

      Write the given 32 bits via `writeBits31(boolean, int, int)`, while swapping bytes if !bigEndian beforehand.
      Parameters:
        `msbFirst` - if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
        `bigEndian` - if false, 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.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### toStringImpl

          protected String toStringImpl()

    - #### toBinString

          public static String toBinString(int v,
                           int bitCount)

    - #### toHexBinString

          public static String toHexBinString(int v,
                              int bitCount)

    - #### checkBounds

          public static void checkBounds(byte[] sb,
                         int offset,
                         int remaining)
                                  throws IndexOutOfBoundsException

      Throws:
        `IndexOutOfBoundsException`