Versatile Bitstream implementation supporting: More...

Collaboration diagram for org.jau.io.Bitstream< T >:

Classes
class	ByteArrayStream
	Specific `byte stream`. More...

class	ByteBufferStream
	Specific `byte stream`. More...

class	ByteInputStream
	Specific `byte stream`. More...

class	ByteOutputStream
	Specific `byte stream`. More...

interface	ByteStream
	General byte stream. More...

Public Member Functions
	Bitstream (final ByteStream< T > stream, final boolean outputMode) throws IllegalArgumentException

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

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

final void	setStream (final T stream, final boolean outputMode) throws IllegalArgumentException, IOException
	Sets the underlying stream, without `close()`ing the previous one.

final ByteStream< T >	getStream ()
	Returns the currently used `ByteStream`.

final T	getSubStream ()
	Returns the currently used `ByteStream`'s `ByteStream#getStream()`.

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

final int	flush () throws IllegalStateException, IOException
	Synchronizes all underlying `output stream` operations, or do nothing.

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

final boolean	canOutput ()
	Return true if stream can handle output, i.e.

final void	mark (final int readLimit) throws IllegalStateException
	Set `markpos` to current position, allowing the stream to be `reset()`.

final void	reset () throws IllegalStateException, IOException
	Reset stream position to markpos as set via `mark(int)`.

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

final int	getLastBitPos ()
	Return the last bit number read or written counting from [0..7].

final int	getBitPosition ()
	Return the next bit number to be read or write counting from [0..7].

final int	getBitBuffer ()
	Returns the current bit buffer.

final long	position ()
	Returns the bit position in the stream.

final long	position (final long newPosition) throws UnsupportedOperationException, IllegalArgumentException, IllegalStateException, IOException
	Sets this stream's bit position.

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

final int	writeBit (final boolean msbFirst, final int bit) throws IllegalStateException, IOException

long	skip (final long n) throws IllegalStateException, IOException
	It is implementation dependent, whether backward skip giving a negative number is supported or not.

int	readBits31 (final int n) throws IllegalArgumentException, IOException
	Return incoming bits as read via `readBit(boolean)` LSB-first as little-endian.

int	writeBits31 (final int n, final int bits) throws IllegalStateException, IllegalArgumentException, IOException
	Write the given bits via `writeBit(boolean, int)` LSB-first as little-endian.

final int	readUInt8 () throws IllegalStateException, IOException
	Return incoming `uint8_t` as read via `readBits31(int)`.

final int	writeInt8 (final byte int8) throws IllegalStateException, IOException
	Write the given 8 bits via `writeBits31(int, int)`.

