Index: /trunk/psLib/src/collections/Makefile =================================================================== --- /trunk/psLib/src/collections/Makefile (revision 437) +++ /trunk/psLib/src/collections/Makefile (revision 438) @@ -13,4 +13,10 @@ psBitMask.o \ psSort.o \ + +INCLUDES = -I$(includedir) + +%.o: %.c + @echo " Compiling $<. " + $(CC) $(CFLAGS) $(INCLUDE_GLOBAL) $(INCLUDES) -c $< -o $@ libpsCollections.a: $(SRC_OBJS) Index: /trunk/psLib/src/collections/psBitMask.c =================================================================== --- /trunk/psLib/src/collections/psBitMask.c (revision 437) +++ /trunk/psLib/src/collections/psBitMask.c (revision 438) @@ -1,4 +1,21 @@ -#include "psBitMask.h" +/** @file psBitMask.c + * + * @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 + */ +/******************************************************************************/ +/* INCLUDE FILES */ +/******************************************************************************/ #include #include @@ -6,9 +23,34 @@ #include -static char* getByte(int bit, const psBitMask* inMask); -static char mask(int bit); +#include "psBitMask.h" +//#include "psMemory.h" +/*****************************************************************************/ +/* FUNCTION IMPLEMENTATION - LOCAL */ +/*****************************************************************************/ +static char* getByte(int bit, const psBitMask *restrict inMask) +{ + int index = 0; + char *byte = 0; + index = bit/8; + byte = inMask->bits+index; + + return byte; +} + +static char mask(int bit) +{ + char mask = 0x01; + mask = mask << (bit%8); + + return mask; +} + +/*****************************************************************************/ +/* FUNCTION IMPLEMENTATION - PUBLIC */ +/*****************************************************************************/ psBitMask* psBitMaskAlloc(int n) { +// psBitMask *newObj = (psBitMask*)psAlloc(sizeof(psBitMask)); psBitMask *newObj = (psBitMask*)malloc(sizeof(psBitMask)); newObj->n = n; @@ -43,5 +85,6 @@ } -psBitMask* psBitMaskOp(psBitMask *outMask, const psBitMask *restrict inMask1, char *operator, const psBitMask *restrict inMask2) +psBitMask* psBitMaskOp(psBitMask *outMask, const psBitMask *restrict inMask1, char *operator, + const psBitMask *restrict inMask2) { int i = 0; @@ -118,21 +161,2 @@ return outString; } - -/* 0 based index of byte array's byte that contains containing bit */ -static char* getByte(int bit, const psBitMask* inMask) -{ - int index = 0; - char *byte = 0; - index = bit/8; - byte = inMask->bits+index; - - return byte; -} - -static char mask(int bit) -{ - char mask = 0x01; - mask = mask << (bit%8); - - return mask; -} Index: /trunk/psLib/src/collections/psBitMask.h =================================================================== --- /trunk/psLib/src/collections/psBitMask.h (revision 437) +++ /trunk/psLib/src/collections/psBitMask.h (revision 438) @@ -1,13 +1,128 @@ +/** @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 Index: /trunk/psLib/src/collections/psSort.c =================================================================== --- /trunk/psLib/src/collections/psSort.c (revision 437) +++ /trunk/psLib/src/collections/psSort.c (revision 438) @@ -1,4 +1,26 @@ -#include "psArray.h" -#include "psSort.h" +/** @file psSort.h + * + * @brief Sorts an array of floats + * + * The psSort functions use the qsort() stdlib function with a user-defined callback to sort an array of + * floats. The qsort function requires the starting point of the array, number of elements in the array, size + * of each element, and a pointer to a callback comparison function. Once called, qsort() will sort the array + * contents in ascending order according to the comparison function. The comparison function is called with + * two arguments that point to the objects being compared - in this case two floats. The comparison function + * must return an integer less than, equal to, or greater than zero if the first argument is considered to be + * respectively less than, equal to, or greater than the second. If two members compare as equal, their order + * in the sorted array is undefined. + * + * @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 + */ + +/******************************************************************************/ +/* INCLUDE FILES */ +/******************************************************************************/ #include @@ -7,21 +29,87 @@ #include #include -/* qsort - sorts an array */ -/* The qsort() function sorts an array with nmemb elements of size size. - The base argument points to the start of the array. - - The contents of the array are sorted in ascending order according to a - comparison function pointed to by compar, which is called with two - arguments that point to the objects being compared. - - The comparison function must return an integer less than, equal to, or - greater than zero if the first argument is considered to be respec- - tively less than, equal to, or greater than the second. If two members - compare as equal, their order in the sorted array is undefined. -*/ -static int psCompare(const void *x, const void *y); - - -psFloatArray *psSort(psFloatArray *restrict outArray, const psFloatArray *restrict inArray) + +#include "psArray.h" +#include "psSort.h" + +/******************************************************************************/ +/* DEFINE STATEMENTS */ +/******************************************************************************/ + +// None + +/******************************************************************************/ +/* TYPE DEFINITIONS */ +/******************************************************************************/ + +// None + +/*****************************************************************************/ +/* GLOBAL VARIABLES */ +/*****************************************************************************/ + +// None + +/*****************************************************************************/ +/* FILE STATIC VARIABLES */ +/*****************************************************************************/ + +// None + +/*****************************************************************************/ +/* FUNCTION IMPLEMENTATION - LOCAL */ +/*****************************************************************************/ + +/** Private callback comparison function to compare two floats. + * + * The comparison function is called by qsort() with two arguments that point to the objects being + * compared. The comparison function must return an integer less than, equal to, or greater than zero if + * the first argument is considered to be respectively less than, equal to, or greater than the second. If + * two members compare as equal, their order in the sorted array is undefined. + * + * @return int: Result of comparsion (-1, 0, or 1). + */ + +static int psCompare( + const void *x, /**< First float to compare. */ + const void *y /**< Second float to compare. */ +) +{ + float *item1 = NULL; + float *item2 = NULL; + + if(x == NULL || y == NULL) { + printf("Null input argument\n"); + } + + item1 = (float*)x; + item2 = (float*)y; + + if(item1 == NULL || item2 == NULL) { + printf("Improper cast to float\n"); + } + + if(*item1 < *item2) { + return -1; + } + else if(*item1 > *item2) { + return 1; + } + else { + return 0; + } +} + +/** Sort an array of floats. + * + * Sorts an array of floats in ascendin order with the qsort() stdlib function. + * + * @return psFloatArray*: Pointer to sorted psFloatArray. + */ + +psFloatArray *psSort( + psFloatArray *restrict outArray, /**< Sorted output array. */ + const psFloatArray *restrict inArray /**< Input array to sort. */ +) { int inN = 0; @@ -65,5 +153,16 @@ } -psIntArray *psSortIndex(psIntArray *restrict outArray, const psFloatArray *restrict inArray) +/** Creates an array of indices based on sort odred of float array. + * + * Sorts an array of floats and creates an integer array holding indices of sorted float values based on + * pre-sort index positions. + * + * @return psIntArray*: Pointer to psIntArray of sorted indices. + */ + +psIntArray *psSortIndex( + psIntArray *restrict outArray, /**< Output array of sorted indices. */ + const psFloatArray *restrict inArray /**< Input array to be sorted. */ +) { int inN = 0; @@ -117,29 +216,2 @@ return outArray; } - -static int psCompare(const void *x, const void *y) -{ - float *item1 = NULL; - float *item2 = NULL; - - if(x == NULL || y == NULL) { - printf("Null input argument\n"); - } - - item1 = (float*)x; - item2 = (float*)y; - - if(item1 == NULL || item2 == NULL) { - printf("Improper cast to float\n"); - } - - if(*item1 < *item2) { - return -1; - } - else if(*item1 > *item2) { - return 1; - } - else { - return 0; - } -}