NAME

UR::Time - a few useful time-related functions.

SYNOPSIS

  ##- use UR::Time;

  UR::Time->config(time => '%H:$M:%S');
  $format = UR::Time->config('time');

  $date = UR::Time->today;

  $date_time = UR::Time->now;

  $ds = UR::Time->timediff($t1, $t2);

  $rv = UR::Time->compare_dates($d1, $d2);

  ($sec, $min, $hour, $day, $mon, $year)
      = UR::Time->datetime_to_numbers($datetime);

  $datetime = UR::Time->numbers_to_datetime($sec, $min, $hour,
                                             $day, $mon, $year);

DESCRIPTION

This package provides several useful functions for reporting and comparing dates and times in a standard date format. The format is set using the config method. All years are expected to be not truncated and all times are expected in 24 hour format.

METHODS

These methods use Perl builtin time methods and Date::Calc (see Date::Calc) to get date and time information and then format it or operate on it.

config

  UR::Time->config(datetime => '%Y-%m-%d %H:%M:%S');
  $dt_format = UR::Time->config('datetime');
  %config = UR::Time->config;

This method is used to set and retrieve configuration information. See UR::ModuleConfig for details of method behavior. Possible configuration options are:

datetime

The format for date/time represenations in scalar format. The default is shown above.

date

The format for date represenations in scalar format. The default is %Y-%m-%d.

time

The format for time represenations in scalar format. The default is %H:%M:%S.

All formats are interpreted as format arguments to strftime (see strftime).

today

  $date = UR::Time->date_now;

This method returns today's date in the default format. (Aliassed as "today".)

time_now

  $date = UR::Time->time_now;

Returns the time "now", much like the now method w/o the date.

now

  $date = UR::Time->now;

This method returns the current date/time in the default format. This method will attempt to get this time from the the database, if a connection is available.

now_local

  $date = UR::Time->now_local;

This method returns the current machine date/time in the default format. It never consults the database and will match current local file timestamps.

from_integer

  $date = UR::Time->from_integer($time);

Takes a time in long-integer format (as returned by stat() or time()), and returns the date/time in the default format.

timediff

  $ds = UR::Time->timediff($t1, $t2);

This method computes the difference in seconds between two times ($t1 and $t2) in 24 hour format (HH:MM:SS). The difference in seconds is returned. If the times are not in the correct format, undef is returned. If $t1 is greater than $t2, a negative value is returned.

compare_dates

  $rv = UR::Time->compare_dates($d1, $d2);

This method compares two date/times and returns -1 if $d1 is less than $d2, 1 if $d1 is greater than $d2, and 0 if the dates are equivalent.

datetime_to_numbers

  ($sec, $min, $hour, $day, $mon, $year)
      = UR::Time->datetime_to_numbers($datetime);

This method converts a date/time in the default format into a list of the numeric represenation of the year, month, day, hour, minute, and second. If any part of the date or time cannot be determined from the string, it's value will be undef. All values start at 1, e.g., January is month 1, not zero.

numbers_to_datetime

  $datetime = UR::Time->numbers_to_datetime($sec, $min, $hour
                                             $day, $mon, $year);

This method converts a list of numeric date and time data into a date/time in the the default format. In effect, this method is the reverse of datetime_to_numbers (see "datetime_to_numbers"). If an error occurs, undef is returned.

datetime_to_time

  $time = UR::Time->datetime_to_time($datetime);

This method converts a date/time in the default format into epoch seconds.

add_date_delta_days

    $date = UR::Time->add_date_delta_days($date, $days);

This method accepts a date in the default format and will return a date $days in the past or future. Use negative values for calculating dates in the past and positive values for dates in the future. It is based on Date::Calc::Add_Delta_Days (see "Add_Delta_Days" in Date::Calc).

SEE ALSO

Date::Calc(3), Date::Parse(3), strftime(3), POSIX(3)