11 /* Public: Return a single nibble from the byte array, with range checking.
13 * source - the source byte array.
14 * source_length - the total length of the source array.
15 * nibble_index - the index of the nibble to retreive. The leftmost nibble is
18 * Returns the retreived nibble, right aligned in a uint8_t.
20 uint8_t getNibble(const uint8_t source[], const uint8_t source_length,
21 const uint8_t nibble_index);
23 /* Public: Return a single byte from the byte array, with range checking.
25 * source - the source byte array.
26 * source_length - the total length of the source array.
27 * byte_index - the index of the byte to retreive. The leftmost byte is index 0.
29 * Returns the retreived byte.
31 uint8_t getByte(const uint8_t source[], const uint8_t source_length,
32 const uint8_t byte_index);
34 /* Public: Copy a range of bits from one bit array to another.
36 * The range does not need to be byte aligned, and the source and destination do
37 * not have to be the same size (as long as the desitnation has enough room to
40 * A bit array with regards to this function always has the leftmost bit in byte
41 * 0, i.e. bit index is the leftmost bit of byte 0. Endianness does not matter.
45 * uint8_t source[4] = {0x11, 0x22, 0x33, 0x44};
46 * uint8_t destination[4] = {0};
47 * copyBits(source, sizeof(source), 8, 8, destination,
48 * sizeof(destination), 0);
49 * // destination[0] == 0x22
50 * // destination[1] == 0x0
51 * // destination[2] == 0x0
52 * // destination[3] == 0x0
55 * http://stackoverflow.com/questions/3534535/whats-a-time-efficient-algorithm-to-copy-unaligned-bit-arrays
56 * for the implementation of the algorithm.
58 * source_origin - the source array.
59 * source_length - the total length of the source array in bytes,
61 * source_offset - an offset in bits to start the copy from the source array.
62 * Specify 0 to start from source_origin.
63 * bit_count - the number of bits to copy.
64 * destination_origin - the destination array.
65 * desitnation_length - the total length of the destination array in bytes,
67 * destination_offset - an offset in bits to start placing the copied range into
68 * the destination array. Specify 0 to start from the beginning of the
69 * destination. If you are copying a range not aligned on a byte, you
70 * probably want to set this to a positive offset to right the resulting
71 * bits in the destination.
73 * Returns true if the copy was successful and false if the range exceeded the
74 * size of the source or destination, or if the range size negative or 0.
76 bool copyBits(const uint8_t* source_origin, const uint16_t source_length,
77 const uint16_t source_offset, uint16_t bit_count,
78 uint8_t* destination_origin, const uint16_t destination_length,
79 const uint16_t destination_offset);
81 /* Public: Copy a range of bits from one array to another, right aligning the
84 * This is mostly useful if you want to cast the result to an integer type
85 * instead of a byte array.
89 * uint8_t source[4] = {0x11, 0x22, 0x33, 0x44};
90 * uint8_t destination[4] = {0};
91 * copyBitsRightAligned(source, sizeof(source), 8, 8, destination,
92 * sizeof(destination));
93 * // destination[0] == 0x0
94 * // destination[1] == 0x0
95 * // destination[2] == 0x0
96 * // destination[3] == 0x22
98 * int value = (int)destination;
99 * // value == 0x22 == 32
101 * The arguments are the same as copyBits, but without the destination_offset
102 * option - that's set automatically to right align the result.
104 * Returns true if the copy was successful and false if the range exceeded the
105 * size of the source or destination, or if the range size negative or 0.
107 bool copyBitsRightAligned(const uint8_t source[], const uint16_t source_length,
108 const uint16_t offset, const uint16_t bit_count,
109 uint8_t* destination, const uint16_t destination_length);
115 #endif // __BITFIELD_H__