$Header: /var/cvs/mbdyn/mbdyn/mbdyn-1.0/modules/module-udunits/README,v 1.2 2012/11/24 10:25:57 masarati Exp $

This module adds a namespace "units" with the only function "convert",
which is thus invoked as "units::convert".
This function's prototype is

	real units::convert( string from , string to [ , real val ] )

where

	from	is a string indicating what units to convert from
	to	is a string indicating what units to convert to
	val	is an optional real argument that indicates what value
		should be converted

When called with just the two mandatory arguments, the function returns the
scale factor between the two units; for example

	units::convert("ft", "m")

returns 0.3048.

When called with the third optional argument as well, the function returns
the optional argument converted according to the conversion arguments;
for example

	units::convert("ft", "m", 10.)

returns 3.048, corresponding to ( 10 ft * 0.3048 m/ft ).

The first form may not be enough, for example, for those conversions
that include an "intercept"; for example, when converting from degrees 
Celsius to degrees Fahrenheit, the actual conversion would be

	F = 32 + 9 / 5 * C

In those cases, the conversion fails, unless the third argument 
is specified; for example

	units::convert("Celsius", "Fahrenheit")

would fail, while

	units::convert("Celsius", "Fahrenheit", 0.)

would return 32.

This module requires UNIDATA's libudunits; get it from

<http://www.unidata.ucar.edu/software/udunits/>



