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 Description static class
Bitstream.ByteArrayStream
Specificbyte stream
.static class
Bitstream.ByteBufferStream
Specificbyte stream
.static class
Bitstream.ByteInputStream
Specificbyte stream
.static class
Bitstream.ByteOutputStream
Specificbyte stream
.static interface
Bitstream.ByteStream<T>
General byte stream.
-
Field Summary
Fields Modifier and Type Field Description static int
EOS
End of stream marker, -1 or 0xFFFFFFFF
-
Constructor Summary
Constructors Constructor Description Bitstream(Bitstream.ByteStream<T> stream, boolean outputMode)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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, impliesflush()
.int
flush()
Synchronizes all underlyingoutput 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 usedBitstream.ByteStream
.T
getSubStream()
Returns the currently usedBitstream.ByteStream
'sBitstream.ByteStream.getStream()
.boolean
getThrowIOExceptionOnEOF()
Returns true if I/O methods throw anIOException
ifEOS
appears, otherwise false (default).void
mark(int readLimit)
Setmarkpos
to current position, allowing the stream to bereset()
.long
position()
Returns the bit position in the stream.long
position(long newPosition)
Sets this stream's bit position.int
readBit(boolean msbFirst)
int
readBits31(int n)
Return incoming bits as read viareadBit(boolean)
LSB-first as little-endian.int
readUInt16(boolean bigEndian)
Return incominguint16_t
as read viareadBits31(int)
LSB-first as little-endian, hence bytes are swapped if bigEndian.static int
readUInt16(boolean bigEndian, byte[] bytes, int offset)
Return incominguint16_t
value and swap bytes according to bigEndian.long
readUInt32(boolean bigEndian)
Return incominguint32_t
as read viareadBits31(int)
LSB-first as little-endian, hence bytes are swapped if bigEndian.static long
readUInt32(boolean bigEndian, byte[] bytes, int offset)
Return incominguint32_t
and swap bytes according to bigEndian.int
readUInt8()
Return incominguint8_t
as read viareadBits31(int)
.void
reset()
Reset stream position to markpos as set viamark(int)
.void
setStream(T stream, boolean outputMode)
Sets the underlying stream, withoutclose()
ing the previous one.void
setThrowIOExceptionOnEOF(boolean enable)
Enables or disables throwing anIOException
in caseEOS
appears.long
skip(long n)
It is implementation dependent, whether backward skip giving a negative number is supported or not.static String
toBinString(boolean msbFirst, int v, int bitCount)
static String
toHexBinString(boolean msbFirst, byte[] data, int offset, int len)
static String
toHexBinString(boolean msbFirst, int v, int bitCount)
static String
toHexBinString(boolean msbFirst, ByteBuffer data, int offset, int len)
String
toString()
protected String
toStringImpl()
static int
toUInt32Int(int int32)
Returns the reinterpreted givenint32_t
value asuint32_t
if ≤Integer.MAX_VALUE
as within anint
storage.static long
toUInt32Long(int int32)
Reinterpret the givenint32_t
value asuint32_t
, i.e.static int
uint32LongToInt(long uint32)
int
writeBit(boolean msbFirst, int bit)
int
writeBits31(int n, int bits)
Write the given bits viawriteBit(boolean, int)
LSB-first as little-endian.int
writeInt16(boolean bigEndian, short int16)
Write the given 16 bits viawriteBits31(int, int)
LSB-first as little-endian, hence bytes are swapped if bigEndian.int
writeInt32(boolean bigEndian, int int32)
Write the given 32 bits viawriteBits31(int, int)
LSB-first as little-endian, hence bytes are swapped if bigEndian.int
writeInt8(byte int8)
Write the given 8 bits viawriteBits31(int, int)
.
-
-
-
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'scanInput()
andcanOutput()
.
-
-
Method Detail
-
setThrowIOExceptionOnEOF
public final void setThrowIOExceptionOnEOF(boolean enable)
Enables or disables throwing anIOException
in caseEOS
appears.Default behavior for I/O methods is not to throw an
IOException
, but to returnEOS
.
-
getThrowIOExceptionOnEOF
public final boolean getThrowIOExceptionOnEOF()
Returns true if I/O methods throw anIOException
ifEOS
appears, otherwise false (default).
-
setStream
public final void setStream(T stream, boolean outputMode) throws IllegalArgumentException, IOException
Sets the underlying stream, withoutclose()
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'scanInput()
andcanOutput()
.IOException
- could be caused byflush()
.
-
getStream
public final Bitstream.ByteStream<T> getStream()
Returns the currently usedBitstream.ByteStream
.
-
getSubStream
public final T getSubStream()
Returns the currently usedBitstream.ByteStream
'sBitstream.ByteStream.getStream()
.
-
close
public final void close() throws IOException
Closing the underlying stream, impliesflush()
.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 underlyingoutput 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 closedIOException
-
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
Setmarkpos
to current position, allowing the stream to bereset()
.- Parameters:
readlimit
- maximum number of bytes able to read before invalidating themarkpos
.- 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 viamark(int)
.markpos is kept, hence
reset()
can be called multiple times.- Throws:
IllegalStateException
- if not in input mode or stream closedIllegalStateException
- if markpos has not been set viamark(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.
-
position
public final long position(long newPosition) throws UnsupportedOperationException, IllegalArgumentException, IllegalStateException, IOException
Sets this stream's bit position.A set mark is cleared.
Returns
EOS
is end-of-stream is reached, otherwise the new position.Known supporting implementation is
Bitstream.ByteBufferStream
andBitstream.ByteArrayStream
.- Parameters:
newPosition
- The new positive position.- Returns:
- The new set position or
EOS
if end-of-stream is reached. - Throws:
UnsupportedOperationException
- if not supported, i.e.Bitstream.ByteInputStream
orBitstream.ByteOutputStream
IllegalArgumentException
- If thenewPosition
is negativeIOException
- if read error occurs or EOS is reached andsetThrowIOExceptionOnEOF(boolean)
is set to true.IllegalStateException
-
readBit
public final int readBit(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. - Throws:
IOException
IllegalStateException
- if not in input mode or stream closedUnsupportedOperationException
-
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
- if read error occurs or EOS is reached andsetThrowIOExceptionOnEOF(boolean)
is set to true.IllegalStateException
- if closed
-
readBits31
public int readBits31(int n) throws IllegalArgumentException, IOException
Return incoming bits as read viareadBit(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
. - Throws:
IllegalStateException
- if not in input mode or stream closedIllegalArgumentException
- if n > 31IOException
-
writeBits31
public int writeBits31(int n, int bits) throws IllegalStateException, IllegalArgumentException, IOException
Write the given bits viawriteBit(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 bitsbits
- the bits to write- Returns:
- the written bits or
EOS
. - Throws:
IllegalStateException
- if not in output mode or stream closedIllegalArgumentException
- if n > 31IOException
-
readUInt8
public final int readUInt8() throws IllegalStateException, IOException
Return incominguint8_t
as read viareadBits31(int)
.In case of a
int8_t
2-complement signed value, simply cast the result tobyte
after checking forEOS
.- Returns:
EOS
or the 8bit unsigned value within the lower bits.- Throws:
IllegalStateException
- if not in input mode or stream closedIOException
-
writeInt8
public final int writeInt8(byte int8) throws IllegalStateException, IOException
Write the given 8 bits viawriteBits31(int, int)
.- Returns:
EOS
or the written 8bit value.- Throws:
IllegalStateException
- if not in output mode or stream closedIOException
-
readUInt16
public final int readUInt16(boolean bigEndian) throws IllegalStateException, IOException
Return incominguint16_t
as read viareadBits31(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 toshort
after checking forEOS
.- 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 closedIOException
-
readUInt16
public static final int readUInt16(boolean bigEndian, byte[] bytes, int offset) throws IndexOutOfBoundsException
Return incominguint16_t
value and swap bytes according to bigEndian.In case of a
int16_t
2-complement signed value, simply cast the result toshort
.- 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 viawriteBits31(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 closedIOException
-
readUInt32
public final long readUInt32(boolean bigEndian) throws IllegalStateException, IOException
Return incominguint32_t
as read viareadBits31(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 toint
after checking forEOS
.- 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 closedIOException
-
readUInt32
public static final long readUInt32(boolean bigEndian, byte[] bytes, int offset) throws IndexOutOfBoundsException
Return incominguint32_t
and swap bytes according to bigEndian.In case of a
int32_t
2-complement signed value, simply cast the result toint
.- 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 viawriteBits31(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 closedIOException
-
toUInt32Long
public static final long toUInt32Long(int int32)
Reinterpret the givenint32_t
value asuint32_t
, i.e. perform the following cast tolong
:final long l = 0xffffffffL & int32;
-
toUInt32Int
public static final int toUInt32Int(int int32)
Returns the reinterpreted givenint32_t
value asuint32_t
if ≤Integer.MAX_VALUE
as within anint
storage. Otherwise return -1.
-
uint32LongToInt
public static final int uint32LongToInt(long uint32)
-
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)
-
checkBounds
public static void checkBounds(byte[] sb, int offset, int remaining) throws IndexOutOfBoundsException
- Throws:
IndexOutOfBoundsException
-
-