psLookupTable.h

Go to the documentation of this file.

/** @file  psLookupTable.h
*
*  @brief This file defines the structure and functions for table lookups.
*
*  @ingroup fileUtils
*
*  @author Ross Harman, MHPCC
*
*  @version $Revision: 1.4 $ $Name: rel5_0 $
*  @date $Date: 2005/02/17 21:54:09 $
*
*  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
*/

#ifndef PS_LOOKUPTABLE_H
#define PS_LOOKUPTABLE_H

#include "psType.h"
#include "psVector.h"
#include "psArray.h"


/** Lookup table structure
 *
 *  Holds table data read from external data files.
 *
 */
typedef struct
{
    const char *fileName;              ///< Name of file with table
    psU64 numRows;                     ///< Number of table rows
    psU64 numCols;                     ///< Number of table columns
    psF64 validFrom;                   ///< Lower bound for rable read
    psF64 validTo;                     ///< Upper bound for table read
    psVector *index;                   ///< Vector of independent index values
    psArray *values;                   ///< Array of dependent table values corresponding to index values
}
psLookupTable;


/** Lookup table lookup status and error conditions
 *
 *  Success, failure, and status conditions for table lookups.
 */
typedef enum {
    PS_LOOKUP_SUCCESS             = 0x0000,        ///< Table lookup succeeded
    PS_LOOKUP_PAST_TOP            = 0x0101,        ///< Lookup off top of table
    PS_LOOKUP_PAST_BOTTOM         = 0x0102,        ///< Lookup off bottom of table
    PS_LOOKUP_ERROR               = 0x0104         ///< Any other type of lookup error
} psLookupStatusType;

/** Lookup table parse status and error conditions
 *
 *  Success, failure, and status conditions for table parsing.
 */
typedef enum {
    PS_PARSE_SUCCESS              = 0x0000,        ///< Table lookup succeeded
    PS_PARSE_ERROR_TYPE           = 0x0101,        ///< Error parsing type
    PS_PARSE_ERROR_VALUE          = 0x0102,        ///< Error parsing numerical value
    PS_PARSE_ERROR_GENERAL        = 0x0104         ///< Any other type of lookup error
}psParseErrorType;

/** Allocator for psLookupTable struct
 *
 *  Allocates a new psLookupTable struct.
 *
 *  @return psLookupTable*     New psLookupTable struct.
 */
psLookupTable* psLookupTableAlloc(
    const char *fileName,           ///< Name of file to read
    psF64 validFrom,                ///< Lower bound for rable read
    psF64 validTo                   ///< Upper bound for table read
);

/** Read lookup table
 *
 *  Reads a lookup table and fills corresponding psLookupTable struct.
 *
 *  @return psLookupTable*     New psLookupTable struct.
 */
psLookupTable* psLookupTableRead(
    psLookupTable *table            ///< Table to read
);

/** Lookup and interpolate value from table.
 *
 *  Interpolates value from table. Sets status bit for success or one of several possible failure
 *  conditions.
 *
 *  @return psLookupTable*     New psLookupTable struct
 */
psF64 psLookupTableInterpolate(
    psLookupTable *table,           ///< Table with data
    psF64 index,                    ///< Value to be interpolated
    psU64 column,                   ///< Column in table to be interpolated
    psLookupStatusType *status      ///< Status of lookup
);

/** Lookup and interpolate all values from table.
 *
 *  Interpolates all values from table. Sets status bit for success or one of several possible failure
 *  conditions.
 *
 *  @return psLookupTable*     New psLookupTable struct
 */
psVector* psLookupTableInterpolateAll(
    psLookupTable *table,           ///< Table with data
    psF64 index,                    ///< Value to be interpolated
    psVector *stats                 ///< Vector of status for each lookup
);

#endif

---