The bitarray library contains data types and functions supporting the creation and manipulation of arbitrary length arrays of bits.
bit_array_t is the type used to store an array of bits. The
underlying array is hidden from direct access, but is implemented as an
array of unsigned chars where bit 0 is the most significant bit
of char 0, and the last bit is the least significant (non-spare) bit of the
greatest array index. bit_array_t elements are created using
the the smallest array of unsigned char capable of containing
the specified number of bits.
Example:
An array of 20 bits (0 through 19) with 8 bit unsigned
chars requires 3 unsigned
chars (0 through 2) to store all the bits.
| char | 0 | 1 | 2 | |||||||||||||||||||||
| bit | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | X | X | X | X | ||||||||||
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | X | X | X | X | |
Declaration:
bit_array_t *BitArrayCreate(const unsigned int bits);
Description:
This function allocates a bit array large enough to contain the specified number of bits. The contents of the array are not initialized.
Parameters:
bits - the number of bits in the array to be
allocated.
Effects:
This function allocates a bit array from the heap, or sets
errno on failure.
Returned:
A pointer to allocated the bit array or NULL if the array
may not be allocated. errno will be set in the event that
the array may not be allocated.
Declaration:
void BitArrayDestroy(bit_array_t *ba);
Description:
This function frees the memory allocated for a bit array.
Parameters:
ba - A pointer to the bit array to be freed.
Effects:
The memory pointed to by the bit array structure is freed.
Returned:
None
Declaration:
int BitArrayCopy(const bit_array_t *const dest, const bit_array_t
*const src);
Description:
This function copies the contents of a source bit array into the
destination. If the two arrays are not the same size or either array
pointer is NULL, a copy will not take place and
errno will be set to EPERM.
Parameters:
dest - A pointer to the destination bit array
src - A pointer to the source bit array
Effects:
The contents of the source bit array are copied to the destination bit array.
Returned:
0 for success, -1 for failure. errno will be set in the
event of a failure.
Declaration:
bit_array_t *BitArrayDuplicate(const bit_array_t *const src);
Description:
This function creates a bit array and copies the contents of the bit array passed as a parameter into the newly created array. A pointer to the duplicate array is returned.
Parameters:
src - A pointer to the bit array to be duplicated
Effects:
A duplicate of the source bit array is created.
Returned:
A Pointer to duplicate of source or NULL for failure.
errno will be set in the event that the array may not
be duplicated.
Declaration:
void BitArraySetAll(const bit_array_t *const ba);
Description:
This function sets every bit to 1 in the bit array passed as a
parameter. This is function uses UCHAR_MAX, so it is
crucial that the machine implementation of unsigned char
utilizes all the bits in the memory allocated for an unsigned
char.
Parameters:
ba - A pointer to the bit array to be set.
Effects:
Each of the bits used in the bit array are set to 1. Unused (spare) bits are set to 0.
Returned:
None
Declaration:
void BitArrayClearAll(const bit_array_t *const ba);
Description:
This function sets every bit to 0 in the bit array passed as a parameter.
Parameters:
ba - A pointer to the bit array to be cleared.
Effects:
Each of the bits used in the bit array are set to 0.
Returned:
None
Declaration:
int BitArraySetBit(const bit_array_t *const ba, const unsigned
int bit);
Description:
This function sets the specified bit in the bit array passed as a parameter to 1.
Parameters:
ba - A pointer to the bit array
bit - The index of bit to set
Effects:
The specified bit in the bit array is set to 1.
Returned:
0 for success, -1 for failure. errno will be set in the
event of a failure. If bit is beyond the bounds of the
bit array errno will be set to ERANGE.
Declaration:
int BitArrayClearBit(const bit_array_t *const ba, const unsigned
int bit);
Description:
This function sets the specified bit in the bit array passed as a parameter to 0.
Parameters:
ba - A pointer to the bit array
bit - The index of bit to clear
Effects:
The specified bit in the bit array is set to 0.
Returned:
0 for success, -1 for failure. errno will be set in the
event of a failure. If bit is beyond the bounds of the
bit array errno will be set to ERANGE.
Declaration:
int BitArrayTestBit(const bit_array_t *const ba, const unsigned
int bit);
Description:
This function tests the specified bit in the bit array passed as a parameter. A non-zero will be returned if the tested bit is set.
Parameters:
ba - A pointer to the bit array
bit - The index of bit to test
Effects:
None
Returned:
Non-zero if the bit is set, otherwise 0. This function does not validate the input. Tests on invalid input will produce unknown results.
Declaration:
int BitArrayAnd(const bit_array_t *const dest,
const bit_array_t *const src1,
const bit_array_t *const src2);
Description:
This function performs a bitwise AND on two bit arrays, storing the
results in a third bit array. All array pointers must be
non-NULL and all arrays must be the same size. Otherwise
no operation will take place and errno will be set to
EPERM.
Parameters:
dest - A pointer to the destination bit array
src1 - A pointer to the first source bit array
src2 - A pointer to the second source bit array
Effects:
dest will contain the results of a bitwise AND of
src1 and src2 unless one array pointer is
NULL or arrays are different sizes.
Returned:
0 for success, -1 for failure. errno will be set to
EPERM the event of a failure.
Declaration:
int BitArrayOr(const bit_array_t *const dest,
const bit_array_t *const src1,
const bit_array_t *const src2);
Description:
This function performs a bitwise OR on two bit arrays, storing the
results in a third bit array. All array pointers must be
non-NULL and all arrays must be the same size. Otherwise
no operation will take place and errno will be set to
EPERM.
Parameters:
dest - A pointer to the destination bit array
src1 - A pointer to the first source bit array
src2 - A pointer to the second source bit array
Effects:
dest will contain the results of a bitwise OR of
src1 and src2 unless one array pointer is
NULL or arrays are different sizes.
Returned:
0 for success, -1 for failure. errno will be set to
EPERM the event of a failure.
Declaration:
int BitArrayXor(const bit_array_t *const dest,
const bit_array_t *const src1,
const bit_array_t *const src2);
Description:
This function performs a bitwise XOR on two bit arrays, storing the
results in a third bit array. All array pointers must be
non-NULL and all arrays must be the same size. Otherwise
no operation will take place and errno will be set to
EPERM.
Parameters:
dest - A pointer to the destination bit array
src1 - A pointer to the first source bit array
src2 - A pointer to the second source bit array
Effects:
dest will contain the results of a bitwise XOR of
src1 and src2 unless one array pointer is
NULL or arrays are different sizes.
Returned:
0 for success, -1 for failure. errno will be set to
EPERM the event of a failure.
Declaration:
int BitArrayNot(const bit_array_t *const dest,
const bit_array_t *const src);
Description:
This function performs a bitwise NOT on one bit array, storing the
results in another bit array. All array pointers must be
non-NULL and all arrays must be the same size. Otherwise
no operation will take place and errno will be set to
EPERM.
Parameters:
dest - A pointer to the destination bit array
src - A pointer to the source bit array
Effects:
dest will contain the results of a bitwise NOT of
src and unless one array pointer is NULL or
the arrays are different sizes.
Returned:
0 for success, -1 for failure. errno will be set to
EPERM the event of a failure.
Declaration:
int BitArrayShiftLeft(const bit_array_t *const ba, unsigned int
shifts);
Description:
This function shifts the bits in a bit array to the left by the amount
of bit positions specified. If the array pointer is NULL,
nothing will be shifted and errno will be set to
EPERM.
Parameters:
ba - A pointer to the bit array to be shifted
shifts - The number of bit positions to shift to the left
Effects:
The bit array data pointed to by ba is shifted to the left.
New bits shifted in will be set to 0.
Returned:
0 for success, -1 for failure. errno will be set to
EPERM the event of a failure.
Declaration:
int BitArrayShiftRight(const bit_array_t *const ba, unsigned int
shifts);
Description:
This function shifts the bits in a bit array to the right by the amount
of bit positions specified. If the array pointer is NULL,
nothing will be shifted and errno will be set to
EPERM.
Parameters:
ba - A pointer to the bit array to be shifted
shifts - The number of bit positions to shift to the right
Effects:
The bit array data pointed to by ba is shifted to the
right. New bits shifted in will be set to 0.
Returned:
0 for success, -1 for failure. errno will be set to
EPERM the event of a failure.
Declaration:
int BitArrayIncrement(const bit_array_t *const ba);
Description:
This function increments a bit array as if it is an unsigned value of
the size of the bit array. An overflow will cause the value to wrap
around. If the array pointer is NULL, nothing will be
incremented and errno will be set to EPERM.
Parameters:
ba - A pointer to the bit array to be incremented
Effects:
The bit array will contain the results of an increment operation performed on itself.
Returned:
0 for success, -1 for failure. errno will be set to
EPERM the event of a failure.
Declaration:
int BitArrayDecrement(const bit_array_t *const ba);
Description:
This function increments a bit array as if it is an unsigned value of
the size of the bit array. An underflow will cause the value to wrap
around. If the array pointer is NULL, nothing will be
decremented and errno will be set to EPERM.
Parameters:
ba - A pointer to the bit array to be decremented
Effects:
The bit array will contain the results of an decrement operation performed on itself.
Returned:
0 for success, -1 for failure. errno will be set to
EPERM the event of a failure.
Declaration:
int BitArrayCompare(const bit_array_t *ba1, const bit_array_t
*ba2);
Description:
This function compares two bit arrays.
Parameters:
ba1 - A pointer to a bit array
ba2 - A pointer to a bit array
Effects:
None
Returned:
< 0 if ba1 < ba2 or ba1
is shorter than ba2
0 if ba1 == ba2
> 0 if ba1 > ba2 or ba1
is longer than ba2
Declaration:
void BitArrayDump(const bit_array_t *const ba, FILE *outFile);
Description:
This function dumps the contents of a bit array to the specified output stream. The format of the dump is a series of bytes represented in hexadecimal.
Parameters:
ba - A pointer to the bit array to be dumped
outFile - A pointer to output steam to be used. If
NULL, then stdout will be used.
Effects:
A hexadecimal dump of the bit array is sent to outFile.
Returned:
None
NOTE: This function only works with 8-bit
char.
Declaration:
void *BitArrayGetBits(const bit_array_t *const ba);
Description:
This function returns a pointer to the array of unsigned
char containing actual bits. This function should be used
with caution. Manipulating the array of bits outside of the bit array
functions may have adverse effects.
Parameters:
ba - A pointer to the bit array
Effects:
None
Returned:
A pointer to the array containing the bits.