Package 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)
  • extract 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

  • Constructor Summary

    Constructors
    Constructor
    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
    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
    void
    skip(int numBits)
    Move the position by specified number of 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 Details

    • BitBuffer

      public BitBuffer(byte[] b)
      Creates a new bit buffer that wraps array b starting at offset 0

    • BitBuffer

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

  • Method Details

    • getBits

      public long getBits(int numBits)
      reads numBits from the buffer and returns them into a long on the rightmost position.
      Parameters:
      numBits - has to be max 64.

    • putBits

      public void putBits(long value, int numBits)
      put the least significant numBits from value into the buffer, increasing the position with 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

    • 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

    • 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

    • skip

      public void skip(int numBits)
      Move the position by specified number of bits
      Parameters:
      numBits -