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