bitfield \- API for manipulating bit arrays.

A library of functions for creating, modifying and destroying bit arrays, i.e.

series of zeroes and ones spread across an array of storage units.

.B struct bitfield

is a data structure for storing bit arrays. It has two elements: an array of

unsigned long integers \fIfield\fR for storing the values of bits and an

unsigned integer \fIsize\fR for storing the number of bits in the array.

For details of each function, refer to its manual page.

.LP

.LP

Creating and deleting bit arrays:

.LP

.B

.br

.RS

creates an empty bitfield structure, and returns a pointer to it

.RE

.LP

.B

.br

.RS

creates a bitfield structure, sets all its bits and returns a pointer to it

.RE

.LP

.B

.br

.RS

creates a bitfield structure and returns a pointer to it

.RE

.LP

.B

.br

.RS

destroys a bitfield structure and frees memory

.RE

.LP

Operations with bit arrays:

.LP

.B

.br

.RS

resizes an existing bitfield

.RE

.LP

.B

.br

.RS

concatenates several bitfields into one

.RE

.LP

.B

.br

.RS

clears all bits in a bitfield (i.e. fills it with zeroes)

.RE

.LP

.B

.br

.RS

creates a copy of an existing bitfield

.RE

.LP

.B

.br

.RS

copies the contents of a bitfield into another pre-existing bitfield

.RE

.LP

.B

.br

.RS

counts the Hamming distance between two bitfields

.RE

.LP

.B

.br

.RS

checks whether all bit of an array are unset

.RE

.LP

.B

.br

.RS

represents a bitfield as a smallest value of a closed ring

.RE

.LP

.B

.br

.RS

counts the set bits in a bitfield

.RE

.LP

.B

.br

.RS

checks whether an array of bits contains a sub-array

.RE

.LP

.B

.br

.RS

reverses the order of bits in a bitfield and returns result in new bitfield

.RE

.LP

.B

.br

.RS

reverses the order of bits in an existing bitfield

.RE

.LP

.B

.br

.RS

sets all bits in a bitfield (i.e. fills it with ones)

.RE

.LP

.B

.br

.RS

circular-shifts the contents of a bitfield and returns the result in new

bitfield

.RE

.LP

.B

.br

.RS

circular-shifts the contents of an existing bitfield

.RE

.LP

.B

.br

.RS

extracts a sub-bitfield in a new bitfield

.RE

.LP

Operations with individual bits:

.LP

.B

.br

.RS

checks the state of a bit in a bitfield

.RE

.LP

.B

.br

.RS

sets one bit in a bitfield

.RE

.LP

.B

.br

.RS

clears one bit in a bitfield

.RE

.LP

.B

.br

.RS

toggles (i.e. reverses the state of) a bit in a bitfield

.RE

.LP

Printing bit arrays:

.LP

.B

.br

.RS

prints a bitfield as a series of ones and zeroes, left to right, the least

significant bit first

.RE

.LP

.B

.br

.RS

prints a bitfield as a series of ones and zeroes, left to right, the most

significant bit first

.RE

.LP

Logical operations with bit arrays:

.LP

.B

.br

.RS

performs bitwise AND over a pair of bitfields

.RE

.LP

.B

.br

.RS

reverses all bits in a bitfield and return the result in a new bitfield

.RE

.LP

.B

.br

.RS

reverses all bits in an existing bitfield

.RE

.LP

.B

.br

.RS

performs bitwise inclusive OR over a pair of bitfields

.RE

.LP

.B

.br

.RS

performs bitwise exclusive OR over a pair of bitfields

.RE

.LP

.B

.br

.RS

compares two bitfields and returns 0 if same or non-zero and error

message if different

.RE

.LP

Bitfield-to-something converters:

.LP

.B

.br

.RS

converts a bitfield structure into an array of unsigned chars

.RE

.LP

.B

.br

.RS

converts into a character string of '1's and '0's

.RE

.LP

.B

.br

.RS

converts into an array of short integers

.RE

.LP

.B

.br

.RS

converts into an array of integers

.RE

.LP

.B

.br

.RS

converts into an array of long integers

.RE

.LP

.B

.br

.RS

converts into an array of long long integers

.RE

.LP

.B

.br

.RS

converts into an array of uint8_t

.RE

.LP

.B

.br

.RS

converts into an array of uint16_t

.RE

.LP

.B

.br

.RS

converts into an array of uint32_t

.RE

.LP

.B

.br

.RS

converts into an array of uin64_t

.RE

.LP

"In-place" bitfield-to-something converters are same as above, except that

instead of creating a new array, these functions fill an existing one:

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

Something-to-bitfield converters:

.LP

.B

.br

.RS

converts an array of unsigned chars into a bitfield structure

.RE

.LP

.B

.br

.RS

converts a character string of '1's and '0's

.RE

.LP

.B

.br

.RS

converts an array of short integers

.RE

.LP

.B

.br

.RS

converts an array of integers

.RE

.LP

.B

.br

.RS

converts an array of long integers

.RE

.LP

.B

.br

.RS

converts an array of long long integers

.RE

.LP

.B

.br

.RS

converts an array of uint8_t

.RE

.LP

.B

.br

.RS

converts an array of uint16_t

.RE

.LP

.B

.br

.RS

converts an array of uint32_t

.RE

.LP

.B

.br

.RS

converts an array of uint64_t

.RE

.LP

"In-place" something-to-bitfield converters are same as above, except that

instead of creating a new bitfield, these functions fill an existing one:

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

.B

.RE

.LP

Miscellaneous:

.LP

.B

.br

.RS

.LP

obtains the number of bits of a bitfield

.RE

Vitalie CIUBOTARU