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 writeMode) throws IllegalArgumentException, IOException
	Sets the underlying stream, without `close()`ing the previous one.

final void	setWriteMode (final boolean writeMode) throws IllegalArgumentException, IOException
	Sets the output-mode of this stream.

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	canWrite ()
	Returns true in case stream is in write mode, false if in read mode.

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	getCachedBitCount ()
	Number of remaining bits cached to read before next byte-read (input mode) or number of remaining bits to be cached before next byte-write (output mode).

final int	getLastCachedPos ()
	Return the last cached bit position read or written counting from [0..7].

final int	getCachedPos ()
	Return the next cached bit position to be read or written counting from [0..7].

final int	getBitCache ()
	Returns the current bit cache.

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 boolean	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 canWrite().

Definition at line 622 of file Bitstream.java.

Here is the caller graph for this function:

Member Function Documentation

◆ canWrite()

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

Returns true in case stream is in write mode, false if in read mode.

Definition at line 758 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 1581 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 719 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 738 of file Bitstream.java.

◆ getBitCache()

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

Returns the current bit cache.

See also: getCachedBitCount()

Definition at line 828 of file Bitstream.java.

◆ getCachedBitCount()

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

Number of remaining bits cached 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, starting with 0.

In input mode, zero indicates reading up next 8 bits and cont. w/ 7 bits.
In output mode, the cached bits are written when flipping over to 0.

Definition at line 803 of file Bitstream.java.

◆ getCachedPos()

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

Return the next cached bit position to be read or written counting from [0..7].

If no bit access has been performed or none is cached, 0 is returned.

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

Definition at line 820 of file Bitstream.java.

◆ getLastCachedPos()

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

Return the last cached bit position 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 811 of file Bitstream.java.

◆ getStream()

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

Returns the currently used ByteStream.

Definition at line 701 of file Bitstream.java.

◆ getSubStream()

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

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

Definition at line 704 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 661 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 765 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 833 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 866 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 902 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 1055 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 1254 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 1295 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 1361 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 1407 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 1204 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 783 of file Bitstream.java.

◆ setStream()

final void org.jau.io.Bitstream< T >.setStream	(	final T	stream,
		final boolean	writeMode ) 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 `canWrite()`.
IOException	could be caused by `flush()`.

Definition at line 672 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 656 of file Bitstream.java.

◆ setWriteMode()

final void org.jau.io.Bitstream< T >.setWriteMode ( final boolean writeMode ) throws IllegalArgumentException, IOException

Sets the output-mode of this stream.

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

Exceptions

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

Definition at line 691 of file Bitstream.java.

Here is the call graph for this function:

◆ 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 975 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 1539 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 1560 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 1570 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 1556 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 1521 of file Bitstream.java.

Here is the call graph for this function:

◆ toStringImpl()

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

protected

Definition at line 1524 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 1503 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 1493 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 1512 of file Bitstream.java.

Here is the caller graph for this function:

◆ writeBit()

final boolean 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: true if successful, otherwise false

Exceptions

IOException
IllegalStateException	if not in output mode or stream closed

Definition at line 938 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 1132 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 1315 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 1428 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 1226 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

◆ canWrite()

◆ checkBounds()

◆ close()

◆ flush()

◆ getBitCache()

◆ getCachedBitCount()

◆ getCachedPos()

◆ getLastCachedPos()

◆ 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()

◆ setWriteMode()

◆ 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