diff options
Diffstat (limited to 'include/zix/bitset.h')
| -rw-r--r-- | include/zix/bitset.h | 66 |
1 files changed, 57 insertions, 9 deletions
diff --git a/include/zix/bitset.h b/include/zix/bitset.h index 96816c8..491346d 100644 --- a/include/zix/bitset.h +++ b/include/zix/bitset.h @@ -17,10 +17,21 @@ @{ */ -/// A bitset (always referred to by pointer, actually an array) +/** + A bitset element. + + A bitset is an array that is always referred to by pointer. This type is + the type of an element of that array (which stores some number of bits), so + a pointer to this type is a pointer to a bitset. +*/ typedef unsigned long ZixBitset; -/// Tally of the number of bits in one ZixBitset element +/** + Tally of the number of bits in one ZixBitset element. + + Like #ZixBitset, this is the type of one element of a tally, which is a + parallel array to the bitset one, also always referred to by pointer. +*/ typedef uint8_t ZixBitsetTally; /// The number of bits per ZixBitset array element @@ -31,33 +42,66 @@ typedef uint8_t ZixBitsetTally; (((n_bits) / ZIX_BITSET_BITS_PER_ELEM) + \ (((n_bits) % ZIX_BITSET_BITS_PER_ELEM) ? 1 : 0)) -/// Clear a Bitset +/** + Clear a bitset. + + @param b The bitset to clear. + @param t The tally for `b` to update. + @param n_bits The number of bits in `b`. +*/ ZIX_API void zix_bitset_clear(ZixBitset* ZIX_NONNULL b, ZixBitsetTally* ZIX_NONNULL t, size_t n_bits); -/// Set bit `i` in `t` to 1 +/** + Set bit `i` in `b`. + + @param b The bitset to set bit `i` in. + @param t The tally for `b` to update. + @param i The index of the bit to set. +*/ ZIX_API void zix_bitset_set(ZixBitset* ZIX_NONNULL b, ZixBitsetTally* ZIX_NONNULL t, size_t i); -/// Clear bit `i` in `t` (set to 0) +/** + Clear bit `i` in `b`. + + @param b The bitset to set bit `i` in. + @param t The tally for `b` to update. + @param i The index of the bit to set. +*/ ZIX_API void zix_bitset_reset(ZixBitset* ZIX_NONNULL b, ZixBitsetTally* ZIX_NONNULL t, size_t i); -/// Return the bit at index `i` in `b` +/** + Return the bit at index `i` in `b`. + + @param b The bitset to access. + @param i The index of the bit to return. + @return True if the bit is set (1), false otherwise (0). +*/ ZIX_PURE_API bool zix_bitset_get(const ZixBitset* ZIX_NONNULL b, size_t i); -/// Return the number of set bits in `b` up to bit `i` (non-inclusive) +/** + Return the number of set bits in `b` up to bit `i`. + + The returned count is non-inclusive, that is, doesn't include bit `i`. + + @param b The bitset to count. + @param t The tally for `b`. + @param i The end index to stop counting at. + @return The number of set bits in `b` from bit 0 to bit `i - 1`. +*/ ZIX_PURE_API size_t zix_bitset_count_up_to(const ZixBitset* ZIX_NONNULL b, @@ -65,8 +109,12 @@ zix_bitset_count_up_to(const ZixBitset* ZIX_NONNULL b, size_t i); /** - Return the number of set bits in `b` up to bit `i` (non-inclusive) if bit - `i` is set, or `(size_t)-1` otherwise. + Return the number of set bits in `b` up to bit `i` if it is set. + + The returned count is non-inclusive, that is, doesn't include bit `i`. + + @return The number of set bits in `b` from bit 0 to bit `i - 1` if bit `i` + is set, otherwise, `(size_t)-1`. */ ZIX_PURE_API size_t |