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

FreeBSD Manual Pages

  
 
  

home | help 
AG_UNITS(3)		    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	abbre-
       viated 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
       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)

       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	match-
       ing 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 edit-
       ing 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 Cel-
       sius, 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.

Agar 1.7		       December	21, 2022		   AG_UNITS(3)

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

home | help