Package org.yamcs.utils

Class 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

      All Methods Instance Methods Concrete Methods 
      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

    • Constructor Detail

      • 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 Detail

      • 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 -