final int	readUInt16 (final 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.

final int	writeInt16 (final boolean bigEndian, final 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.

final long	readUInt32 (final 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.

final int	writeInt32 (final boolean bigEndian, final 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.

String	toString ()

Static Public Member Functions
static final int	readUInt16 (final boolean bigEndian, final byte[] bytes, final int offset) throws IndexOutOfBoundsException
	Return incoming `uint16_t` value and swap bytes according to bigEndian.

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

static final long	toUInt32Long (final int int32)
	Reinterpret the given `int32_t` value as `uint32_t`, i.e.

static final int	toUInt32Int (final int int32)
	Returns the reinterpreted given `int32_t` value as `uint32_t` if ≤ `Integer#MAX_VALUE` as within an `int` storage.

static final int	uint32LongToInt (final long uint32)
	Returns the given `uint32_t` value `long` value as `int` if ≤ `Integer#MAX_VALUE`.

static String	toBinString (final boolean msbFirst, final int v, final int bitCount)

static String	toHexBinString (final boolean msbFirst, final int v, final int bitCount)

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

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

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

Static Public Attributes
static final int	EOS = -1
	End of stream marker, {@value} or 0xFFFFFFFF.

Protected Member Functions
String	toStringImpl ()

Detailed Description

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

Definition at line 49 of file Bitstream.java.

Constructor & Destructor Documentation

◆ Bitstream()

org.jau.io.Bitstream< T >.Bitstream	(	final ByteStream< T >	stream,
		final boolean	outputMode ) throws IllegalArgumentException

Parameters

stream
outputMode

Exceptions

IllegalArgumentException if requested outputMode doesn't match stream's canInput() and canOutput().

Definition at line 622 of file Bitstream.java.

Here is the caller graph for this function:

Member Function Documentation

◆ canInput()

final boolean org.jau.io.Bitstream< T >.canInput ( )

Return true if stream can handle input, i.e.

readBit(boolean).

Definition at line 738 of file Bitstream.java.

◆ canOutput()

final boolean org.jau.io.Bitstream< T >.canOutput ( )

Return true if stream can handle output, i.e.

writeBit(boolean, int).

Definition at line 741 of file Bitstream.java.

◆ checkBounds()

static void org.jau.io.Bitstream< T >.checkBounds	(	final byte[]	sb,
		final int	offset,
		final int	remaining ) throws IndexOutOfBoundsException

static

Definition at line 1556 of file Bitstream.java.

Here is the caller graph for this function:

◆ close()

final void org.jau.io.Bitstream< T >.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.

Exceptions

IOException

Definition at line 699 of file Bitstream.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ flush()

final int org.jau.io.Bitstream< T >.flush ( ) throws IllegalStateException, IOException

Synchronizes all underlying output stream operations, or do nothing.

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

Returns: EOS caused by writing, otherwise zero.

Exceptions

IllegalStateException	if not in output mode or stream closed
IOException

Definition at line 718 of file Bitstream.java.

◆ getBitBuffer()

final int org.jau.io.Bitstream< T >.getBitBuffer ( )

Returns the current bit buffer.

See also: getBitCount()

Definition at line 819 of file Bitstream.java.

◆ getBitCount()

final int org.jau.io.Bitstream< T >.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.

Definition at line 789 of file Bitstream.java.

◆ getBitPosition()

final int org.jau.io.Bitstream< T >.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.

Definition at line 807 of file Bitstream.java.

◆ getLastBitPos()

final int org.jau.io.Bitstream< T >.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.

Definition at line 798 of file Bitstream.java.

◆ getStream()

final ByteStream< T > org.jau.io.Bitstream< T >.getStream ( )

Returns the currently used ByteStream.

Definition at line 681 of file Bitstream.java.

◆ getSubStream()

final T org.jau.io.Bitstream< T >.getSubStream ( )

Returns the currently used ByteStream's ByteStream#getStream().

Definition at line 684 of file Bitstream.java.

◆ getThrowIOExceptionOnEOF()

final boolean org.jau.io.Bitstream< T >.getThrowIOExceptionOnEOF ( )

Returns true if I/O methods throw an IOException if EOS appears, otherwise false (default).

Definition at line 659 of file Bitstream.java.

◆ mark()

final void org.jau.io.Bitstream< T >.mark ( final 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.

Exceptions

IllegalStateException if not in input mode or stream closed

Definition at line 748 of file Bitstream.java.

◆ position() [1/2]

final long org.jau.io.Bitstream< T >.position ( )

Returns the bit position in the stream.

Definition at line 824 of file Bitstream.java.

◆ position() [2/2]

final long org.jau.io.Bitstream< T >.position ( final long newPosition ) throws UnsupportedOperationException, IllegalArgumentException, IllegalStateException, IOException

Sets this stream's bit position.

A set mark is cleared.

Returns Bitstream#EOS is end-of-stream is reached, otherwise the new position.

Known supporting implementation is ByteBufferStream and ByteArrayStream.

Parameters

newPosition The new positive position.

Returns: The new set position or Bitstream#EOS if end-of-stream is reached.

Exceptions

UnsupportedOperationException	if not supported, i.e. `ByteInputStream` or `ByteOutputStream`
IllegalArgumentException	If the `newPosition` is negative
IOException	if read error occurs or EOS is reached and `setThrowIOExceptionOnEOF(boolean)` is set to true.
IllegalStateException

Definition at line 859 of file Bitstream.java.

Here is the call graph for this function:

◆ readBit()

final int org.jau.io.Bitstream< T >.readBit ( final boolean msbFirst ) throws UnsupportedOperationException, 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.

Exceptions

IOException
IllegalStateException	if not in input mode or stream closed

Definition at line 877 of file Bitstream.java.

Here is the caller graph for this function:

◆ readBits31()

int org.jau.io.Bitstream< T >.readBits31 ( final int n ) throws IllegalArgumentException, IOException

Return incoming bits as read via readBit(boolean) LSB-first as little-endian.

The incoming bit order is from low- to most-significant-bit, maintaining bit LSB-first order.

Parameters

n	number of bits, maximum 31 bits

Returns: the read bits from 0-n in the given order or EOS.

Exceptions

IllegalStateException	if not in input mode or stream closed
IllegalArgumentException	if n > 31
IOException

Definition at line 1029 of file Bitstream.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readUInt16() [1/2]

final int org.jau.io.Bitstream< T >.readUInt16 ( final 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.

Exceptions

IllegalStateException	if not in input mode or stream closed
IOException

Definition at line 1229 of file Bitstream.java.

Here is the call graph for this function:

◆ readUInt16() [2/2]

static final int org.jau.io.Bitstream< T >.readUInt16	(	final boolean	bigEndian,
		final byte[]	bytes,
		final int	offset ) throws IndexOutOfBoundsException

static

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.

Exceptions

IndexOutOfBoundsException

Definition at line 1270 of file Bitstream.java.

Here is the call graph for this function:

◆ readUInt32() [1/2]

final long org.jau.io.Bitstream< T >.readUInt32 ( final 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.

Exceptions

IllegalStateException	if not in input mode or stream closed
IOException

Definition at line 1336 of file Bitstream.java.

Here is the call graph for this function:

◆ readUInt32() [2/2]

static final long org.jau.io.Bitstream< T >.readUInt32	(	final boolean	bigEndian,
		final byte[]	bytes,
		final int	offset ) throws IndexOutOfBoundsException

static

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.

Exceptions

IndexOutOfBoundsException

Definition at line 1382 of file Bitstream.java.

Here is the call graph for this function:

◆ readUInt8()

final int org.jau.io.Bitstream< T >.readUInt8 ( ) throws IllegalStateException, IOException

Return incoming uint8_t as read via readBits31(int).

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

Returns: EOS or the 8bit unsigned value within the lower bits.

Exceptions

IllegalStateException	if not in input mode or stream closed
IOException

Definition at line 1179 of file Bitstream.java.

Here is the call graph for this function:

◆ reset()

final void org.jau.io.Bitstream< T >.reset ( ) throws IllegalStateException, IOException

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

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

Exceptions

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.

Definition at line 766 of file Bitstream.java.

◆ setStream()

final void org.jau.io.Bitstream< T >.setStream	(	final T	stream,
		final 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.

Exceptions

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

Definition at line 670 of file Bitstream.java.

Here is the call graph for this function:

◆ setThrowIOExceptionOnEOF()

final void org.jau.io.Bitstream< T >.setThrowIOExceptionOnEOF ( final 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.

Definition at line 654 of file Bitstream.java.

◆ skip()

long org.jau.io.Bitstream< T >.skip ( final 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

Exceptions

IOException	if read error occurs or EOS is reached and `setThrowIOExceptionOnEOF(boolean)` is set to true.
IllegalStateException	if closed

Definition at line 950 of file Bitstream.java.

Here is the call graph for this function:

◆ toBinString()

static String org.jau.io.Bitstream< T >.toBinString	(	final boolean	msbFirst,
		final int	v,
		final int	bitCount )

static

Definition at line 1514 of file Bitstream.java.

Here is the caller graph for this function:

◆ toHexBinString() [1/3]

static final String org.jau.io.Bitstream< T >.toHexBinString	(	final boolean	msbFirst,
		final byte[]	data,
		final int	offset,
		final int	len )

static

Definition at line 1535 of file Bitstream.java.

Here is the call graph for this function:

◆ toHexBinString() [2/3]

static final String org.jau.io.Bitstream< T >.toHexBinString	(	final boolean	msbFirst,
		final ByteBuffer	data,
		final int	offset,
		final int	len )

static

Definition at line 1545 of file Bitstream.java.

Here is the call graph for this function:

◆ toHexBinString() [3/3]

static String org.jau.io.Bitstream< T >.toHexBinString	(	final boolean	msbFirst,
		final int	v,
		final int	bitCount )

static

Definition at line 1531 of file Bitstream.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ toString()

String org.jau.io.Bitstream< T >.toString ( )

Definition at line 1496 of file Bitstream.java.

Here is the call graph for this function:

◆ toStringImpl()

String org.jau.io.Bitstream< T >.toStringImpl ( )

protected

Definition at line 1499 of file Bitstream.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ toUInt32Int()

static final int org.jau.io.Bitstream< T >.toUInt32Int ( final int int32 )

static

Returns the reinterpreted given int32_t value as uint32_t if ≤ Integer#MAX_VALUE as within an int storage.

Otherwise return -1.

Definition at line 1478 of file Bitstream.java.

Here is the call graph for this function:

◆ toUInt32Long()

static final long org.jau.io.Bitstream< T >.toUInt32Long ( final int int32 )

static

Reinterpret the given int32_t value as uint32_t, i.e.

perform the following cast to long:

  final long l = 0xffffffffL & int32;

Definition at line 1468 of file Bitstream.java.

Here is the caller graph for this function:

◆ uint32LongToInt()

static final int org.jau.io.Bitstream< T >.uint32LongToInt ( final long uint32 )

static

Returns the given uint32_t value long value as int if ≤ Integer#MAX_VALUE.

Otherwise return -1.

Definition at line 1487 of file Bitstream.java.

Here is the caller graph for this function:

◆ writeBit()

final int org.jau.io.Bitstream< T >.writeBit	(	final boolean	msbFirst,
		final 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.

Exceptions

IOException
IllegalStateException	if not in output mode or stream closed

Definition at line 913 of file Bitstream.java.

Here is the caller graph for this function:

◆ writeBits31()

int org.jau.io.Bitstream< T >.writeBits31	(	final int	n,
		final int	bits ) throws IllegalStateException, IllegalArgumentException, IOException

Write the given bits via writeBit(boolean, int) LSB-first as little-endian.

The outgoing bit order is from low- to most-significant-bit, maintaining bit LSB-first order.

Parameters

n	number of bits, maximum 31 bits
bits	the bits to write

Returns: the written bits or EOS.

Exceptions

IllegalStateException	if not in output mode or stream closed
IllegalArgumentException	if n > 31
IOException

Definition at line 1106 of file Bitstream.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ writeInt16()

final int org.jau.io.Bitstream< T >.writeInt16	(	final boolean	bigEndian,
		final 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.

Exceptions

IllegalStateException	if not in output mode or stream closed
IOException

Definition at line 1290 of file Bitstream.java.

Here is the call graph for this function:

◆ writeInt32()

final int org.jau.io.Bitstream< T >.writeInt32	(	final boolean	bigEndian,
		final 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.

Exceptions

IllegalStateException	if not in output mode or stream closed
IOException

Definition at line 1403 of file Bitstream.java.

Here is the call graph for this function:

◆ writeInt8()

final int org.jau.io.Bitstream< T >.writeInt8 ( final byte int8 ) throws IllegalStateException, IOException

Write the given 8 bits via writeBits31(int, int).

Returns: EOS or the written 8bit value.

Exceptions

IllegalStateException	if not in output mode or stream closed
IOException

Definition at line 1201 of file Bitstream.java.

Here is the call graph for this function:

Member Data Documentation

◆ EOS

final int org.jau.io.Bitstream< T >.EOS = -1

static

End of stream marker, {@value} or 0xFFFFFFFF.

Definition at line 53 of file Bitstream.java.

The documentation for this class was generated from the following file:

java_base/org/jau/io/Bitstream.java

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Bitstream()

Member Function Documentation

◆ canInput()

◆ canOutput()

◆ checkBounds()

◆ close()

◆ flush()

◆ getBitBuffer()

◆ getBitCount()

◆ getBitPosition()

◆ getLastBitPos()

◆ getStream()

◆ getSubStream()

◆ getThrowIOExceptionOnEOF()

◆ mark()

◆ position() [1/2]

◆ position() [2/2]

◆ readBit()

◆ readBits31()

◆ readUInt16() [1/2]

◆ readUInt16() [2/2]

◆ readUInt32() [1/2]

◆ readUInt32() [2/2]

◆ readUInt8()

◆ reset()

◆ setStream()

◆ setThrowIOExceptionOnEOF()

◆ skip()

◆ toBinString()

◆ toHexBinString() [1/3]

◆ toHexBinString() [2/3]

◆ toHexBinString() [3/3]

◆ toString()

◆ toStringImpl()

◆ toUInt32Int()

◆ toUInt32Long()

◆ uint32LongToInt()

◆ writeBit()

◆ writeBits31()

◆ writeInt16()

◆ writeInt32()

◆ writeInt8()

Member Data Documentation

◆ EOS