=head1 NAME
Time::Interval - Converts time intervals of days, hours, minutes, and seconds
This is a rather simple perl module for dealing with time intervals. Among other things,
this module can tell you the number of hours, minutes, and seconds elapsed between two
dates.
NOTE: this module does not handle resolutions < 1 second. Please see the Time::HiRes
module for high resolution time operations. This module will round fractional second
values to the nearest whole number.
=head1 SYNOPSIS
use Time::Interval;
$data = getInterval(
"1/25/03 12:34:32 EDT 2003",
"4/25/03 11:24:00 EDT 2003"
);
$string = getInterval(
"1/25/03 12:34:32 EDT 2003",
"4/25/03 11:24:00 EDT 2003",
"string"
);
$number_of_minutes = convertInterval(
days => 5,
hours => 23,
minutes => 10,
ConvertTo => "minutes"
);
$data = parseInterval(seconds => 14295872);
$string = parseInterval(
seconds => 14295872,
String => 1
);
$string = parseInterval(
seconds => 14295872,
Small => 1
);
$min_intervals = coalesce([
[ '1/25/03 12:34:32 EDT 2003', '1/25/03 15:34:32 EDT 2003' ],
[ '1/25/03 14:34:32 EDT 2003', '1/25/03 16:34:32 EDT 2003' ],
[ '1/25/03 09:10:18 EDT 2003', '1/25/03 12:32:15 EDT 2003' ]
]);
=head1 getInterval
this will take two date strings in any of the formats recognized by Date::Parse, and return
the number of days, hours, minutes, and seconds elapsed between the two times.
=head2 Returned Data format
getInterval returns a hash reference in the same format as parseInterval.
=head2 Catching exceptions
upon failure this routine will return the undef value, and an error string will be
warn'd to stdout.
=head2 Arguments
=over
=item argument 1 (required)
this should be a date string in any of the formats available to Date::Parse.
=item argument 2 (required)
this should be a date string in any of the formats available to Date::Parse.
=item argument 3 (optional)
this argument controls how the interval will be returned.
If not defined, the inerval will be returned as a hash reference containing the number of
days, hourse, minutes and seconds between the two dates. If the following values are specified
the interval will be returned as a string:
=over
=item 'small'
if this value is specified, a string containing abbreviated values will be returned (dhms format)
for instance 1d 2h 3m 0s (one day, two hours, three minutes and 0 seconds)
=item 'string'
if this value (or any value other than 'short') is specified a string containing the interval
will be returned for instance: '1 day, 2 hours, 3 minutes, 0 seconds'
=back
=back
=head1 convertInterval
this will convert a given number of days, hours, minutes, or seconds, or any combination
thereof to the format specified by the ConverrtTo option.
=head2 Returned data
is a number, of time units that you specify on the ConvertTo option
=head2 Options
=over
=item ConvertTo 'days'|'hours'|'minutes'|'seconds'
convert the given time interval to this unit of time measurement, if not specified, the default
value is 'seconds'
=item days
specify number of days
=item hours
specify number of hours
=item minutes
specify number of minutes
=item seconds
specify number of seconds
=back
=head1 parseInterval
this will convert the given time interval to the number of days, hours, minutes and seconds.
=head2 Returned Data Format
unless the 'String' option is specified, this routine returns a has reference containing the
following data:
\%data = (
'days' => $number_of_days,
'hours' => $number_of_hours,
'minutes' => $number_of_minutes,
'seconds' => $number_of_seconds
);
=head2 Options
=over
=item days
specify number of days
=item hours
specify number of hours
=item minutes
specify number of minutes
=item seconds
specify number of seconds
=item String
if this option is specified as a non-zero value a string containing the number of days, hours,
minutes, and seconds is returned, for example:
"70 days, 16 hours, 56 minutes, 18 seconds"
=item Small
if this option is specified as a non-zero value a string containing the number of days, hours,
minutes, and seconds is returned in abbreviated form (dhms format), for example:
"70d 16h 56m 18s"
=back
=head1 coalesce
given a set of time intervals (start and end time pairs), this method will return the minimum set
based on overlapping time spans. That is, this method will return a list of unique contiguous time
intervals from the given list. As with the other methods in this package, time strings may be
submitted in any of the formats supported by Date::Parse. Data is returned as it was passed in, as
a reference to an array of array references (see below).
=head2 Arguments
coalesce takes only one argument, an array reference. The reference should be to an array of array
references, each of which contains a start and an end time. For a quick example, take a look at the
SYNOPSIS section.
=head1 Author:
Andrew N. Hicox <ahicox@hicox.com>
http://www.hicox.com