2. Bitset

The bitset(3m) module provides functions for testing and manipulating an arbitrary pointer to memory as a set of bits. Unlike other modules in Libmba, this is not an abstract data type 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 is 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.

2.1. The bitset functions

These functions should be used to test and manipulate a memory pointer as a set of bits.

The bitset_isset function
Synopsis


  #include <mba/bitset.h>
  int bitset_isset(void *ptr, int bit);

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

The bitset_set function
Synopsis


  #include <mba/bitset.h>
  int bitset_set(void *ptr, int bit);

Description
The bitset_set function sets the bit at the index identified by bit and returns 1 if the bit was set or 0 if the bitset was not modified.

The bitset_unset function
Synopsis


  #include <mba/bitset.h>
  int bitset_unset(void *ptr, int bit);

Description
The bitset_unset function unsets the bit at the index identified by bit and returns 1 if the bit was unset or 0 if the bitset was not modified.

The bitset_toggle function
Synopsis


  #include <mba/bitset.h>
  void bitset_toggle(void *ptr, int bit);

Description
The bitset_toggle function toggles the bit identified by bit. This function does not return a value.

The bitset_find_first function
Synopsis


  #include <mba/bitset.h>
  int bitset_find_first(void *ptr, void *plim, int val);

Description
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.
Returns
The bitset_find_first function returns the index of the first bit with the value val or -1 and sets errno to ENOENT if there is no such bit in the memory between ptr and plim.

The bitset_iterate function
Synopsis


  #include <mba/bitset.h>
  void bitset_iterate(iter_t *iter);

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

The bitset_next function
Synopsis


  #include <mba/bitset.h>
  int bitset_next(void *ptr, void *plim, iter_t *iter);

Returns
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.