org.yamcs.utils

Class BitBuffer

java.lang.Object

org.yamcs.utils.BitBuffer

public class BitBuffer
extends Object

Allows to read and write bits from a byte array (byte[]) keeps a bit position and the extractions are relative to the position. It allows also to provide an offset (in bytes) inside the byte array and then the bit position is relative to the offset. Supported operations are - extract up to 64 bits into a long - big endian or little endian - extract a byte array (throws exception if the position is not at the beginning of a byte) - exact a byte (throws exception if the position is not at the beginning of a byte) Note on the Little Endian: it is designed to work on x86 architecture which uses internally little endian byte _and_ bit ordering but when accessing memory, full bytes are transferred in big endian order. For example when in C you have a 32 bit structure: struct S { unsigned int a: 3; unsigned int b: 12; unsigned int c: 17; } and you pack that in a packet by just reading the corresponding 4 bytes memory, you will get the following representation (0 is the most significant bit): b7 b8 b9 b10 b11 a0 a1 a2 c16 b0 b1 b2 b3 b4 b5 b6 c8 c9 c10 c11 c12 c13 c14 c15 c0 c1 c2 c3 c4 c5 c6 c7 To read this with this BitBuffer you would naturally do like this: BitBuffer bb = new BitBuffer(..., 0); bb.setOrder(LITTLE_ENDIAN); a = bb.getBits(3); b = bb.getBits(12); c = bb.getBits(17); Note how the first call (when the bb.position=0) reads the 3 bits at position 5 instead of those at position 0

Author:

nm

Constructor Summary

Constructors

Constructor and Description
BitBuffer(byte[] b) Creates a new bit buffer that wraps array b starting at offset 0
BitBuffer(byte[] b, int offset) Creates a new bit buffer that wraps the array b starting at offset (in bytes)

Method Summary

Modifier and Type	Method and Description
byte[]	array()
int	arrayLength() returns the backing array length in bytes!
long	getBits(int numBits) reads numBits from the buffer and returns them into a long on the rightmost position.
byte	getByte() fast getByte - only works when position%8 = 0 - otherwise throws an IllegalStateException advances the position by 8 bits
void	getByteArray(byte[] dst) Copies bytes from the buffer to the given destination array.
ByteOrder	getByteOrder()
int	getPosition() get position in bits
int	offset() Returns the offset inside the byte array where this buffer starts
void	put(byte[] src) copy the content of the source array into the buffer works only if the position is at the byte boundary
void	put(byte[] src, int offset, int length) Copy bytes into the buffer from the given source array.
void	putBits(long value, int numBits) put the least significant numBits from value into the buffer, increasing the position with numBits
void	putByte(byte c) fast write byte in the buffer works only if the position is at byte boundary
int	remainingBytes() Returns the remaining bytes from position until the end of the buffer.
void	setByteOrder(ByteOrder order)
void	setPosition(int position) set position in bits
int	sizeInBits() returns the size of the buffer (from the offset to the end of the byte array) in bits
BitBuffer	slice() Creates a new BitBuffer backed by the same array but with the offset set at the current position of this buffer Works only when position%8 = 0 - otherwise throws an IllegalStateException

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BitBuffer

public BitBuffer(byte[] b)

Creates a new bit buffer that wraps array b starting at offset 0

Parameters:

b -

BitBuffer

public BitBuffer(byte[] b,
                 int offset)

Creates a new bit buffer that wraps the array b starting at offset (in bytes)

Parameters:

b -

offset -

Method Detail

getBits

public long getBits(int numBits)

reads numBits from the buffer and returns them into a long on the rightmost position. numBits has to be max 64.

Parameters:

numBits -

Returns:

putBits

public void putBits(long value,
                    int numBits)

put the least significant numBits from value into the buffer, increasing the position with numBits

Parameters:

value -

numBits -

put

public void put(byte[] src,
                int offset,
                int length)

Copy bytes into the buffer from the given source array. The bit buffer has to be positioned at a byte boyndary.

put

public void put(byte[] src)

copy the content of the source array into the buffer works only if the position is at the byte boundary

putByte

public void putByte(byte c)

fast write byte in the buffer works only if the position is at byte boundary

getPosition

public int getPosition()

get position in bits

Returns:

current position in bits

setPosition

public void setPosition(int position)

set position in bits

Parameters:

position -

setByteOrder

public void setByteOrder(ByteOrder order)

getByteOrder

public ByteOrder getByteOrder()

getByte

public byte getByte()

fast getByte - only works when position%8 = 0 - otherwise throws an IllegalStateException advances the position by 8 bits

Returns:

the byte at the current position

getByteArray

public void getByteArray(byte[] dst)

Copies bytes from the buffer to the given destination array. Works only when position%8 = 0 - otherwise throws an IllegalStateException

Parameters:

dst - - destination array

sizeInBits

public int sizeInBits()

returns the size of the buffer (from the offset to the end of the byte array) in bits

Returns:

size in bits

arrayLength

public int arrayLength()

returns the backing array length in bytes!

Returns:

array length

slice

public BitBuffer slice()

Creates a new BitBuffer backed by the same array but with the offset set at the current position of this buffer Works only when position%8 = 0 - otherwise throws an IllegalStateException

Returns:

new bit buffer

array

public byte[] array()

offset

public int offset()

Returns the offset inside the byte array where this buffer starts

Returns:

remainingBytes

public int remainingBytes()

Returns the remaining bytes from position until the end of the buffer. Works only when position%8 = 0 - otherwise throws an IllegalStateException

Returns: