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 classBitstream.ByteArrayStreamSpecificbyte stream.static classBitstream.ByteBufferStreamSpecificbyte stream.static classBitstream.ByteInputStreamSpecificbyte stream.static classBitstream.ByteOutputStreamSpecificbyte stream.static interfaceBitstream.ByteStream<T>General byte stream.
-
Field Summary
Fields Modifier and Type Field Description static intEOSEnd 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 booleancanInput()Return true if stream can handle input, i.e.booleancanOutput()Return true if stream can handle output, i.e.static voidcheckBounds(byte[] sb, int offset, int remaining)voidclose()Closing the underlying stream, impliesflush().intflush()Synchronizes all underlyingoutput streamoperations, or do nothing.intgetBitBuffer()Returns the current bit buffer.intgetBitCount()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).intgetBitPosition()Return the next bit number to be read or write counting from [0..7].intgetLastBitPos()Return the last bit number read or written counting from [0..7].Bitstream.ByteStream<T>getStream()Returns the currently usedBitstream.ByteStream.TgetSubStream()Returns the currently usedBitstream.ByteStream'sBitstream.ByteStream.getStream().booleangetThrowIOExceptionOnEOF()Returns true if I/O methods throw anIOExceptionifEOSappears, otherwise false (default).voidmark(int readLimit)Setmarkposto current position, allowing the stream to bereset().longposition()Returns the bit position in the stream.longposition(long newPosition)Sets this stream's bit position.intreadBit(boolean msbFirst)intreadBits31(int n)Return incoming bits as read viareadBit(boolean)LSB-first as little-endian.intreadUInt16(boolean bigEndian)Return incominguint16_tas read viareadBits31(int)LSB-first as little-endian, hence bytes are swapped if bigEndian.static intreadUInt16(boolean bigEndian, byte[] bytes, int offset)Return incominguint16_tvalue and swap bytes according to bigEndian.longreadUInt32(boolean bigEndian)Return incominguint32_tas read viareadBits31(int)LSB-first as little-endian, hence bytes are swapped if bigEndian.static longreadUInt32(boolean bigEndian, byte[] bytes, int offset)Return incominguint32_tand swap bytes according to bigEndian.intreadUInt8()Return incominguint8_tas read viareadBits31(int).voidreset()Reset stream position to markpos as set viamark(int).voidsetStream(T stream, boolean outputMode)Sets the underlying stream, withoutclose()ing the previous one.voidsetThrowIOExceptionOnEOF(boolean enable)Enables or disables throwing anIOExceptionin caseEOSappears.longskip(long n)It is implementation dependent, whether backward skip giving a negative number is supported or not.static StringtoBinString(boolean msbFirst, int v, int bitCount)static StringtoHexBinString(boolean msbFirst, byte[] data, int offset, int len)static StringtoHexBinString(boolean msbFirst, int v, int bitCount)static StringtoHexBinString(boolean msbFirst, ByteBuffer data, int offset, int len)StringtoString()protected StringtoStringImpl()static inttoUInt32Int(int int32)Returns the reinterpreted givenint32_tvalue asuint32_tif ≤Integer.MAX_VALUEas within anintstorage.static longtoUInt32Long(int int32)Reinterpret the givenint32_tvalue asuint32_t, i.e.static intuint32LongToInt(long uint32)intwriteBit(boolean msbFirst, int bit)intwriteBits31(int n, int bits)Write the given bits viawriteBit(boolean, int)LSB-first as little-endian.intwriteInt16(boolean bigEndian, short int16)Write the given 16 bits viawriteBits31(int, int)LSB-first as little-endian, hence bytes are swapped if bigEndian.intwriteInt32(boolean bigEndian, int int32)Write the given 32 bits viawriteBits31(int, int)LSB-first as little-endian, hence bytes are swapped if bigEndian.intwriteInt8(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 anIOExceptionin caseEOSappears.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 anIOExceptionifEOSappears, 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 IOExceptionClosing the underlying stream, impliesflush().Implementation will
nullthe 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, IOExceptionSynchronizes all underlyingoutput streamoperations, or do nothing.Method also flushes incomplete bytes to the underlying
Bitstream.ByteStreamand hence skips to the next byte position.- Returns:
EOScaused 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 IllegalStateExceptionSetmarkposto 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, IOExceptionReset 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, IOExceptionSets this stream's bit position.A set mark is cleared.
Returns
EOSis end-of-stream is reached, otherwise the new position.Known supporting implementation is
Bitstream.ByteBufferStreamandBitstream.ByteArrayStream.- Parameters:
newPosition- The new positive position.- Returns:
- The new set position or
EOSif end-of-stream is reached. - Throws:
UnsupportedOperationException- if not supported, i.e.Bitstream.ByteInputStreamorBitstream.ByteOutputStreamIllegalArgumentException- If thenewPositionis 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
EOSif end-of-stream is reached. - Throws:
IOExceptionIllegalStateException- 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
EOSif end-of-stream is reached. - Throws:
IOExceptionIllegalStateException- if not in output mode or stream closed
-
skip
public long skip(long n) throws IllegalStateException, IOExceptionIt 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, IOExceptionReturn 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, IOExceptionWrite 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, IOExceptionReturn incominguint8_tas read viareadBits31(int).In case of a
int8_t2-complement signed value, simply cast the result tobyteafter checking forEOS.- Returns:
EOSor 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, IOExceptionWrite the given 8 bits viawriteBits31(int, int).- Returns:
EOSor the written 8bit value.- Throws:
IllegalStateException- if not in output mode or stream closedIOException
-
readUInt16
public final int readUInt16(boolean bigEndian) throws IllegalStateException, IOExceptionReturn incominguint16_tas read viareadBits31(int)LSB-first as little-endian, hence bytes are swapped if bigEndian.In case of a
int16_t2-complement signed value, simply cast the result toshortafter checking forEOS.- Parameters:
bigEndian- if true, swap incoming bytes to little-endian, otherwise leave them as little-endian.- Returns:
EOSor 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 IndexOutOfBoundsExceptionReturn incominguint16_tvalue and swap bytes according to bigEndian.In case of a
int16_t2-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, IOExceptionWrite 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:
EOSor the written 16bit value.- Throws:
IllegalStateException- if not in output mode or stream closedIOException
-
readUInt32
public final long readUInt32(boolean bigEndian) throws IllegalStateException, IOExceptionReturn incominguint32_tas read viareadBits31(int)LSB-first as little-endian, hence bytes are swapped if bigEndian.In case of a
int32_t2-complement signed value, simply cast the result tointafter checking forEOS.- Parameters:
bigEndian- if true, swap incoming bytes to little-endian, otherwise leave them as little-endian.- Returns:
EOSor 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 IndexOutOfBoundsExceptionReturn incominguint32_tand swap bytes according to bigEndian.In case of a
int32_t2-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, IOExceptionWrite 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:
EOSor 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_tvalue 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_tvalue asuint32_tif ≤Integer.MAX_VALUEas within anintstorage. 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
-
-