UDUNITSPerl(1)

NAME
udunitsperl - perl extension for UDUNITS

SYNOPSIS
use UDUNITS;

UDUNITS::init($path)

$unit = UDUNITS::new()
$unit = UDUNITS::scan($spec)
$unit2 = UDUNITS::dup($unit)

$unit->hasorigin()
$unit->istime()
$unit->clear()
$unit->invert()
$unit->shift($amount)
$unit->scale($factor)
$unit->raise($power)
$unit->multiply($unit2)
$unit->divide($unit2)
$unit->convert($unit2, $slope, $intercept)

$unit2 = $unit->dup()
$spec = $unit->print()

$timeunit->valtocal($value, $year, $month, $day, $hour, $minute, $second)
$value = $timeunit->caltoval($year, $month, $day, $hour, $minute, $second)

UDUNITS::term()

DESCRIPTION

UDUNITSPerl is a port of the udunits(3) library into a native Perl 5 extension.

  PACKAGE FUNCTIONS

The functions in the UDUNITS package should be invoked by use of the UDUNITS:: prefix (e.g. UDUNITS::scan() invokes the scan() function).

init($path)
    Initializes the UDUNITS module. File $path is the units database to be read. If $path is the empty string, then the default database is read. The default database is determined at the time the UDUNITS package is installed.

new()
    Returns a trivial unit object. A trivial unit object is dimensionless and has the value 1.

scan($spec)
    Returns a unit object determined by the string $spec or an undefined perl scalar if the UDUNITS module hasn't been initialized or the units specification is invalid.

dup($unit)
    Returns a duplicate of unit object $unit. This action is identical to invoking the dup() member function of a unit object (e.g. $unit->dup()).

term()
    Terminates use of the UDUNITS module. Frees allocated resources.

  MEMBER FUNCTIONS

Every unit object created by one of the above functions has a set of method functions. A member function is invoked by using the unit object as a reference (e.g. $unit->invert() invokes the invert() member function of unit object $unit).

hasorigin()
    Returns true if the unit has an origin (possibly set via the shift() member function) and false otherwise.

istime()
    Returns true if the unit is a pure unit of time (e.g. "seconds").

clear()
    Clears the unit object by setting it to the trivial unit object.

invert()
    Inverts the unit object (e.g. "seconds" becomes "1/seconds").

shift($amount)
    Shifts the origin of the unit object by the amount $amount.

scale($factor)
    Scales the unit object by the amount $factor.

raise($power)
    Raises the unit object by the power $power.

multiply($unit2)
    Multiplies the unit object by the unit $unit2.

divide($unit2)
    Divides the unit object by the unit $unit2.

convert($unit2,$slope,$intercept)
    Computes the slope and intercept necessary to convert values in units of the unit object into values in units of unit2. Returns 0 on success, UDUNITS::ENOINIT if the units module hasn't been initialized, and UDUNITS::ECONVERT if the unit objects are not convertable.

dup()
    Returns a duplicate of unit object. This action is identical to invoking the UDUNITS::dup($unit) package function.

print()
    Returns the canonical string specification of the unit object (e.g. "kilogram meter second-2").

valtocal($value, $year, $month, $day, $hour, $minute, $second)
    Breaks down the value $value in units of the unit object into UTC calendar time. Returns 0 on success, UDUNITS::EINVALID if the unit object is not a unit of time, and UDUNITS::ENOINIT the units module hasn't been initialized. The returned $second argument is floating-point.

caltoval($year, $month, $day, $hour, $minute, $second)
    Returns the value in units of the unit object that corresponds to the given UTC calendar time or a perl undefined scalar if the units module hasn't been initialized or the unit object is not a unit of time. If defined, then the returned value is floating-point. The $second argument may be floating-point.

In addition to the above functions, most C macro constants that are defined in the UDUNITS header file udunits.h are also available to a perl script by dropping any `UT_' substring and using the UDUNITS:: prefix, e.g. UDUNITS::EINVALID.

SEE ALSO

perl(1), udunits(3)