libs/bitfield-c/src/bitfield/bitfield.h

   1 #ifndef __BITFIELD_H__
   2 #define __BITFIELD_H__
   3
   4 #include <stdint.h>
   5 #include <stdbool.h>
   6
   7 #define NIBBLE_SIZE (CHAR_BIT / 2)
   8
   9 #ifdef __cplusplus
  10 extern "C" {
  11 #endif
  12
  13 /* Public: Reads a subset of bits into a uint64_t, right aligned so they may be
  14  * interpreted as a number.
  15  *
  16  * source - the bytes in question.
  17  * source_size - the number of bytes in the source.
  18  * offset - the starting index of the bit field (beginning from 0).
  19  * bit_count - the width of the bit field to extract. This must be less than or
  20  *      equal to 64.
  21  *
  22  * Bit fields are positioned according to big-endian bit layout and the data is
  23  * swapped automatically as necessary depending on the compiled architecture.
  24  *
  25  * For example, the bit layout of the value "42" (i.e. 00101010 set at position
  26  * 14 with length 6 is:
  27  *
  28  *     000000000000001010100000000000000000000000000000000000000000000
  29  *
  30  * and the same value and position but with length 8 is:
  31  *
  32  *     000000000000000010101000000000000000000000000000000000000000000
  33  *
  34  * Examples
  35  *
  36  *  uint64_t value = get_bitfield(data, data_size, 2, 4);
  37  *
  38  * Returns the value of the requested bit field, right aligned in a uint64_t.
  39  */
  40 uint64_t get_bitfield(const uint8_t source[], const uint8_t source_length,
  41                 const uint16_t offset, const uint16_t bit_count);
  42
  43 /* Public: Return a single nibble from the byte array, with range checking.
  44  *
  45  * source - the source byte array.
  46  * source_length - the total length of the source array.
  47  * nibble_index - the index of the nibble to retreive. The leftmost nibble is
  48  *      index 0.
  49  *
  50  * Returns the retreived nibble, right aligned in a uint8_t.
  51  */
  52 uint8_t get_nibble(const uint8_t source[], const uint8_t source_length,
  53                 const uint8_t nibble_index);
  54
  55 /* Public: Return a single byte from the byte array, with range checking.
  56  *
  57  * source - the source byte array.
  58  * source_length - the total length of the source array.
  59  * byte_index - the index of the byte to retreive. The leftmost byte is index 0.
  60  *
  61  * Returns the retreived byte.
  62  */
  63 uint8_t get_byte(const uint8_t source[], const uint8_t source_length,
  64         const uint8_t byte_index);
  65
  66 /* Public: Copy a range of bits from one bit array to another.
  67  *
  68  * The range does not need to be byte aligned, and the source and destination do
  69  * not have to be the same size (as long as the desitnation has enough room to
  70  * fit the range).
  71  *
  72  * A bit array with regards to this function always has the leftmost bit in byte
  73  * 0, i.e. bit index is the leftmost bit of byte 0. Endianness does not matter.
  74  *
  75  * For example:
  76  *
  77  *      uint8_t source[4] = {0x11, 0x22, 0x33, 0x44};
  78  *      uint8_t destination[4] = {0};
  79  *      copy_bits(source, sizeof(source), 8, 8, destination,
  80  *              sizeof(destination), 0);
  81  *      // destination[0] == 0x22
  82  *      // destination[1] == 0x0
  83  *      // destination[2] == 0x0
  84  *      // destination[3] == 0x0
  85  *
  86  * Thanks to
  87  * http://stackoverflow.com/questions/3534535/whats-a-time-efficient-algorithm-to-copy-unaligned-bit-arrays
  88  * for the implementation of the algorithm.
  89  *
  90  * source_origin - the source array.
  91  * source_length - the total length of the source array in bytes,
  92  *      for range checking.
  93  * source_offset - an offset in bits to start the copy from the source array.
  94  *      Specify 0 to start from source_origin.
  95  * bit_count - the number of bits to copy.
  96  * destination_origin - the destination array.
  97  * desitnation_length - the total length of the destination array in bytes,
  98  *      for range checking.
  99  * destination_offset - an offset in bits to start placing the copied range into
 100  *      the destination array. Specify 0 to start from the beginning of the
 101  *      destination. If you are copying a range not aligned on a byte, you
 102  *      probably want to set this to a positive offset to right the resulting
 103  *      bits in the destination.
 104  *
 105  * Returns true if the copy was successful and false if the range exceeded the
 106  * size of the source or destination, or if the range size negative or 0.
 107  */
 108 bool copy_bits(const uint8_t* source_origin, const uint16_t source_length,
 109         const uint16_t source_offset, uint16_t bit_count,
 110         uint8_t* destination_origin, const uint16_t destination_length,
 111         const uint16_t destination_offset);
 112
 113 /* Public: Copy a range of bits from one array to another, right aligning the
 114  * result.
 115  *
 116  * This is mostly useful if you want to cast the result to an integer type
 117  * instead of a byte array.
 118  *
 119  * For example:
 120  *
 121  *      uint8_t source[4] = {0x11, 0x22, 0x33, 0x44};
 122  *      uint8_t destination[4] = {0};
 123  *      copy_bits_right_aligned(source, sizeof(source), 8, 8, destination,
 124  *              sizeof(destination));
 125  *      // destination[0] == 0x0
 126  *      // destination[1] == 0x0
 127  *      // destination[2] == 0x0
 128  *      // destination[3] == 0x22
 129  *
 130  *      int value = (int)destination;
 131  *      // value == 0x22 == 32
 132  *
 133  * The arguments are the same as copy_bits, but without the destination_offset
 134  * option - that's set automatically to right align the result.
 135  *
 136  * Returns true if the copy was successful and false if the range exceeded the
 137  * size of the source or destination, or if the range size negative or 0.
 138  */
 139 bool copy_bits_right_aligned(const uint8_t source[], const uint16_t source_length,
 140                 const uint16_t offset, const uint16_t bit_count,
 141                 uint8_t* destination, const uint16_t destination_length);
 142
 143 /* Public: Copy a range of bytes from one byte array to another.
 144  *
 145  * The source and destination do not have to be the same size (as long as the
 146  * desitnation has enough room to fit the range).
 147  *
 148  * source_origin - the source array.
 149  * source_length - the total length of the source array in bytes,
 150  *      for range checking.
 151  * source_offset - a byte offset to start the copy from the source array.
 152  *      Specify 0 to start from source_origin.
 153  * byte_count - the number of bytes to copy.
 154  * destination_origin - the destination array.
 155  * desitnation_length - the total length of the destination array in bytes,
 156  *      for range checking.
 157  * destination_offset - an offset in bytes to start placing the copied range into
 158  *      the destination array. Specify 0 to start from the beginning of the
 159  *      destination.
 160  *
 161  * Returns true if the copy was successful and false if the range exceeded the
 162  * size of the source or destination, or if the range size negative or 0.
 163  */
 164 bool copy_bytes_right_aligned(const uint8_t source[], const uint16_t source_length,
 165                 const uint16_t offset, const uint16_t byte_count,
 166                 uint8_t* destination, const uint16_t destination_length);
 167
 168 /* Public: Set the a nibble in the given data array to the new value.
 169  *
 170  * nibble_index - the index of the nibble to retreive. The leftmost nibble is
 171  *      index 0.
 172  * value - the value to set in the bit field.
 173  * destination - the destination array.
 174  * destination_length - the total length of the destination array in bytes,
 175  *      for range checking.
 176  *
 177  * Returns true if the bit_count is enough to fully represent the value, and
 178  *      false if it will not fit.
 179  */
 180 bool set_nibble(const uint16_t nibble_index, const uint8_t value,
 181                 uint8_t* destination, const uint16_t destination_length);
 182
 183 /* Public: Set the bit field in the given data array to the new value.
 184  *
 185  * value - the value to set in the bit field.
 186  * offset - the starting index of the bit field (beginning from 0).
 187  * bit_count - the number of bits to set in the data.
 188  * destination - the destination array.
 189  * destination_length - the total length of the destination array in bytes,
 190  *      for range checking.
 191  *
 192  * Returns true if the bit_count is enough to fully represent the value, and
 193  *      false if it will not fit.
 194  */
 195 bool set_bitfield(const uint64_t value, const uint16_t offset,
 196         const uint16_t bit_count, uint8_t destination[],
 197         uint16_t destination_length);
 198
 199 /* Public: Return a right aligned bitmask for a uint64_t.
 200  *
 201  * bit_count - the number of bits to mask, right aligned.
 202  */
 203 uint64_t bitmask(const uint8_t bit_count);
 204
 205 /* Private:
 206  */
 207 uint16_t bits_to_bytes(uint32_t bits);
 208
 209 /* Private: A union to assist swapping between uint64_t and a uint8_t array.
 210  */
 211 typedef union {
 212     uint64_t whole;
 213     uint8_t bytes[sizeof(uint64_t)];
 214 } ArrayOrBytes;
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif
 219
 220 #endif // __BITFIELD_H__