/ 
Physics-Udunits2-0.03
River stage zero No dependents
/ Physics::Udunits2

NAME

Physics::Udunits2 - Perl extension to Udunits2 unit system

SYNOPSIS

use Physics::Udunits2;
my $system = new Physics::Udunits2();
my $mUnit = $system->getUnit("m");
my $kmUnit = $system->getUnit("km");
if ($mUnit->isConvertibleTo($kmUnit)) {
   my $converter = $mUnit->getConverterTo($kmUnit);
   foreach my $num (1..1000) {
	   printf("%fm = %fkm"\n, $num, $converter->convert($num));
   }
}

DESCRIPTION

This is a perl interface to the udunits-2 package from unidata. The c-level api has been change to a perl OO-api, i.e.

ut_unit ut_get_unit_by_name(ut_system, name)

changes in perl to

$unit = $system->getUnitByName(name)

Lots of information can thus be retrieved from the extensive C-Api documentation of udunits2. The following gives only and excerpt:

Physics::Udunits Time handling

Times are stored in double, in the unit with the name 'second'. With the following functions, times can be converted from a calendar to that double. These function can be imported with the ':all' tag.

encodeTime($year, $month, $day, $hour, $minute, $second)

All values are integer, except second. Year are (usually) 4 numbers, $month is between 1 and 12, day between 1 and 31, hour between 0 and 23, minute between 0 and 59 and seconds between 0 and 59.999999

encodeDate($year, $month, $day)
encodeClock($hour, $minute, $second)

encodeClock + encodeDate = encodeTime

decodeTime($timeDouble)

return ($year, $month, $day, $hour, $minute, $second)

Time Conversion Example

use Physics::Udunits2 qw(:all);
my $system = new Physics::Udunits2();
my @time = (1973, 6, 26, 9, 51, 0);
my $baseTime = encodeTime(@time);
my $tUnit = $system->getUnit("minutes since 1973-06-26 00:00:00");
my $baseTimeUnit = $system->getUnitByName("second"); 
print $baseTimeUnit->getConverterTo($tUnit)->convert($baseTime); # writes 591.000000xxx = 9*60 + 51 + (fractalSeconds)

Physics::Udunits2::System

Methods of Physics::Udunits2::System:

new Physics::Udunits2([$path])

retrieve a Physics::Udunits2::System ($system) from the file-system, if path is left empty, retrieve the default.

getUnit($unitString)

parse the unitString and return Physics::Udunits2::Unit, in 99% of all cases, you want to use this function

getUnitByName($unitName)

retrieve a unit by the exact unitName

getUnitBySymbol($symbolName)

retrieve a unit by the exact base-symbol (km will not work)

newBaseUnit

retrieve a new unit

newDimensionlessUnit

Physics::Udunits2::Unit

After retrieving a unit from a system, you call the following methods:

Converter

isConvertibleTo($otherUnit)

Check if units are convertible, return true on success. Throws if units are from different systems.

getConverterTo($otherUnit)

Retrieve a Physics::Udunits2::Converter, to convert from one unit to another. Throws if units are not convertible, or from different systems.

Unit Operations

The following unit operation methods all return a new unit

scale($numberScale)
offset($numberOffset)
offset_by_time($numberTime)
invert()
raise($intPower)
root($intRoot)
log($numberBase)
multiply($unit2)
divide($unitDenominator)
clone()

Unit Information

getName()

return the name or undef

getSymbol()

return the symbol or undef

sameSystem($otherUnit)

check if units are from the same system.

isDimensionless()
getSystem()
compare($otherUnit)

return a value < 0, 0 or > 0, if the unit is <, = or > the otherUnit. The units need to be convertible.

Physics::Udunist2::Converter

A converter should be fetched from a Physics::Udunits2::Unit

convert($number)

returns the number in the other unit of the converter

EXPORT

None by default. Tag ':all' gives:

encodeTime
encodeDate
encodeClock
decodeTime

EXCEPTIONS

All errors internal to udunits are thrown with croak. Those are usually either programming errors, or system errors. When retrieving units from a system,

SEE ALSO

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

AUTHOR

Heiko Klein, <Heiko.Klein@met.no>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Heiko Klein

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.