Logo Search packages:      
Sourcecode: udunits version File versions  Download package

converter.h

/*
 * Copyright 2008, 2009 University Corporation for Atmospheric Research
 *
 * This file is part of the UDUNITS-2 package.  See the file LICENSE
 * in the top-level source-directory of the package for copying and
 * redistribution conditions.
 */
/*
 * Public header-file for the Unidata units(3) library.
 */

#ifndef CV_CONVERTER_H_INCLUDED
#define CV_CONVERTER_H_INCLUDED

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef union cv_converter    cv_converter;

/*
 * Returns the trivial converter (i.e., y = x).
 * When finished with the converter, the client should pass the converter to
 * cv_free().
 * RETURNS:
 *    The trivial converter.
 */
cv_converter*
cv_get_trivial(void);

/*
 * Returns the reciprocal converter (i.e., y = 1/x).
 * When finished with the converter, the client should pass the converter to
 * cv_free().
 * RETURNS:
 *    The reciprocal converter.
 */
cv_converter*
cv_get_inverse(void);

/*
 * Returns a scaling converter (i.e., y = ax).
 * When finished with the converter, the client should pass the converter to
 * cv_free().
 * RETURNS:
 *    The scaling converter.
 */
cv_converter*
cv_get_scale(
    const double  slope);

/*
 * Returns a converter that adds a number to values (i.e., y = x + b).
 * When finished with the converter, the client should pass the converter to
 * cv_free().
 * ARGUMENTS:
 *    intercept   The number to be added.
 * RETURNS:
 *    NULL  Necessary memory couldn't be allocated.
 *    else  A converter that adds the given number to values.
 */
cv_converter*
cv_get_offset(
    const double  intercept);

/*
 * Returns a Galilean converter (i.e., y = ax + b).
 * When finished with the converter, the client should pass the converter to
 * cv_free().
 * ARGUMENTS:
 *    slope       The number by which to multiply values.
 *    intercept   The number to be added.
 * RETURNS:
 *    NULL  Necessary memory couldn't be allocated.
 *    else  A Galilean converter corresponding to the inputs.
 */
cv_converter*
cv_get_galilean(
    const double  slope,
    const double  intercept);

/*
 * Returns a logarithmic converter (i.e., y = log(x) in some base).
 * When finished with the converter, the client should pass the converter to
 * cv_free().
 * ARGUMENTS:
 *    base        The logarithmic base (e.g., 2, M_E, 10).  Must be
 *                      greater than one.
 * RETURNS:
 *    NULL        "base" is not greater than one or necessary
 *                memory couldn't be allocated.
 *    else        A logarithmic converter corresponding to the inputs.
 */
cv_converter*
cv_get_log(
    const double  base);

/*
 * Returns an exponential converter (i.e., y = pow(b, x) in some base "b").
 * When finished with the converter, the client should pass the converter to
 * cv_free().
 *
 * Arguments:
 *    base        The desired base.  Must be positive.
 * Returns:
 *    NULL        "base" is invalid or necessary memory couldn't be
 *                allocated.
 *    else        An exponential converter corresponding to the inputs.
 */
cv_converter*
cv_get_pow(
    const double  base);

/*
 * Returns a converter corresponding to the sequential application of two
 * other converters.
 * ARGUMENTS:
 *    first The converter to be applied first.
 *    second      The converter to be applied second.
 * RETURNS:
 *    NULL  Either "first" or "second" is NULL or necessary memory couldn't
 *          be allocated.
 *      else    A converter corresponding to the sequential application of the
 *              given converters.  If one of the input converters is the trivial
 *              converter, then the returned converter will be the other input
 *              converter.
 */
cv_converter*
cv_combine(
    cv_converter* const first,
    cv_converter* const second);

/*
 * Frees resources associated with a converter.
 * ARGUMENTS:
 *    conv  The converter to have its resources freed or NULL.
 */
void
cv_free(
    cv_converter* const conv);

/*
 * Converts a float.
 * ARGUMENTS:
 *    converter   The converter.
 *    value       The value to be converted.
 * RETURNS:
 *    The converted value.
 */
float
cv_convert_float(
    const cv_converter* converter,
    const float         value);

/*
 * Converts a double.
 * ARGUMENTS:
 *    converter   The converter.
 *    value       The value to be converted.
 * RETURNS:
 *    The converted value.
 */
double
cv_convert_double(
    const cv_converter* converter,
    const double  value);

/*
 * Converts an array of floats.
 * ARGUMENTS:
 *    converter   The converter.
 *    in          The values to be converted.
 *    count       The number of values to be converted.
 *    out         The output array for the converted values.  May
 *                be the same array as "in" or overlap it.
 * RETURNS:
 *    NULL  "out" is NULL.
 *    else  A pointer to the output array.
 */
float*
cv_convert_floats(
    const cv_converter* converter,
    const float* const  in,
    const size_t  count,
    float*        out);

/*
 * Converts an array of doubles.
 * ARGUMENTS:
 *    converter   The converter.
 *    in          The values to be converted.
 *    count       The number of values to be converted.
 *    out         The output array for the converted values.  May
 *                be the same array as "in" or overlap it.
 * RETURNS:
 *    NULL  "out" is NULL.
 *    else  A pointer to the output array.
 */
double*
cv_convert_doubles(
    const cv_converter* converter,
    const double* const in,
    const size_t  count,
    double*       out);

/*
 * Returns a string representation of a converter.
 * ARGUMENTS:
 *    conv        The converter.
 *    buf         The buffer into which to write the expression.
 *    max         The size of the buffer.
 *    variable    The string to be used as the input value for the
 *                converter.
 * RETURNS
 *    <0    An error was encountered.
 *    else  The number of bytes formatted excluding the terminating null.
 */
int
cv_get_expression(
    const cv_converter* const conv,
    char* const               buf,
    size_t              max,
    const char* const         variable);

#ifdef __cplusplus
}
#endif

#endif

Generated by  Doxygen 1.6.0   Back to index