NAME

Date::Span -- deal with date/time ranges than span multiple dates

SYNOPSIS

use Date::Span;

@spanned = range_expand($start, $end);

print "from $_->[0] to $_->[1]\n" for (@spanned);

DESCRIPTION

This module provides code for dealing with datetime ranges that span multiple calendar days. This is useful for computing, for example, the amount of seconds spent performing a task on each day. Given the following table:

 event   | begun            | ended
---------+------------------+------------------
 loading | 2004-01-01 00:00 | 2004-01-01 12:45
 venting | 2004-01-01 12:45 | 2004-01-02 21:15
 running | 2004-01-02 21:15 | 2004-01-03 00:00

We may want to gather the following data:

date       | event   | time spent
-----------+---------+----------------
2004-01-01 | loading | 12.75 hours
2004-01-01 | venting | 11.25 hours
2004-01-02 | venting | 21.25 hours
2004-01-02 | running |  2.75 hours

Date::Span takes a data like the first and produces data more like the second. (Details on exact interface are below.)

FUNCTIONS

range_durations($start, $end)

Given $start and $end as timestamps (in epoch seconds), range_durations returns a list of arrayrefs. Each arrayref is a date (expressed as epoch seconds at midnight) and the number of seconds for which the given range intersects with the date.

range_expand($start, $end)

Given $start and $end as timestamps (in epoch seconds), range_durations returns a list of arrayrefs. Each arrayref is a start and end timestamp. No pair of start and end times will cross a date boundary, and the set of ranges as a whole will be identical to the passed start and end.

TODO

This code was just yanked out of a general purpose set of utility functions I've compiled over the years. It should be refactored (internally) and further tested. The interface should stay pretty stable, though.

AUTHORS

Ricardo SIGNES, <rjbs@cpan.org>

COPYRIGHT

(C) 2004, Ricardo SIGNES. Date::Span is available under the same terms as Perl itself.