NAME
   Date::Range - work 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 correct object. See want_class()
   below.

 want_class
   The class of which we expect the date 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 that uses a different
   date 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:
   [email protected]

COPYRIGHT AND LICENSE
     Copyright (C) 2001-2006 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.