Changeset 438 for trunk/psLib/src/collections/psBitMask.h

Timestamp:

Apr 16, 2004, 4:43:59 PM (22 years ago)

Author:

harman

Message:

Added Doxygen comments

File:

• trunk/psLib/src/collections/psBitMask.h (modified) (1 diff)

trunk/psLib/src/collections/psBitMask.h

@@ +1 @@
+/** @file  psBitMask.h
+ *
+ *  @brief Creates an array of bits of arbitrary length.
+ *
+ *  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.
+ *
+ *  @author Ross Harman, MHPCC
+ *   
+ *  @version $Revision: 1.2 $ $Name: not supported by cvs2svn $
+ *  @date $Date: 2004-04-17 02:43:59 $
+ *
+ *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
+ */
+ 
+#ifndef PSBITMASK_H
+#define PSBITMASK_H
+ 
+/******************************************************************************/
+/*  TYPE DEFINITIONS                                                          */
+/******************************************************************************/
+
+/** Struct containing array of bits and its 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.
+ */
 typedef struct {
-    int n;
-    char *bits;
+    int n;      /**< Number of bytes in the array */
+    char *bits; /**< Aray of bytes holding bits */
 } psBitMask;
 
-psBitMask* psBitMaskAlloc(int n);
-void psBitMaskFree(psBitMask *restrict inMask);
-psBitMask* psBitMaskSet(psBitMask *inMask, int bit);
-int psBitMaskTest(const psBitMask *inMask, int bit);
-psBitMask* psBitMaskOp(psBitMask *outMask, const psBitMask *restrict inMask1, char *operator, const psBitMask *restrict inMask2);
-char *psBitMaskToString(const psBitMask *restrict inMask);
-static char* getByte(int bit, const psBitMask* inMask);
-static char mask(int bit);
+/*****************************************************************************/
+/* FUNCTION PROTOTYPES                                                       */
+/*****************************************************************************/
+
+/** Allocate a psBitMask. 
+ *
+ *  Create a psBitMask with 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.
+ */
+psBitMask* psBitMaskAlloc(
+    int n   /**< Number of bytes in array */
+);
+
+/** Free a psBitMask 
+ *
+ *  Deletes a psBitMask array and its byte count.
+ */
+void psBitMaskFree(
+    psBitMask *restrict inMask  /**< Pointer to psBitMask struct 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.
+ *
+ *  @return  psBitMask*: Pointer to struct containing array with bit set.
+ */
+psBitMask* psBitMaskSet(
+    psBitMask *inMask, /**< Pointer to struct 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.
+ *
+ *  @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. */
+);
+
+/** Perform a binary operation on two psBitMasks
+ *
+ *  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.
+ *
+ *  @return  psBitMask*: 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 */
+);
+
+/** Print the contents of a psBitMask.
+ *
+ *  Prints the contents of a psBitMask in its binary form of ones and zeros. The LSB is the left-most chracter.
+ *
+ *  @return  char*: Pointer to character array containing binary formatted 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 */
+);
+
+#endif