Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
AG_UNITS(3)		 BSD Library Functions Manual		   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 abbrevi-
     ated 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 func-
     tion 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.

BSD				 May 10, 2004				   BSD
NAME | SYNOPSIS | DESCRIPTION | GENERAL | LENGTHS & ANGLES | PHYSICAL | THERMODYNAMICS | ELECTRICAL | INTERFACE | EXAMPLES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Units&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help