1Date::Range(3)        User Contributed Perl Documentation       Date::Range(3)
2
3
4

NAME

6       Date::Range - work with a range of dates
7

SYNOPSIS

9         use Date::Range;
10
11         my $range = Date::Range->new($date1, $date2);
12
13         my $earliest = $range->start;
14         my $latest   = $range->end;
15         my $days     = $range->length;
16
17         if ($range->includes($date3)) { ... }
18         if ($range->includes($range2)) { ... }
19
20         if ($range->overlaps($range2)) {
21           my $range3 = $range->overlap($range2);
22         }
23
24         foreach my $date ($range->dates) { ... }
25

DESCRIPTION

27       Quite often, when dealing with dates, we don't just want to know
28       information about one particular date, but about a range of dates. For
29       example, we may wish to know whether a given date is in a particular
30       range, or what the overlap is between one range and another.  This
31       module lets you ask such questions.
32

METHODS

34   new()
35         my $range = Date::Range->new($date1, $date2);
36
37       A range object is instantiated with two dates, which do not need to be
38       in chronological order (we'll sort all that out internally).
39
40       These dates must be instances of the correct object. See want_class()
41       below.
42
43   want_class
44       The class of which we expect the date objects to be objects. By default
45       this is Date::Simple, but this could be any other date class. See
46       Time::Piece::Range for an example of a subclass that uses a different
47       date class.
48
49   start / end / length
50         my $earliest = $range->start;
51         my $latest   = $range->end;
52         my $days     = $range->length;
53
54       These methods allow you retrieve the start and end dates of the range,
55       and the number of days in the range.
56
57   equals
58         if ($range1->equals($range2)) { }
59
60       This tells you if two ranges are the same - i.e. start and end at the
61       same dates.
62
63   includes
64         if ($range->includes($date3)) { ... }
65         if ($range->includes($range2)) { ... }
66
67       These methods tell you if a given range includes a given date, or a
68       given range.
69
70   overlaps / overlap
71         if ($range->overlaps($range2)) {
72           my $range3 = $range->overlap($range2);
73         }
74
75       These methods let you know whether one range overlaps another or not,
76       and access this overlap range.
77
78   gap
79               my $range3 = $range->gap($range2);
80
81       This returns a new range representing the gap between two other ranges.
82
83   abuts
84               if ($range->abuts($range2)) { ... }
85
86       This tells you whether or not two ranges are contiguous - i.e. there is
87       no gap between them, but they do not overlap.
88
89   dates
90         foreach my $date ($range->dates) { ... }
91
92       This returns a list of each date in the range as a Date::Simple object.
93

AUTHOR

95       Tony Bowden, based heavily on Martin Fowler's "Analysis Patterns 2"
96       discussion and code at http://www.martinfowler.com/ap2/range.html
97

BUGS and QUERIES

99       Please direct all correspondence regarding this module to:
100         bug-Date-Range@rt.cpan.org
101

103         Copyright (C) 2001-2006 Tony Bowden.
104
105         This program is free software; you can redistribute it and/or modify
106         it under the terms of the GNU General Public License; either version
107         2 of the License, or (at your option) any later version.
108
109         This program is distributed in the hope that it will be useful,
110         but WITHOUT ANY WARRANTY; without even the implied warranty of
111         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
112
113
114
115perl v5.36.0                      2022-07-22                    Date::Range(3)
Impressum