Agar

<-- Back to AG_Intro.3

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

agPercentageUnitsValue in percentile
agFrequencyUnitsUnits of frequency
agTimeUnitsUnits of time

LENGTHS & ANGLES

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

PHYSICAL

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)

THERMODYNAMICS

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

ELECTRICAL

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

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)

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.

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.
Csoft.net ElectronTubeStore