NAME

Convert::TimeUnits - Perl module for converting between various units of time.

SYNOPSIS

  # Functional interface
  use Convert::TimeUnits qw(years_to_seconds days_to_minutes);
  my $seconds = years_to_seconds(3);
  my $days = days_to_minutes(1);

  # Object-oriented interface
  use Convert::TimeUnits;
  my $conv = new Convert::TimeUnits # all fields default to 0.
  (
    seconds     => 0,
    minutes     => 0,
    hours       => 0,
    days        => 5,
    weeks       => 5,
    years       => 0
  );
  my $seconds = $conv->get('seconds');
  $conv->set('days', 0);
  print $conv->calc_minutes(); # print total number of minutes for each field

DESCRIPTION

Convert::TimeUnits is a Perl module that simplifies the task of converting one amount of time to its equivalent value as expressed by another unit. Negative values are not permitted. All units referenced within the module whether as part of the object returned by new() or as function names are plural. All methods (object and class) take integer or floating point arguments and return the appropriate numeric format. It is the user's responsibility to use sprintf() and other date / time modules to format the results. All operations are limited in precision first by the definitions in the code and second by Perl's numeric data types.

For simple unit-to-unit conversions, the functional interface provides the greatest simplicity and import control. Simply import the required functions and use them as part of the current package.

For a more detailed presentation of conversion information, the object-oriented interface provides two accessor methods, get() and set(). The first argument to each is the field to access, and the second argument to set() is the value to set. Values which would cause a regrouping (e.g., seconds > 60) are permitted, and are the main point of this module.

OBJECT-ORIENTED INTERFACE

new()

new() instantiates a Convert::TimeUnits object. The following fields are valid: seconds minutes hours days years weeks .

get()

get() returns the requested item. The fields which are valid for new() are also valid for get().

set()

set() defines a value for a field. It takes two arguments: the field to set, and a numeric value to which to set said field.

calc_() methods

All of the calc_() methods do not take arguments. There is a calc_() method for each field of a Convert::TimeUnits object (thus calc_seconds(), calc_minutes(), etc.). Each calc_() method converts all other fields to their equivalent values in the target unit, tallies the results of all of those calculations, and returns that sum. Note that invoking a calc_() method includes the requested unit's field's value in its calculation, so calc_seconds() adds the Convert::TimeUnit's object's seconds field to the total.

FUNCTION-ORIENTED INTERFACE

Functions

All Convert::TimeUnits functions accessible via the function-oriented interface are of the form foo_to_bar , where foo and bar are plural unit names. For example, to convert from hours to seconds, call hours_to_seconds(). Each function takes a numeric argument and returns a numeric argument.

Exported functions

None by default.

SEE ALSO

units(1), perl(1)

CONFORMANCE

All of the values in Convert::TimeUnits have been derived from the units(1) program, version 1.0, and the accompanying units.lib file, version $FreeBSD: src/usr.bin/units/units.lib,v 1.15 2003/11/05 22:29:48 mph Exp $ , as shipped with FreeBSD 5.2.1. Discrepancies with GNU units presumed to be nonexistent because both FreeBSD's units.lib and GNU unit's units.dat both define the number of seconds in a year to be 31556926. All relations are interdependent, and this equality mathematically requires all relations (anamolies excepted) to be equal. The author wholeheartedly invites those in the appropriate fields of endeavor to test this software and report any inaccuracies and / or inconsistencies with corrections if possible and rationales if applicable.

Any changes to the conformance of Convert::TimeUnits shall be ostensibly annotated here and in the source distribution's accompanying README.

AUTHOR

Christopher Nehren, <apeiron@comcast.net> Meaghan Hayes contributed the idea to include a weeks field and functions.

COPYRIGHT AND LICENSE

Copyright (C) 2004 by Christopher Nehren

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