Citrus C API Reference

CITRUS_UNIT_PLURAL_S

#define CITRUS_UNIT_PLURAL_S		0

This flag indicates that a unit's plural form is obtained by adding 's' to the end of the unit's name. An example would be "meter", for which the plural is "meters".

CITRUS_UNIT_PLURAL_ES

#define CITRUS_UNIT_PLURAL_ES		1

This flag indicates that a unit's plural form is obtained by adding 'es' to the end of the unit's name. An example would be "inch", for which the plural is "inches".

CITRUS_UNIT_PLURAL_SPECIAL

#define CITRUS_UNIT_PLURAL_SPECIAL	2

This flag indicates that a unit's plural form name is significantly different from the unit's singular form name. An example would be "foot", for which the plural is "feet".

citrus_initialize ()

int         citrus_initialize               (const char *configFile);

Initialize the Citrus library. At the moment, all this does is read the configuration file. The configuration file contains all of the dimensions, dimensional groups, and units. Without them, the library is relatively useless.

citrus_quantity_from_string ()

void*       citrus_quantity_from_string     (const char *src);

This creates an internal representation of a number with units that can be used to convert units, find the dimensional group of a given number, or find a canonical representation (in the unit system of your choice).

citrus_quantity_export_mathml ()

xmlNodePtr  citrus_quantity_export_mathml   (const void *quantity);

Return an XML tree containing MathML nodes describing the quantity.

These nodes have no parent document. This function will change in the near future. There are also plans to add citrus_unit_expr_export_mathml and citrus_unit_powers_export_mathml. These routines will be more flexible but won't add the value of the quantity to the left of the units.

citrus_convert_quantities ()

int         citrus_convert_quantities       (void *from,
                                             void *to,
                                             double *result);

Convert one quantity into the units of another.

citrus_convert_string ()

int         citrus_convert_string           (const char *from,
                                             const char *to,
                                             double *result);

Convert a string containing a number and units into a number with the units of a second string.

citrus_convert_array ()

int         citrus_convert_array            (double *value,
                                             int len,
                                             const char *from,
                                             const char *to,
                                             double *result);

Convert a number and a string containing its units into a number with the units of a second string.

citrus_convert ()

int         citrus_convert                  (double value,
                                             const char *from,
                                             const char *to,
                                             double *result);

Convert a number and a string containing its units into a number with the units of a second string.

citrus_dimension_group_get_next ()

const void* citrus_dimension_group_get_next (const void *pDgrp);

This function can be used to enumerate all of the recognized dimensional groups. Handy for displaying the capabilities of the converter.

citrus_dimension_group_get_next_unit ()

const void* citrus_dimension_group_get_next_unit
                                            (const void *pDgrp,
                                             const void *pUnit);

citrus_dimension_group_get_name ()

const gchar* citrus_dimension_group_get_name
                                            (const void *pDgrp);

Return the name of a dimension group given a pointer to a dimension group. Use this with citrus_dimension_group_get_next().

citrus_unit_get_scale ()

double      citrus_unit_get_scale           (const void *pUnit);

Get how a unit scales a dimensional axis (length, mass, time) compared to an arbitary (but fixed) reference unit. Our reference units are SI kgs units.

citrus_unit_has_offset ()

gboolean    citrus_unit_has_offset          (const void *pUnit);

Get whether a unit's zero point is at an offset compared to an arbitary (but fixed) reference unit. Our reference units are SI kgs units.

citrus_unit_get_offset ()

double      citrus_unit_get_offset          (const void *pUnit);

Get the distance unit's zero point is at an offset compared to an arbitary (but fixed) reference unit. Our reference units are SI kgs units. The result is measured in the reference units.

citrus_unit_get_name ()

const gchar* citrus_unit_get_name           (const void *pUnit);

The full name of a unit, in singular form.

citrus_unit_get_abbr ()

const gchar* citrus_unit_get_abbr           (const void *pUnit);

The abbreviation of a unit. Unit abbreviations are what's used to specify the units associated with numbers (see citrus_quantity_from_string(), for instance).

citrus_unit_get_plural_policy ()

gint        citrus_unit_get_plural_policy   (const void *pUnit);

Return an integer representing how the name of a unit is pluralized.

citrus_unit_get_plural_form ()

gchar*      citrus_unit_get_plural_form     (const void *pUnit);

You are responsible for calling g_free on the result.