.\" 
.\" 	Copyright 2004 Michael B. Allen <mba2000 ioplex.com>
.\" 
.TH bitset 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions"
.SH NAME
bitset \- functions for manipulating memory as sets of bits
.SH SYNOPSIS
.nf
.B #include <mba/bitset.h>
.sp
.BI "int bitset_isset(void *" ptr ", int " bit ");
.br
.BI "int bitset_set(void *" ptr ", int " bit ");
.br
.BI "int bitset_unset(void *" ptr ", int " bit ");
.br
.BI "void bitset_toggle(void *" ptr ", int " bit ");
.br
.BI "int bitset_find_first(void *" ptr ", void *" plim ", int " val ");
.br
.BI "void bitset_iterate(iter_t *" iter "); 
.br
.BI "int bitset_next(void *" ptr ", void *" plim ", iter_t *" iter ");
.br

.fi
.SH DESCRIPTION
The
.BR "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
.BR "bitset" (3m)
operations threat the target memory as an array of
.I unsigned char
elements. Bit 0 of each element is the least significant bit whereas bit 7 is the most significant bit.
.sp
Paramters and return values that represent the index of a bit in the
.BR "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.
.PP
.TP
.B isset
The
.B bitset_isset
function tests the bit at the index identified by
.I bit
and returns 1 or 0 to indicate that it is set or unset respectively.
.TP
.B set
The
.B bitset_set
function sets the bit at the index identified by
.I bit
and returns 1 if the bit was set or 0 if the
.B bitset
was not modified.
.TP
.B unset
The
.B bitset_unset
function unsets the bit at the index identified by
.I bit
and returns 1 if the bit was unset or 0 if the
.B bitset
was not modified.
.TP
.B toggle
The
.B bitset_toggle
function toggles the bit identified by
.IR "bit" .
This function does not return a value.
.TP
.B find_first
The
.B bitset_find_first
function returns the index of the first bit with the value
.I val
starting at the memory
.I ptr
up to, but not including, the memory at
.IR "plim" .
Specifically if
.I val
is 0 the index of the first bit not set is returned whereas if
.I val
is non-zero the index of the first bit that is set is returned.
.TP
.B iterate\fR, \fBnext
The
.B bitset_iterate
and
.B bitset_next
functions are used to iterate over the bits in the
.BR "bitset" (3m)
identified by the memory at
.IR "ptr" .
.SH RETURNS
.TP
.B isset
The
.B bitset_isset
function returns 1 or 0 to indicate that the bit at the index identified by
.I bit
is set or unset respectively.
.TP
.B find_first
The
.B bitset_find_first
function returns the index of the first bit with the value
.I val
or -1 and sets
.B errno
to
.I ENOENT
if there is no such bit in the memory between
.I ptr
and
.IR "plim" .
.TP
.B next
The
.B bitset_next
function returns 0, 1, or -1 to indicate the next bit in the memory at
.I ptr
representing this
.BR "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,
.I plim
will be examined. When
.I plim
is reached -1 is returned.