7 #define NIBBLE_SIZE (CHAR_BIT / 2)
13 /* Public: Return a single nibble from the byte array, with range checking.
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
20 * Returns the retreived nibble, right aligned in a uint8_t.
22 uint8_t get_nibble(const uint8_t source[], const uint8_t source_length,
23 const uint8_t nibble_index);
25 /* Public: Return a single byte from the byte array, with range checking.
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.
31 * Returns the retreived byte.
33 uint8_t get_byte(const uint8_t source[], const uint8_t source_length,
34 const uint8_t byte_index);
36 /* Public: Copy a range of bits from one bit array to another.
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
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.
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
57 * http://stackoverflow.com/questions/3534535/whats-a-time-efficient-algorithm-to-copy-unaligned-bit-arrays
58 * for the implementation of the algorithm.
60 * source_origin - the source array.
61 * source_length - the total length of the source array in bytes,
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,
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.
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.
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);
83 /* Public: Copy a range of bits from one array to another, right aligning the
86 * This is mostly useful if you want to cast the result to an integer type
87 * instead of a byte array.
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
100 * int value = (int)destination;
101 * // value == 0x22 == 32
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.
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.
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);
113 /* Public: Copy a range of bytes from one byte array to another.
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).
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
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.
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);
138 bool set_nibble(const uint16_t nibble_index, const uint8_t value,
139 uint8_t* destination, const uint16_t destination_length);
141 uint16_t bits_to_bytes(uint32_t bits);
147 #endif // __BITFIELD_H__