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. This is the ut_parse(ut_trim(unitString)) function in the C-API documentation.

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.

cpanm Physics::Udunits2

perl -MCPAN -e shell
install Physics::Udunits2