skalibs: the bitarray library interface
Keywords: skalibs c unix bitarray library libstddjb

libstddjb
libskarnet
skalibs
Software
skarnet.org

# The `bitarray` library interface

The following functions are declared in the `skalibs/bitarray.h` header, and implemented in the `libskarnet.a` or `libskarnet.so` library.

## General information

`bitarray` is a set of primitives to operate efficiently on large bitfields.

A bitfield is represented by a pre-allocated block of `unsigned char`; `bitarray` does not care if that block has been BSS-, stack- or heap-allocated. Bitfields that can grow in size should be stored in a stralloc.

Bits in a bitfield of length n are numbered from 0 to n-1.

## Functions

`size_t bitarray_div8 (size_t n)`
Returns the minimum number of bytes needed to store a field of n bits.

`void bitarray_clearsetn (unsigned char *s, size_t start, size_t len, int h)`
Sets (if h is nonzero) or clears (if h is zero) len bits in field s, starting at bit start.

`void bitarray_clearn (unsigned char *s, size_t start, size_t len)`
Clears len bits in field s, starting at bit start.

`void bitarray_setn (unsigned char *s, size_t start, size_t len)`
Sets len bits in field s, starting at bit start.

`int bitarray_peek (unsigned char const *s, size_t n)`
Returns the value of the nth bit in field s.

`void bitarray_poke (unsigned char *s, size_t n, int h)`
Sets (if h is nonzero) or clears (if h is zero) the nth bit in field s.

`void bitarray_clear (unsigned char *s, size_t n)`
Clears the nth bit in field s.

`void bitarray_set (unsigned char *s, size_t n)`
Sets the nth bit in field s.

`int bitarray_testandpoke (unsigned char *s, size_t n, int h)`
Sets (if h is nonzero) or clears (if h is zero) the nth bit in field s, and returns the previous value of that bit.

`int bitarray_testandclear (unsigned char *s, size_t n)`
Clear the nth bit in field s, and returns the previous value of that bit.

`int bitarray_testandset (unsigned char *s, size_t n)`
Sets the nth bit in field s, and returns the previous value of that bit.

`size_t bitarray_first (unsigned char const *s, size_t len, int h)`
Returns the number of the first set (if h is nonzero) or clear (if h is zero) bit in s, len being the total number of bits. If all bits in s are the negation of h, then len is returned.

`size_t bitarray_firstclear (unsigned char const *s, size_t len)`
Returns the number of the first clear bit in s, len being the total number of bits. If all bits in s are set, len is returned.

`size_t bitarray_firstclear_skip (unsigned char const *s, size_t len, size_t skip)`
Like `bitarray_firstclear`, but the first skip bits are ignored: the function cannot return less than skip. It is a programming error if skip > len.

`size_t bitarray_firstset (unsigned char const *s, size_t len)`
Returns the number of the first set bit in s, len being the total number of bits. If all bits in s are clear, len is returned.

`size_t bitarray_firstset_skip (unsigned char const *s, size_t len, size_t skip)`
Like `bitarray_firstset`, but the first skip bits are ignored: the function cannot return less than skip. It is a programming error if skip > len.

`size_t bitarray_countones (unsigned char const *s, size_t len)`
Returns the number of set bits in s, len being the total number of bits being tested.