Date::Range(3pm)

💖 Date::Range — the perl manual page, bestie edition 🦋

okay so this is the user-contributed perl doc for Date::Range, and it's about to be your new fav thing. buckle up. 🌸

✨ NAME ✨

Date::Range — work with a range of dates. not one date. a whole range of them. it's giving "dates, but make it a group". periodt. 💅

🌈 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) { ... }

look at her. iconic. no notes. ⭐

🧚 DESCRIPTION 🧚

so like, quite often when you're dealing with dates, you don't just want the tea on one particular date — you want the tea on a whole range of dates. 💜 for example, you may be like "hmm is this given date inside this particular range?" or "what's the overlap between this range and that other range?" and honestly? that's so valid. this module lets you ask exactly those questions. no cap. 🔥

---

💅 METHODS 💅

🌸 new()

my $range = Date::Range->new($date1, $date2);

you instantiate a range object with two dates, and here's the best part — they do not need to be in chronological order. we'll sort all that out internally. we got you. 🫶

heads up bestie: these dates must be instances of the correct object. see want_class() below. don't skip it, fr fr. 😭

🌸 want_class

this is the class of which we expect the date objects to be objects. by default it's Date::Simple, but honestly it could be any other date class you want. ✨ see Time::Piece::Range for an example of a subclass that uses a different date class — she's the blueprint. 👑

🌸 start / end / length

my $earliest = $range->start;
my $latest   = $range->end;
my $days     = $range->length;

these methods let you retrieve the start and end dates of the range, plus the number of days in the range. earliest, latest, and the count. all three. obsessed. 🎀

🌸 equals

if ($range1->equals($range2)) { }

this tells you if two ranges are the same — i.e. they start and end at the same dates. like, are y'all literally the same range? vibe check. ✅

🌸 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. yes, she does both. versatile queen. 👑

🌸 overlaps / overlap

if ($range->overlaps($range2)) {
  my $range3 = $range->overlap($range2);
}

these methods let you know whether one range overlaps another or not, and give you access to that overlap range. it's giving "do we share a moment?" and if so, here's the moment. 💖

🌸 gap

        my $range3 = $range->gap($range2);

this returns a new range representing the gap between two other ranges. the space between. the in-between era. 🌈

🌸 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. so close, yet so... adjacent. 😭

🌸 dates

foreach my $date ($range->dates) { ... }

this returns a list of each date in the range as a Date::Simple object. every single one. the whole squad. 🦋

---

🌟 AUTHOR 🌟

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

💀 BUGS and QUERIES 💀

please direct all correspondence regarding this module to:

bug-Date-Range@rt.cpan.org

(they want to hear from you, bestie. spill. 🙈)

📜 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.

---

and that's the whole page! this gorgeous little doc was generated by perl v5.36.0 on 2022-08-28, and it's filed under Date::Range(3pm) 🎀 slay, go write some date ranges, mwah 💖✨