bitset(3m)

NAME
bitset - macros and functions for manipulating memory as sets of bits

SYNOPSIS
#include <mba/bitset.h>

int bitset_isset(void *ptr, int bit);
unsigned char bitset_set(void *ptr, int bit);
unsigned char bitset_unset(void *ptr, int bit);
unsigned char bitset_toggle(void *ptr, int bit);
int bitset_find_first(void *ptr, void *plim, int val);
void bitset_iterate(iter_t *iter);
int bitset_next(void *ptr, void *plim, iter_t *iter);

DESCRIPTION
The bitset(3m) module provides some basic macros for testing and manipulating an arbitrary pointer to memory as a set of bits as well as some functions to perform more sophisticated operations. Unlike other modules in Libmba, this is not an ADT in that it is the responsibility of the user to manage the memory of the bitset. All bitset(3m) operations threat the target memory as an array of unsigned char elements. Bit 0 of each element is the least significant bit whereas bit 7 would be the most significant bit.

Paramters and return values that represent the index of a bit in the bitset(3m) start at 0 relative to the provided target memory. It is the caller's responsability to ensure that a bit index parameter falls within the target memory.

isset
    The bitset_isset macro tests the bit at the index identified by bit and returns 1 or 0 to indicate that it is set or unset respectively.

set The bitset_set macro sets the bit at the index identified by bit and returns the resulting unsigned char element containing that bit (element bit / 8).

unset
    The bitset_unset macro unsets the bit identified by bit and returns the resulting unsigned char element containing that bit (element bit / 8).

toggle
    The bitset_toggle macro toggles the bit identified by bit (sets if unset or unsets if set) and returns the resulting unsigned char element containing that bit (element bit / 8).

find_first
    The bitset_find_first function returns the index of the first bit with the value val starting at the memory ptr up to, but not including, the memory at plim. Specifically if val is 0 the index of the first bit not set is returned whereas if val is non-zero the index of the first bit that is set is returned.

iterate, next
    The bitset_iterate and bitset_next functions are used to iterate over the bits in the bitset(3m) identified by the memory at ptr.

RETURNS

isset
    The bitset_isset macro returns 1 or 0 to indicate that the bit at the index identified by bit is set or unset respectively.

find_first
    The bitset_find_first function returns the index of the first bit with the value val or -1 if there is no such bit in the memory between ptr and plim.

next
    The bitset_next function returns 0, 1, or -1 to indicate the next bit in the memory at ptr representing this bitset(3m). If the next bit is unset, 0 is returned. If the bit is set, 1 is returned. Only memory up to, but not including, plim will be examined. When plim is reached -1 is returned.