General

group harp_general

The HARP General module contains all general and miscellaneous functions and procedures of HARP.

Defines

HARP_NUM_DATA_TYPES
HARP_NUM_DIM_TYPES

Typedefs

typedef enum harp_data_type_enum harp_data_type
typedef union harp_scalar_union harp_scalar
typedef union harp_array_union harp_array
typedef enum harp_dimension_type_enum harp_dimension_type

Enums

enum harp_data_type_enum

Values:

harp_type_int8

BYTE

harp_type_int16

INTEGER

harp_type_int32

LONG

harp_type_float

FLOAT

harp_type_double

DOUBLE

harp_type_string

STRING

enum harp_dimension_type_enum

Values:

harp_dimension_independent = -1
harp_dimension_time
harp_dimension_latitude
harp_dimension_longitude
harp_dimension_vertical
harp_dimension_spectral

Functions

int harp_set_udunits2_xml_path(const char *path)

Set the location of the udunits2 unit conversion xml configuration file.

This function should be called before harp_init() is called.

The HARP C library uses the udunits2 library to perform unit conversions. The xml configuration files for udunits2 are included with a HARP installation and a default absolute path to these xml files is built into the library.

If the HARP installation ends up in a different location on disk compared to what was provided at build time then you will either need to set the UDUNITS2_XML_PATH environment variable or call one of the functions harp_set_udunits2_xml_path() or harp_set_udunits2_xml_path_conditional() to set the path programmatically.

The path should be an absolute path to the udunits2.xml file that was included with the HARP installation.

Specifying a path using this function will prevent HARP from using the UDUNITS2_XML_PATH environment variable. If you still want HARP to acknowledge the UDUNITS2_XML_PATH environment variable then use something like this in your code: 

if (getenv("UDUNITS2_XML_PATH") == NULL)
{
    harp_set_udunits2_xml_path("<your path>");
}

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • path: Absolute path to the udunits2.xml file

int harp_set_udunits2_xml_path_conditional(const char *file, const char *searchpath, const char *relative_location)

Set the location of the udunits2 xml configuration file based on the location of another file.

This function should be called before harp_init() is called.

The HARP C library uses the udunits2 library to perform unit conversions. The xml configuration files for udunits2 are included with a HARP installation and a default absolute path to the main xml file is built into the library.

If the HARP installation ends up in a different location on disk compared to what was provided at build time then you will either need to set the UDUNITS2_XML_PATH environment variable or call one of the functions harp_set_udunits2_xml_path() or harp_set_udunits2_xml_path_conditional() to set the path programmatically.

This function will try to find the file with filename file in the provided searchpath searchpath. The first directory in the searchpath where the file file exists will be appended with the relative location relative_location to determine the udunits2 xml path. If the file to search for could not be found in the searchpath then the HARP udunits2 xml path will not be set.

If the UDUNITS2_XML_PATH environment variable was set then this function will not perform a search or set the udunits2 xml path (i.e. the udunits2 xml path will be taken from the UDUNITS2_XML_PATH variable).

If you provide NULL for searchpath then the PATH environment variable will be used as searchpath. For instance, you can use harp_set_udunits2_xml_path_conditional(argv[0], NULL, “../somedir/udunits2.xml”) to set the udunits2 xml path to a location relative to the location of your executable.

The searchpath, if provided, should have a similar format as the PATH environment variable of your system. Path components should be separated by ‘;’ on Windows and by ‘:’ on other systems.

The relative_location parameter should point to the udunits2.xml file itself (and not the directory that the file is in).

Note that this function differs from harp_set_udunits2_xml_path() in that it will not modify the udunits2 xml path if the UDUNITS2_XML_PATH variable was set.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • file: Filename of the file to search for
  • searchpath: Search path where to look for the file file (can be NULL)
  • relative_location: Filepath relative to the directory from searchpath where file was found that provides the location of the udunits2.xml file.

int harp_convert_unit(const char *from_unit, const char *to_unit, long num_values, double *value)

Perform unit conversion on data

Apply unit conversion on a range of floating point values. Conversion will be performed in-place. If there is no conversion available from the current unit to the new unit then an error will be raised.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • from_unit: Existing unit of the data that should be converted (use udunits2 compliant units).
  • to_unit: Unit to which the data should be converted (use udunits2 compliant units).
  • num_values: Number of floating point values in value.
  • value: Array of floating point values that should be converted.

const char *harp_basename(const char *path)

Remove everything but the last pathname component from path.

Return
Pointer to the last pathname component of path, i.e. everything from the end of path up to the first pathname component separation character (‘’ or ‘/’ on Windows, ‘/’ otherwise).
Parameters
  • path: Path to compute the basename of.

const char *harp_get_data_type_name(harp_data_type data_type)

Returns the name of a data type.

Return
if the data type is known a string containing the name of the type, otherwise the string “unknown”.
Parameters
  • data_type: HARP basic data type

long harp_get_size_for_type(harp_data_type data_type)

Retrieve the byte size for a HARP data type.

Return
The size of the data type in bytes.
Parameters
  • data_type: Data type for which to retrieve the size.

harp_scalar harp_get_fill_value_for_type(harp_data_type data_type)

Retrieve the fill value for a HARP data type.

Return
The fill value for the data type.
Parameters
  • data_type: Data type for which to retrieve the fill value.

harp_scalar harp_get_valid_min_for_type(harp_data_type data_type)

Retrieve the minimum valid value for a HARP data type.

Return
The minimum valid value of the data type.
Parameters
  • data_type: Data type for which to retrieve the minimum valid value.

harp_scalar harp_get_valid_max_for_type(harp_data_type data_type)

Retrieve the maximum valid value for a HARP data type.

Return
The maximum valid value of the data type.
Parameters
  • data_type: Data type for which to retrieve the maximum valid value.

int harp_is_fill_value_for_type(harp_data_type data_type, harp_scalar value)

Test if value equals the fill value for the specified data type.

Return
  • 0, Value is not equal to the fill value.
  • 1, Value equals the fill value.
Parameters
  • data_type: Data type corresponding to the value of value.
  • value: Value to test.

int harp_is_valid_min_for_type(harp_data_type data_type, harp_scalar value)

Test if value equals the minimum valid value for the specified data type.

Return
  • 0, Value is not equal to the minimum valid value.
  • 1, Value equals the minimum valid value.
Parameters
  • data_type: Data type corresponding to the value of value.
  • value: Value to test.

int harp_is_valid_max_for_type(harp_data_type data_type, harp_scalar value)

Test if value equals the maximum valid value for the specified data type.

Return
  • 0, Value is not equal to the maximum valid value.
  • 1, Value equals the maximum valid value.
Parameters
  • data_type: Data type corresponding to the value of value.
  • value: Value to test.

int harp_isfinite(double x)

Find out whether a double value is a finite number (i.e. not NaN and not infinite).

Return
  • 1, The double value is a finite number.
  • 0, The double value is not a finite number.
Parameters
  • x: A double value.

int harp_isnan(double x)

Find out whether a double value equals NaN (Not a Number).

Return
  • 1, The double value equals NaN.
  • 0, The double value does not equal NaN.
Parameters
  • x: A double value.

double harp_nan(void)

Retrieve a double value that respresents NaN (Not a Number).

Return
The double value ‘NaN’.

int harp_isinf(double x)

Find out whether a double value equals inf (either positive or negative infinity).