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

  ##- 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);

# A few useful time functions.

package UR::Time;

# set up package
require 5.6.0;
use warnings;
use strict;
our $VERSION = $UR::VERSION;

# set up module
use base qw(UR::ModuleBase UR::ModuleConfig);
use Date::Calc;
use Date::Parse;
use POSIX;
use Time::Local;

# set configuration variables
__PACKAGE__->config
(
    datetime => '%Y-%m-%d %H:%M:%S',
    date => '%Y-%m-%d',
    time => '%H:%M:%S',
);

# returns today's date in default Oracle date format
*today = \&date_now;
sub date_now
{
    my $class = shift;

    # get date format
    my $format = $class->config('date');
    if ($format)
    {
        $class->debug_message("got date format $format", 4);
    }
    else
    {
        $class->error_message("no date format specified");
        return;
    }

    # return formatted current time
    return POSIX::strftime($format, localtime);
}

# returns today's date in default Oracle date format
sub time_now
{
    my $class = shift;

    # get date format
    my $format = $class->config('time');
    if ($format)
    {
        $class->debug_message("got date format $format", 4);
    }
    else
    {
        $class->error_message("no date format specified");
        return;
    }

    # return formatted current time
    return POSIX::strftime($format, localtime);
}

# returns current date and time in default Oracle date format
my $use_local_time = 0;
my @local_time_offset;
sub now
{
    my $class = shift;

    # do not consult database if we already have
    if ($use_local_time) 
    {   
	# calculate the time from the calculated offset
	my ($y, $mon, $d, $h, $min, $s)
            = Date::Calc::Add_Delta_YMDHMS(Date::Calc::Today_and_Now,
                                           @local_time_offset);
        # format the date accordingly
        return $class->numbers_to_datetime($s, $min, $h, $d, $mon, $y);
    }
    # else try to get time from database
    if (my @db_now = $UR::Context::current->get_time_ymdhms()) {
        
        # get machine time
        my (@now) = Date::Calc::Today_and_Now;

        # calculate difference
        @local_time_offset = Date::Calc::Delta_YMDHMS(@now, @db_now);

        # set flag to avoid database access next time
        $use_local_time = 1;

        # return time in default format
        return $class->numbers_to_datetime(reverse(@db_now));
    }
    # else just get the time from the machine
    return $class->now_local;
}

# returns current date and time in default Oracle date format
sub now_local
{
    my $class = shift;
    return $class->from_integer(time);
}

# returns epoch seconds in default datetime format
sub from_integer
{
    my $class = shift;
    my ($time) = @_;

    # get date format
    my $format = $class->config('datetime');
    if ($format)
    {
        $class->debug_message("got datetime format $format", 4);
    }
    else
    {
        $class->error_message("no datetime format specified");
        return;
    }

    # return formatted current time
    return POSIX::strftime($format, localtime($time));
}

# return difference in seconds of two times
sub timediff
{
    my $class = shift;
    my ($t1, $t2) = @_;

    foreach my $t ($t1, $t2)
    {
	if ($t =~ /(\d\d):(\d\d):(\d\d)/)
	{
	    $t = $3 + ($2 * 60) + ($1 * 60 * 60);
	}
	else
	{
            $class->error_message("failed to parse times:$t1,$t2");
	    return;
	}
    }

    return $t2 - $t1;
}

# returns equivalent of first date <=> second date
# an undef date is considered to be earlier than a defined date
sub compare_dates
{
    my $class = shift;
    my ($date1, $date2) = @_;

    no warnings;
    $class->debug_message("comparing >$date1< with >$date2<", 4);
    use warnings;
    
    return 0 if !$date1 && !$date2;
    # undefined dates are less than defined ones
    return -1 if !$date1;
    return 1 if !$date2;

    # split up the date into parts
    my ($s1, $n1, $h1, $d1, $m1, $y1) = UR::Time->datetime_to_numbers($date1);
    my ($s2, $n2, $h2, $d2, $m2, $y2) = UR::Time->datetime_to_numbers($date2);
    return undef unless $s1 && $s2; # error

    $class->debug_message("$y1,$m1,$d1,$h1,$n1,$s1 to $y2,$m2,$d2,$h2,$n2,$s2", 4);

    no warnings qw(uninitialized);
    return $y1 <=> $y2 || $m1 <=> $m2 || $d1 <=> $d2
	|| $h1 <=> $h2 || $n1 <=> $n2 || $s1 <=> $s2;
}

# split up a date in the default Oracle date format into parts
# return numeric year, month, day, hour, minute, and second
sub datetime_to_numbers
{
    my $class = shift;
    my ($date) = @_;

    # try to parse
    my @time = strptime($date);
    if (@time)
    {
        $class->debug_message("parse date $date", 4);
        # fix month
        ++$time[4];
        $time[5] += 1900;
    }
    else
    {
        $class->warning_message("failed to parse $date with strptime");
        # fall back to old method
        @time = reverse(split(m,[-\s:/],, $date));
    }
    return @time;
}

# combine a bunch of date and time fields into a date in the default format
sub numbers_to_datetime
{
    my $class = shift;
    my ($s, $min, $h, $d, $mon, $y) = @_;

    # get date/time format
    my $format = $class->config('datetime');
    if ($format)
    {
        $class->debug_message("got datetime format $format", 4);
    }
    else
    {
        $class->error_message("no datetime format specified");
        return;
    }

    # return date time
    return POSIX::strftime($format, $s, $min, $h, $d, $mon - 1, $y - 1900);
}

sub datetime_to_time
{
    my ($class, $date) = @_;

    # try to parse
    my @time = strptime($date);
    if (@time)
    {
        $class->debug_message("parse date $date", 4);
    }
    else
    {
        $class->warning_message("failed to parse $date with strptime");
        # fall back to old method
        @time = reverse(split(m,[-\s:/],, $date));
        # fix month
        --$time[4];
        # fix year
        $time[5] -= 1900;
    }

    my $time = timelocal(@time);

    return $time;
}

sub add_date_delta_days 
{
    my $class = shift;
    my ($date, $days) = @_;

    # get date format
    my $format = $class->config('date');
    if ($format)
    {
        $class->debug_message("got date format $format", 4);
    }
    else
    {
        $class->error_message("no date format specified");
        return;
    }

    # try to parse date
    my ($d, $m, $y);
    my @time = strptime($date);
    if (@time)
    {
        $class->debug_message("parsed date $date: " . join('-', @time[3 .. 5]), 4);
        ($d, $m, $y) = @time[3 .. 5];
        # correct for use with Date::Calc
        ++$m;
        $y += 1900;
    }
    else
    {
        $class->warning_message("failed to parse date with strptime");
        # fall back to old method
        ($y, $m, $d) = split(m/-/, $date);
    }

    # add the days
    ($y, $m, $d) = Date::Calc::Add_Delta_Days($y, $m, $d, $days);
    
    # format the string
    return POSIX::strftime($format, 0, 0, 0, $d, --$m, $y - 1900);
}

1;
__END__

#$Header$