.\" $Id: udunitsperl.1,v 1.3 2003/04/29 15:57:37 steve Exp $
.TH UDUNITSPerl 1 "$Date: 2003/04/29 15:57:37 $" "Printed: \n(yr-\n(mo-\n(dy" "UNIDATA UTILITIES"
.SH NAME
udunitsperl \- perl extension for UDUNITS
.SH SYNOPSIS
.na
.nh
.nf
use UDUNITS;
.sp
UDUNITS::init($path)
.sp
$unit = UDUNITS::new()
$unit = UDUNITS::scan($spec)
$unit2 = UDUNITS::dup($unit)
.sp
$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)
.sp
$unit2 = $unit->dup()
$spec = $unit->print()
.sp
$timeunit->valtocal($value, $year, $month, $day, $hour, $minute, $second)
$value = $timeunit->caltoval($year, $month, $day, $hour, $minute, $second)
.sp
UDUNITS::term()
.fi
.ad
.hy
.SH DESCRIPTION
.PP
\fBUDUNITSPerl\fP is a port of the udunits(3) library into a native Perl 5 
extension.
.SS "PACKAGE FUNCTIONS"
.PP
The functions in the UDUNITS package should be invoked by use of the 
\fBUDUNITS::\fP prefix (e.g. \fBUDUNITS::scan()\fP invokes the 
\fBscan()\fP function).
.TP 4
.BI init( $path )
Initializes the UDUNITS module.
File \fI$path\fP is the units
database to be read.
If \fI$path\fP is the empty string, then the default database is read.
The default database is determined at the time the UDUNITS package is
installed.
.TP
.BI new()
Returns a trivial unit object.
A trivial unit object is dimensionless and has the value \fB1\fP.
.TP
.BI scan( $spec )
Returns a unit object determined by the string \fI$spec\fP or an undefined
perl scalar if the UDUNITS module hasn't been initialized or the units
specification is invalid.
.TP
.BI dup( $unit )
Returns a duplicate of unit object \fI$unit\fP.
This action is identical to invoking the \fBdup()\fP member function
of a unit object (e.g. \fI$unit\fB->dup()\fR).
.TP
.BI term()
Terminates use of the UDUNITS module.
Frees allocated resources.
.SS "MEMBER FUNCTIONS"
.PP
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. \fI$unit\fB->invert()\fR invokes the \fBinvert()\fP member function 
of unit object \fI$unit\fP).
.TP
.BI hasorigin()
Returns true if the unit has an origin (possibly set via the shift() member
function) and false otherwise.
.TP
.BI istime()
Returns true if the unit is a pure unit of time (e.g. "seconds").
.TP
.BI clear()
Clears the unit object by setting it to the trivial unit object.
.TP
.BI invert()
Inverts the unit object (e.g. "seconds" becomes "1/seconds").
.TP
.BI shift( $amount )
Shifts the origin of the unit object by the amount \fI$amount\fP.
.TP
.BI scale( $factor )
Scales the unit object by the amount \fI$factor\fP.
.TP
.BI raise( $power )
Raises the unit object by the power \fI$power\fP.
.TP
.BI multiply( $unit2 )
Multiplies the unit object by the unit \fI$unit2\fP.
.TP
.BI divide( $unit2 )
Divides the unit object by the unit \fI$unit2\fP.
.TP
\fBconvert(\fI$unit2\fB,\fI$slope\fB,\fI$intercept\fB)\fR
Computes the slope and intercept necessary to convert values in units of
the unit object into values in units of \fIunit2\fP.
Returns 0 on success, \fBUDUNITS::ENOINIT\fP if the units module hasn't been 
initialized, and \fBUDUNITS::ECONVERT\fP if the unit objects
are not convertable.
.TP
.BI dup()
Returns a duplicate of unit object.
This action is identical to invoking the \fBUDUNITS::dup(\fI$unit\fB)\fR
package function.
.TP
.BI print()
Returns the canonical string specification of the unit object
(e.g. "kilogram meter second-2").
.TP
\fBvaltocal(\fI$value\fB, \fI$year\fB, \fI$month\fB, \fI$day\fB, \fI$hour\fB, \fI$minute\fB, \fI$second\fB)\fR
Breaks down the value \fI$value\fP in units of the unit object into
UTC calendar time.
Returns 0 on success, \fBUDUNITS::EINVALID\fP if the unit object is 
not a unit of time, and
\fBUDUNITS::ENOINIT\fP the units module hasn't been initialized.
The returned \fI$second\fP argument is floating-point.
.TP
\fBcaltoval(\fI$year\fB, \fI$month\fB, \fI$day\fB, \fI$hour\fB, \fI$minute\fB, \fI$second\fB)\fR
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 \fI$second\fP argument may be floating-point.
.PP
In addition to the above functions, most C macro constants that are defined
in the UDUNITS header file \fBudunits.h\fP are also available to a perl
script by dropping any `\fBUT_\fP' substring and using the 
\fBUDUNITS::\fP prefix, e.g. \fBUDUNITS::EINVALID\fP.
.SH "SEE ALSO"
.LP
.BR perl (1),
.BR udunits (3)