Bitset

# 2. Bitset

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.

### 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`, `bitset_set`, `bitset_unset` and `bitset_toggle` functions are actually macros.

The `bitset_isset` function
Synopsis

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

Description
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.
Returns
The `bitset_isset` macro 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>
      unsigned char bitset_set(void *ptr, int bit);

Description
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`).

The `bitset_unset` function
Synopsis

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

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

The `bitset_toggle` function
Synopsis

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

Description
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`).

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

Copyright 2004 Michael B. Allen <mba2000 ioplex.com>