.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Date::Range 3pm"
.TH Date::Range 3pm "2019-12-13" "perl v5.30.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Date::Range \- work with a range of dates
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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) { ... }
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fBnew()\fP"
.IX Subsection "new()"
.Vb 1
\&  my $range = Date::Range\->new($date1, $date2);
.Ve
.PP
A range object is instantiated with two dates, which do not need
to be in chronological order (we'll sort all that out internally).
.PP
These dates must be instances of the correct object. See \fBwant_class()\fR
below.
.SS "want_class"
.IX Subsection "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.
.SS "start / end / length"
.IX Subsection "start / end / length"
.Vb 3
\&  my $earliest = $range\->start;
\&  my $latest   = $range\->end;
\&  my $days     = $range\->length;
.Ve
.PP
These methods allow you retrieve the start and end dates of the range,
and the number of days in the range.
.SS "equals"
.IX Subsection "equals"
.Vb 1
\&  if ($range1\->equals($range2)) { }
.Ve
.PP
This tells you if two ranges are the same \- i.e. start and end at
the same dates.
.SS "includes"
.IX Subsection "includes"
.Vb 2
\&  if ($range\->includes($date3)) { ... }
\&  if ($range\->includes($range2)) { ... }
.Ve
.PP
These methods tell you if a given range includes a given date, 
or a given range.
.SS "overlaps / overlap"
.IX Subsection "overlaps / overlap"
.Vb 3
\&  if ($range\->overlaps($range2)) {
\&    my $range3 = $range\->overlap($range2);
\&  }
.Ve
.PP
These methods let you know whether one range overlaps another or not,
and access this overlap range.
.SS "gap"
.IX Subsection "gap"
.Vb 1
\&        my $range3 = $range\->gap($range2);
.Ve
.PP
This returns a new range representing the gap between two other ranges.
.SS "abuts"
.IX Subsection "abuts"
.Vb 1
\&        if ($range\->abuts($range2)) { ... }
.Ve
.PP
This tells you whether or not two ranges are contiguous \- i.e. there is
no gap between them, but they do not overlap.
.SS "dates"
.IX Subsection "dates"
.Vb 1
\&  foreach my $date ($range\->dates) { ... }
.Ve
.PP
This returns a list of each date in the range as a Date::Simple object.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tony Bowden, based heavily on Martin Fowler's \*(L"Analysis Patterns 2\*(R"
discussion and code at http://www.martinfowler.com/ap2/range.html
.SH "BUGS and QUERIES"
.IX Header "BUGS and QUERIES"
Please direct all correspondence regarding this module to:
  bug\-Date\-Range@rt.cpan.org
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
.Vb 1
\&  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.
.Ve