7 #define NIBBLE_SIZE (CHAR_BIT / 2)
13 /* Public: Reads a subset of bits into a uint64_t, right aligned so they may be
14 * interpreted as a number.
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
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.
25 * For example, the bit layout of the value "42" (i.e. 00101010 set at position
26 * 14 with length 6 is:
28 * 000000000000001010100000000000000000000000000000000000000000000
30 * and the same value and position but with length 8 is:
32 * 000000000000000010101000000000000000000000000000000000000000000
36 * uint64_t value = get_bitfield(data, data_size, 2, 4);
38 * Returns the value of the requested bit field, right aligned in a uint64_t.
40 uint64_t get_bitfield(const uint8_t source[], const uint8_t source_length,
41 const uint16_t offset, const uint16_t bit_count);
43 /* Public: Return a single nibble from the byte array, with range checking.
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
50 * Returns the retreived nibble, right aligned in a uint8_t.
52 uint8_t get_nibble(const uint8_t source[], const uint8_t source_length,
53 const uint8_t nibble_index);
55 /* Public: Return a single byte from the byte array, with range checking.
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.
61 * Returns the retreived byte.
63 uint8_t get_byte(const uint8_t source[], const uint8_t source_length,
64 const uint8_t byte_index);
66 /* Public: Copy a range of bits from one bit array to another.
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
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.
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
87 * http://stackoverflow.com/questions/3534535/whats-a-time-efficient-algorithm-to-copy-unaligned-bit-arrays
88 * for the implementation of the algorithm.
90 * source_origin - the source array.
91 * source_length - the total length of the source array in bytes,
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,
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.
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.
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);
113 /* Public: Copy a range of bits from one array to another, right aligning the
116 * This is mostly useful if you want to cast the result to an integer type
117 * instead of a byte array.
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
130 * int value = (int)destination;
131 * // value == 0x22 == 32
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.
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.
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);
143 /* Public: Copy a range of bytes from one byte array to another.
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).
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
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.
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);
168 /* Public: Set the a nibble in the given data array to the new value.
170 * nibble_index - the index of the nibble to retreive. The leftmost nibble is
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.
177 * Returns true if the bit_count is enough to fully represent the value, and
178 * false if it will not fit.
180 bool set_nibble(const uint16_t nibble_index, const uint8_t value,
181 uint8_t* destination, const uint16_t destination_length);
183 /* Public: Set the bit field in the given data array to the new value.
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.
192 * Returns true if the bit_count is enough to fully represent the value, and
193 * false if it will not fit.
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);
199 /* Public: Return a right aligned bitmask for a uint64_t.
201 * bit_count - the number of bits to mask, right aligned.
203 uint64_t bitmask(const uint8_t bit_count);
207 uint16_t bits_to_bytes(uint32_t bits);
209 /* Private: A union to assist swapping between uint64_t and a uint8_t array.
213 uint8_t bytes[sizeof(uint64_t)];
220 #endif // __BITFIELD_H__