Index: trunk/psLib/src/collections/psBitSet.h =================================================================== --- trunk/psLib/src/collections/psBitSet.h (revision 542) +++ trunk/psLib/src/collections/psBitSet.h (revision 578) @@ -1,20 +1,21 @@ -/** @file psBitMask.h +/** @file psBitSet.h * - * @brief Creates an array of bits of arbitrary length. + * @brief Creates an array of bytes of arbitrary length for storing individual bits. * - * Bit masks are useful for turning options on and off. This module provides functions to create an array of - * bits of arbitrary length and manipulate them with basic binary operations. A print function is also - * provided to display the entire set of bits in binary form. + * Bit masks are useful tools for toggling various flags and options. This set of functions module provides + * a mechanism to create an array of bits of arbitrary length and manipulate them with basic binary + * operations. A print function is also provided to display the entire set of bits in binary format as a + * string. * * @author Ross Harman, MHPCC * - * @version $Revision: 1.1 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-04-28 17:47:56 $ + * @version $Revision: 1.2 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-05-05 20:43:57 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii */ -#ifndef PSBITMASK_H -#define PSBITMASK_H +#ifndef PSBITSET_H +#define PSBITSET_H /******************************************************************************/ @@ -22,8 +23,8 @@ /******************************************************************************/ -/** Struct containing array of bits and its length. +/** Struct containing array of bytes to hold bit data and corresponding array length. * * The bits in the struct are assembled in as an array of bytes with eight bits per byte. The bits are - * arranged with the LSB in first position of the first array element. + * arranged with the LSB in first (right most) position of the first array element. */ typedef struct @@ -32,5 +33,5 @@ char *bits; /**< Aray of bytes holding bits */ } -psBitMask; +psBitSet; /*****************************************************************************/ @@ -38,92 +39,73 @@ /*****************************************************************************/ -/** Allocate a psBitMask. +/** Allocate a psBitSet. * - * Create a psBitMask with number of bytes specified by the user. All bits are set to zero upon allocation. + * Create a psBitSet with the number of bytes specified by the user. All bits are set to zero upon + * allocation. * - * @return psBitMask*: Pointer to struct containing array of bits and size of array. + * @return psBitSet*: Pointer to struct containing array of bits and size of array. */ -psBitMask* psBitMaskAlloc( - int n /**< Number of bytes in array */ +psBitSet* psBitSetAlloc( + int n /**< Number of bytes in psBitSet array */ ); -/** Free a psBitMask +/** Free a psBitSet * - * Deletes a psBitMask array and its byte count. + * Deletes a psBitSet array. */ -void psBitMaskFree( - psBitMask *restrict inMask /**< Pointer to psBitMask struct to be deleted. */ +void psBitSetFree( + psBitSet *restrict inMask /**< Pointer to psBitSet to be deleted. */ ); /** Set a bit. * - * Sets a bit at a given bit location. The bit is set based on a zero index with the first bit set in - * the zero bit slot of the zero element of the byte array. As an example, setting bit 3 in an array with - * two elements would result in an psBitMask that looks like 00000000 00001000. + * Sets a bit at a given bit location, either one or zero. The bit is set based on a zero index with the + * first bit set in the zero bit slot of the zero element of the byte array. As an example, setting bit 3 in + * an array with two elements would result in an psBitSet that looks like 00000000 00001000. * - * @return psBitMask*: Pointer to struct containing array with bit set. + * @return psBitSet*: Pointer to struct containing psBitSet. */ -psBitMask* psBitMaskSet( - psBitMask *inMask, /**< Pointer to struct to be set. */ - int bit /**< Bit to be set. */ +psBitSet* psBitSetSet( + psBitSet *restrict inMask, /**< Pointer to psBitSet to be set. */ + int bit /**< Bit to be set. */ ); /** Test the value of a bit. * - * Prints the value of a bit at a given bit location. The bit printed based on a zero index with the first - * bit set in the zero bit slot of the zero element of the byte array. As an example, testing bit 3 in an array with - * two elements that looks like 00000000 00001000 would retrun a value of one, since that value was already set. + * Prints the value of a bit at a given bit location, either one or zero. The resulting bit is based on a + * zero index format with the first bit set in the zero bit slot of the zero element of the byte array + * As an example, testing bit 3 in a psBitSet with two bytes that looks like 00000000 00001000 would return a + * value of one, since that is the value that was set. * * @return int: Value of bit, either one or zero. */ -int psBitMaskTest( - const psBitMask *inMask, /**< Pointer to struct to be tested. */ - int bit /**< Bit to be tested. */ +int psBitSetTest( + const psBitSet *restrict inMask, /**< Pointer psBitSet to be tested. */ + int bit /**< Bit to be tested. */ ); -/** Perform a binary operation on two psBitMasks +/** Perform a binary operation on two psBitSets * - * Perform an AND, OR, or XOR on two psBitMasks. If the BitMasks are not the same size, the operation will not - * be performed and an error message will be printed. + * Perform an AND, OR, or XOR on two psBitSets. If the BitMasks are not the same size, the operation will not + * be performed and an error message will be logged. * - * @return psBitMask*: Pointer to struct containing result of binary operation. + * @return psBitSet*: Pointer to struct containing result of binary operation. */ -psBitMask* psBitMaskOp( - psBitMask *outMask, /**< Resulting psBitMask from binary operation */ - const psBitMask *restrict inMask1, /**< First psBitMask on which to operate */ - char *operator, /**< Bit operation */ - const psBitMask *restrict inMask2 /**< First psBitMask on which to operate */ +psBitSet* psBitSetOp( + psBitSet *restrict outMask, /**< Resulting psBitSet from binary operation */ + const psBitSet *restrict inMask1, /**< First psBitSet on which to operate */ + char *operator, /**< Bit operation */ + const psBitSet *restrict inMask2 /**< First psBitSet on which to operate */ ); -/** Print the contents of a psBitMask. +/** Convert the psBitSet to a string of ones and zeros. * - * Prints the contents of a psBitMask in its binary form of ones and zeros. The LSB is the left-most chracter. + * Converts the contents of a psBitSet to a string representation of its binary form of ones and zeros. The + * LSB is the right-most chracter. Each set of eight characters represents one byte. * - * @return char*: Pointer to character array containing binary formatted data. + * @return char*: Pointer to character array containing string data. */ -char *psBitMaskToString( - const psBitMask *restrict inMask /**< psBitMask to print */ -); - -/** Private function to return a byte. - * - * Finds the byte containing the bit within the byte array. - * - * @return char*: Pointer to byte in which bit is contained. - */ -static char* getByte( - int bit, /**< Bit to index to search. */ - const psBitMask *restrict inMask /**< psBitMask to search. */ -); - -/** Private function to create a mask. - * - * Creates an eight bit mask with the given bit set. All other bits in the byte are zero. The input bit uses - * zero-based indexing, and is the cumulitive index within the array, not the localized byte's bit position. - * - * @return char*: Pointer to byte in which bit is contained. - */ -static char mask( - int bit /**< Bit to set within mask */ +char *psBitSetToString( + const psBitSet *restrict inMask /**< psBitSet to convert */ );