AG_UNITS(3)

NAME
AG_Units - agar unit conversion facility

SYNOPSIS

    #include <agar/core.h>
    #include <agar/gui.h>

DESCRIPTION
The Agar AG_Units interface implements unit conversion. The AG_Unit structure is defined as follows:

    typedef struct ag_unit {
    	char *key;
    	char *abbr;
    	char *name;
    	double divider;
    	double (*func)(double, int mode);
    } AG_Unit;

The key member is a unique identifier for this unit. abbr is an abbreviated symbol, and name is the full name of the unit.

The linear conversion factor is specified in divider. For non-linear conversions, func can be defined instead (the first argument to the function is the value to convert; if mode is 1, the function make the reverse conversion).

A set of standard conversion unit groups are defined in gui/units.c in the Agar sources. The standard groups are summarized below.

GENERAL
agPercentageUnits
    Value in percentile
agFrequencyUnits
    Units of frequency
agTimeUnits
    Units of time

LENGTHS & ANGLES
agLengthUnits
    Units of length/distance
agAngleUnits
    Units of angular measurement
agVideoUnits
    Units of video pixel resolution
agAreaUnits
    Units of area
agVolumeUnits
    Units of volume
agSpeedUnits
    Units of velocity

PHYSICAL
agMassUnits
    Units of weight
agPressureUnits
    Units of pressure and stress (general)
agVacuumUnits
    Units of pressure (low pressures)
agThermalConductivityUnits
    Units of thermal conductivity
agThermalExpansionUnits
    Units of thermal expansion
agDensityUnits
    Units of density
agLightUnits
    Units of light intensity
agSubstanceAmountUnits
    Units of substance amount (moles)

THERMODYNAMICS
agPowerUnits
    Units of power
agTemperatureUnits
    Units of temperature
agEnergyPerSubstanceAmountUnits
    Units of energy per substance amount
agMolarHeatCapacityUnits
    Units of molar heat capacity

ELECTRICAL
agEMFUnits
    Units of electromotive force / voltage
agCurrentUnits
    Units of electrical current
agResistanceUnits
    Units of electrical resistance
agResistanceTC1Units
    Units of first-order temperature coefficients
agResistanceTC2Units
    Units of second-order temperature coefficients
agResistivityUnits
    Units of resistivity of a material
agCapacitanceUnits
    Units of electrical capacitance
agInductanceUnits
    Units of electrical inductance

INTERFACE
const AG_Unit * AG_FindUnit(const char *key)

const AG_Unit * AG_BestUnit(const AG_Unit *unit_group, double n)

char * AG_UnitFormat(double n, const AG_Unit unit_group[])

const char * AG_UnitAbbr(const AG_Unit *unit)

double AG_Unit2Base(double n, const AG_Unit *unit)

double AG_Base2Unit(double n, const AG_Unit *unit)

long double AG_Unit2BaseLDBL(long double n, const AG_Unit *unit)

long double AG_Base2UnitLDBL(long double n, const AG_Unit *unit)

double AG_Unit2Unit(double n, const AG_Unit *unit_from, const AG_Unit *unit_to)

The AG_FindUnit() function searches the unit database for a unit matching the given key, and returns a pointer to the unit on success or NULL if none was found.

The AG_BestUnit() function returns the unit expected to yield the least number of non-significant figures when formatting the given number n. AG_UnitFormat() formats the given number n using the best unit in unit_group.

AG_UnitAbbr() returns the abbreviation string associated with the given unit.

The AG_Unit2Base() function converts from n in specified units to the equivalent number of base units. AG_Base2Unit() converts n base units to the equivalent number of specified units.

The AG_Unit2BaseLDBL() and AG_Base2UnitLDBL() variants accept a long double argument (only available if AG_HAVE_LONG_DOUBLE is defined).

EXAMPLES
One widget which uses this interface is AG_Numerical(3), which accepts unit arguments. The following code fragment creates a widget for editing a length value given in meters:

    float length = 1.234;
    AG_Numerical *num;
    num = AG_NumericalNewFlt(parent, 0, "m", "Length: ", &length)

The following code fragment prints the equivalent milliseconds for a given n number of seconds:

    printf("%f seconds = %f milliseconds", n,
        AG_Base2Unit(n, AG_FindUnit("ms")));

The following code fragment prints the equivalent of 27 degrees Celsius, in kilo Kelvins:

    const AG_Unit *degC = AG_FindUnit("degC");
    const AG_Unit *kk = AG_FindUnit("kk");
    printf("27C = %fkk", AG_Unit2Unit(27.0, degC, kk));

This code fragment displays the value of r using the resistance unit most suitable to its magnitude.

    printf("Resistance = %s", AG_UnitFormat(r, agResistanceUnits));

Also see tests/unitconv.c in the Agar source distribution.

SEE ALSO
AG_Intro(3), AG_Numerical(3), AG_Widget(3)

HISTORY
The AG_Units facility first appeared in Agar 1.0.