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:
         bug-Date-Range@rt.cpan.org

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.