.\" Copyright (c) 2004-2007 Hypertriton, Inc. <http://hypertriton.com/>
.\" 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 May 10, 2004
.Dt AG_UNITS 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_Units
.Nd agar unit conversion facility
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
The Agar
.Nm
facility implements linear as well as nonlinear unit conversion.
Each unit is attributed an abbreviation and a long name.
A numerical coefficient is associated with linear units and a function pointer
is associated with nonlinear units.
.Pp
The
.Xr AG_Numerical 3
widget uses this interface.
.Pp
Units are arranged in unit groups, and Agar's
.Pa agar/gui/units.c
defines the groups:
.Pp
.Bl -tag -compact -width "agSubstanceAmountUnits "
.It agLengthUnits
Units of length/distance
.It agAreaUnits
Units of area
.It agVolumeUnits
Units of volume
.It agSpeedUnits
Units of speed or velocity
.It agMassUnits
Units of weight
.It agTimeUnits
Units of time
.It agCurrentUnits
Units of electrical current
.It agTemperatureUnits
Units of temperature
.It agSubstanceAmountUnits
Units of substance amount
.It agLightUnits
Units of light measurement
.It agPowerUnits
Units of power
.It agEMFUnits
Units of electromotive force
.It agResistanceUnits
Units of electrical resistance
.It agResistanceTC1Units
Units of first-order temperature coefficients
.It agResistanceTC2Units
Units of second-order temperature coefficients
.It agCapacitanceUnits
Units of electrical capacitance
.It agInductanceUnits
Units of electrical inductance
.It agFrequencyUnits
Units of frequency
.It agPressureUnits
Units of pressure and stress
.It agMetabolicExpenditureUnits
Units of metabolic expenditure
(somewhat humorous)
.El
.Pp
The compile-time option
.Dv ASTRONOMICAL_UNITS
controls the inclusion of astronomical units of length and pressure.
If
.Dv HISTORICAL_UNITS
is defined, historical units of weight and measure are included as well.
.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
The following code fragment prints the equivalent milliseconds for a given
.Va n
number of seconds:
.Pp
.Bd -literal -offset indent
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:
.Pp
.Bd -literal -offset indent
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.
.Pp
.Bd -literal -offset indent
printf("Resistance = %s", AG_UnitFormat(r, agResistanceUnits));
.Ed
.Pp
Also see
.Pa demos/unitconv
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.