.\" Copyright (c) 2004-2022 Julien Nadeau Carriere .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd December 21, 2022 .Dt AG_UNITS 3 .Os Agar 1.7 .Sh NAME .Nm AG_Units .Nd agar unit conversion facility .Sh SYNOPSIS .Bd -literal #include #include .Ed .Sh DESCRIPTION .\" IMAGE(/widgets/AG_UnitConv.png, "Unit conversion test") The Agar .Nm interface implements unit conversion. .\" MANLINK(AG_Unit) The .Ft AG_Unit structure is defined as follows: .Bd -literal .\" SYNTAX(c) typedef struct ag_unit { char *key; char *abbr; char *name; double divider; double (*func)(double, int mode); } AG_Unit; .Ed .Pp The .Va key member is a unique identifier for this unit. .Va abbr is an abbreviated symbol, and .Va name is the full name of the unit. .Pp The linear conversion factor is specified in .Va divider . For non-linear conversions, .Va func can be defined instead (the first argument to the function is the value to convert; if .Fa mode is 1, the function make the reverse conversion). .Pp A set of standard conversion unit groups are defined in .Pa gui/units.c in the Agar sources. The standard groups are summarized below. .Sh GENERAL .Bl -tag -compact -width "agPercentageUnits " .It agPercentageUnits Value in percentile .It agFrequencyUnits Units of frequency .It agTimeUnits Units of time .El .Sh LENGTHS & ANGLES .Bl -tag -compact -width "agLengthUnits " .It agLengthUnits Units of length/distance .It agAngleUnits Units of angular measurement .It agVideoUnits Units of video pixel resolution .It agAreaUnits Units of area .It agVolumeUnits Units of volume .It agSpeedUnits Units of velocity .El .Sh PHYSICAL .Bl -tag -compact -width "agThermalConductivityUnits " .It agMassUnits Units of weight .It agPressureUnits Units of pressure and stress (general) .It agVacuumUnits Units of pressure (low pressures) .It agThermalConductivityUnits Units of thermal conductivity .It agThermalExpansionUnits Units of thermal expansion .It agDensityUnits Units of density .It agLightUnits Units of light intensity .It agSubstanceAmountUnits Units of substance amount (moles) .El .Sh THERMODYNAMICS .Bl -tag -compact -width "agEnergyPerSubstanceAmountUnits " .It agPowerUnits Units of power .It agTemperatureUnits Units of temperature .It agEnergyPerSubstanceAmountUnits Units of energy per substance amount .It agMolarHeatCapacityUnits Units of molar heat capacity .El .Sh ELECTRICAL .Bl -tag -compact -width "agResistanceTC1Units " .It agEMFUnits Units of electromotive force / voltage .It agCurrentUnits Units of electrical current .It agResistanceUnits Units of electrical resistance .It agResistanceTC1Units Units of first-order temperature coefficients .It agResistanceTC2Units Units of second-order temperature coefficients .It agResistivityUnits Units of resistivity of a material .It agCapacitanceUnits Units of electrical capacitance .It agInductanceUnits Units of electrical inductance .El .Sh INTERFACE .nr nS 1 .Ft "const AG_Unit *" .Fn AG_FindUnit "const char *key" .Pp .Ft "const AG_Unit *" .Fn AG_BestUnit "const AG_Unit *unit_group" "double n" .Pp .Ft "char *" .Fn AG_UnitFormat "double n" "const AG_Unit unit_group[]" .Pp .Ft "const char *" .Fn AG_UnitAbbr "const AG_Unit *unit" .Pp .Ft "double" .Fn AG_Unit2Base "double n" "const AG_Unit *unit" .Pp .Ft "double" .Fn AG_Base2Unit "double n" "const AG_Unit *unit" .Pp .Ft "double" .Fn AG_Unit2Unit "double n" "const AG_Unit *unit_from" "const AG_Unit *unit_to" .Pp .nr nS 0 The .Fn AG_FindUnit function searches the unit database for a unit matching the given .Fa key , and returns a pointer to the unit on success or NULL if none was found. .Pp The .Fn AG_BestUnit function returns the unit expected to yield the least number of non-significant figures when formatting the given number .Fa n . .Fn AG_UnitFormat formats the given number .Fa n using the best unit in .Fa unit_group . .Pp .Fn AG_UnitAbbr returns the abbreviation string associated with the given unit. .Pp The .Fn AG_Unit2Base function converts from .Fa n in specified units to the equivalent number of base units. .Fn AG_Base2Unit converts .Fa n base units to the equivalent number of specified units. .Sh EXAMPLES One widget which uses this interface is .Xr AG_Numerical 3 , which accepts .Fa unit arguments. The following code fragment creates a widget for editing a length value given in meters: .Bd -literal -offset indent .\" SYNTAX(c) float length = 1.234; AG_Numerical *num; num = AG_NumericalNewFlt(parent, 0, "m", "Length: ", &length) .Ed .Pp The following code fragment prints the equivalent milliseconds for a given .Va n number of seconds: .Bd -literal -offset indent .\" SYNTAX(c) printf("%f seconds = %f milliseconds", n, AG_Base2Unit(n, AG_FindUnit("ms"))); .Ed .Pp The following code fragment prints the equivalent of 27 degrees Celsius, in kilo Kelvins: .Bd -literal -offset indent .\" SYNTAX(c) const AG_Unit *degC = AG_FindUnit("degC"); const AG_Unit *kk = AG_FindUnit("kk"); printf("27C = %fkk", AG_Unit2Unit(27.0, degC, kk)); .Ed .Pp This code fragment displays the value of .Va r using the resistance unit most suitable to its magnitude. .Bd -literal -offset indent .\" SYNTAX(c) printf("Resistance = %s", AG_UnitFormat(r, agResistanceUnits)); .Ed .Pp Also see .Pa tests/unitconv.c in the Agar source distribution. .Sh SEE ALSO .Xr AG_Intro 3 , .Xr AG_Numerical 3 , .Xr AG_Widget 3 .Sh HISTORY The .Nm facility first appeared in Agar 1.0.