NAME
Date::Range - deal with a range of dates
SYNOPSIS
use Date::Range;
my $range = Date::Range->new($date1, $date2);
my $earliest = $range->start;
my $latest = $range->end;
my $days = $range->length;
if ($range->includes($date3)) { ... }
if ($range->includes($range2)) { ... }
if ($range->overlaps($range2)) {
my $range3 = $range->overlap($range2);
}
foreach my $date ($range->dates) { ... }
DESCRIPTION
Quite often, when dealing with dates, we don't just want to know information about one particular date, but about a range of dates. For example, we may wish to know whether a given date is in a particular range, or what the overlap is between one range and another. This module lets you ask such questions.
METHODS
new()
my $range = Date::Range->new($date1, $date2);
A range object is instantiated with two dates, which do not need to be in chronological order (we'll sort all that out internally).
These dates must be instances of the want_class().
want_class
The class of which we expect the data objects to be objects. By default this is Date::Simple, but this could be any other date class. See Time::Piece::Range for an example of a subclass using a different class.
start / end / length
my $earliest = $range->start;
my $latest = $range->end;
my $days = $range->length;
These methods allow you retrieve the start and end dates of the range, and the number of days in the range.
equals
if ($range1->equals($range2)) { }
This tells you if two ranges are the same - i.e. start and end at the same dates.
includes
if ($range->includes($date3)) { ... }
if ($range->includes($range2)) { ... }
These methods tell you if a given range includes a given date, or a given range.
overlaps / overlap
if ($range->overlaps($range2)) {
my $range3 = $range->overlap($range2);
}
These methods let you know whether one range overlaps another or not, and access this overlap range.
gap
my $range3 = $range->gap($range2);
This returns a new range representing the gap between two other ranges.
abuts
if ($range->abuts($range2)) { ... }
This tells you whether or not two ranges are contiguous - i.e. there is no gap between them, but they do not overlap.
dates
foreach my $date ($range->dates) { ... }
This returns a list of each date in the range as a Date::Simple object.
AUTHOR
Tony Bowden, based heavily on Martin Fowler's "Analysis Patterns 2" discussion and code at http://www.martinfowler.com/ap2/range.html
BUGS and QUERIES
Please direct all correspondence regarding this module to: bug-Date-Range@rt.cpan.org
COPYRIGHT AND LICENSE
Copyright (C) 2001-2005 Tony Bowden.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License; either version
2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.