<-- Back to AG_Intro.3


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


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.


agPercentageUnitsValue in percentile
agFrequencyUnitsUnits of frequency
agTimeUnitsUnits of time


agLengthUnitsUnits of length/distance
agAngleUnitsUnits of angular measurement
agVideoUnitsUnits of video pixel resolution
agAreaUnitsUnits of area
agVolumeUnitsUnits of volume
agSpeedUnitsUnits of velocity


agMassUnitsUnits of weight
agPressureUnitsUnits of pressure and stress (general)
agVacuumUnitsUnits of pressure (low pressures)
agThermalConductivityUnitsUnits of thermal conductivity
agThermalExpansionUnitsUnits of thermal expansion
agDensityUnitsUnits of density
agLightUnitsUnits of light intensity
agSubstanceAmountUnitsUnits of substance amount (moles)


agPowerUnitsUnits of power
agTemperatureUnitsUnits of temperature
agEnergyPerSubstanceAmountUnitsUnits of energy per substance amount
agMolarHeatCapacityUnitsUnits of molar heat capacity


agEMFUnitsUnits of electromotive force / voltage
agCurrentUnitsUnits of electrical current
agResistanceUnitsUnits of electrical resistance
agResistanceTC1UnitsUnits of first-order temperature coefficients
agResistanceTC2UnitsUnits of second-order temperature coefficients
agResistivityUnitsUnits of resistivity of a material
agCapacitanceUnitsUnits of electrical capacitance
agInductanceUnitsUnits of electrical inductance


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).


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.


AG_Intro(3), AG_Numerical(3), AG_Widget(3)


The AG_Units facility first appeared in Agar 1.0.