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: Return a single nibble from the byte array, with range checking.
  14  *
  15  * source - the source byte array.
  16  * source_length - the total length of the source array.
  17  * nibble_index - the index of the nibble to retreive. The leftmost nibble is
  18  *      index 0.
  19  *
  20  * Returns the retreived nibble, right aligned in a uint8_t.
  21  */
  22 uint8_t get_nibble(const uint8_t source[], const uint8_t source_length,
  23                 const uint8_t nibble_index);
  24
  25 /* Public: Return a single byte from the byte array, with range checking.
  26  *
  27  * source - the source byte array.
  28  * source_length - the total length of the source array.
  29  * byte_index - the index of the byte to retreive. The leftmost byte is index 0.
  30  *
  31  * Returns the retreived byte.
  32  */
  33 uint8_t get_byte(const uint8_t source[], const uint8_t source_length,
  34         const uint8_t byte_index);
  35
  36 /* Public: Copy a range of bits from one bit array to another.
  37  *
  38  * The range does not need to be byte aligned, and the source and destination do
  39  * not have to be the same size (as long as the desitnation has enough room to
  40  * fit the range).
  41  *
  42  * A bit array with regards to this function always has the leftmost bit in byte
  43  * 0, i.e. bit index is the leftmost bit of byte 0. Endianness does not matter.
  44  *
  45  * For example:
  46  *
  47  *      uint8_t source[4] = {0x11, 0x22, 0x33, 0x44};
  48  *      uint8_t destination[4] = {0};
  49  *      copy_bits(source, sizeof(source), 8, 8, destination,
  50  *              sizeof(destination), 0);
  51  *      // destination[0] == 0x22
  52  *      // destination[1] == 0x0
  53  *      // destination[2] == 0x0
  54  *      // destination[3] == 0x0
  55  *
  56  * Thanks to
  57  * http://stackoverflow.com/questions/3534535/whats-a-time-efficient-algorithm-to-copy-unaligned-bit-arrays
  58  * for the implementation of the algorithm.
  59  *
  60  * source_origin - the source array.
  61  * source_length - the total length of the source array in bytes,
  62  *      for range checking.
  63  * source_offset - an offset in bits to start the copy from the source array.
  64  *      Specify 0 to start from source_origin.
  65  * bit_count - the number of bits to copy.
  66  * destination_origin - the destination array.
  67  * desitnation_length - the total length of the destination array in bytes,
  68  *      for range checking.
  69  * destination_offset - an offset in bits to start placing the copied range into
  70  *      the destination array. Specify 0 to start from the beginning of the
  71  *      destination. If you are copying a range not aligned on a byte, you
  72  *      probably want to set this to a positive offset to right the resulting
  73  *      bits in the destination.
  74  *
  75  * Returns true if the copy was successful and false if the range exceeded the
  76  * size of the source or destination, or if the range size negative or 0.
  77  */
  78 bool copy_bits(const uint8_t* source_origin, const uint16_t source_length,
  79         const uint16_t source_offset, uint16_t bit_count,
  80         uint8_t* destination_origin, const uint16_t destination_length,
  81         const uint16_t destination_offset);
  82
  83 /* Public: Copy a range of bits from one array to another, right aligning the
  84  * result.
  85  *
  86  * This is mostly useful if you want to cast the result to an integer type
  87  * instead of a byte array.
  88  *
  89  * For example:
  90  *
  91  *      uint8_t source[4] = {0x11, 0x22, 0x33, 0x44};
  92  *      uint8_t destination[4] = {0};
  93  *      copy_bits_right_aligned(source, sizeof(source), 8, 8, destination,
  94  *              sizeof(destination));
  95  *      // destination[0] == 0x0
  96  *      // destination[1] == 0x0
  97  *      // destination[2] == 0x0
  98  *      // destination[3] == 0x22
  99  *
 100  *      int value = (int)destination;
 101  *      // value == 0x22 == 32
 102  *
 103  * The arguments are the same as copy_bits, but without the destination_offset
 104  * option - that's set automatically to right align the result.
 105  *
 106  * Returns true if the copy was successful and false if the range exceeded the
 107  * size of the source or destination, or if the range size negative or 0.
 108  */
 109 bool copy_bits_right_aligned(const uint8_t source[], const uint16_t source_length,
 110                 const uint16_t offset, const uint16_t bit_count,
 111                 uint8_t* destination, const uint16_t destination_length);
 112
 113 /* Public: Copy a range of bytes from one byte array to another.
 114  *
 115  * The source and destination do not have to be the same size (as long as the
 116  * desitnation has enough room to fit the range).
 117  *
 118  * source_origin - the source array.
 119  * source_length - the total length of the source array in bytes,
 120  *      for range checking.
 121  * source_offset - a byte offset to start the copy from the source array.
 122  *      Specify 0 to start from source_origin.
 123  * byte_count - the number of bytes to copy.
 124  * destination_origin - the destination array.
 125  * desitnation_length - the total length of the destination array in bytes,
 126  *      for range checking.
 127  * destination_offset - an offset in bytes to start placing the copied range into
 128  *      the destination array. Specify 0 to start from the beginning of the
 129  *      destination.
 130  *
 131  * Returns true if the copy was successful and false if the range exceeded the
 132  * size of the source or destination, or if the range size negative or 0.
 133  */
 134 bool copy_bytes_right_aligned(const uint8_t source[], const uint16_t source_length,
 135                 const uint16_t offset, const uint16_t byte_count,
 136                 uint8_t* destination, const uint16_t destination_length);
 137
 138 bool set_nibble(const uint16_t nibble_index, const uint8_t value,
 139                 uint8_t* destination, const uint16_t destination_length);
 140
 141 /* Private:
 142  */
 143 uint16_t bits_to_bytes(uint32_t bits);
 144
 145 /* Private:
 146  */
 147 uint64_t bitmask(const uint8_t bit_count);
 148
 149 #ifdef __cplusplus
 150 }
 151 #endif
 152
 153 #endif // __BITFIELD_H__