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.

cpanm Date::Range

perl -MCPAN -e shell
install Date::Range