DateTime::Span(3pm)

📦
version 0.3900 · 7 versions
, in alpine 3.24

💖 DateTime::Span 💖

okay so bestie, you found the DateTime::Span(3pm) page — it's a User Contributed Perl Documentation gem, and we're gonna get you fluent in it. spans are literally the moment, no cap. let's go 🎀

✨ NAME ✨

DateTime::Span — datetime spans, bestie. ranges. periods. the whole "from here to there" vibe. 💅

🌸 SYNOPSIS 🌸

use DateTime;
use DateTime::Span;

$date1 = DateTime->new( year => 2002, month => 3, day => 11 );
$date2 = DateTime->new( year => 2003, month => 4, day => 12 );
$set2 = DateTime::Span->from_datetimes( start => $date1, end => $date2 );
#  set2 = 2002-03-11 until 2003-04-12

$set = $set1->union( $set2 );         # like "OR", "insert", "both"
$set = $set1->complement( $set2 );    # like "delete", "remove"
$set = $set1->intersection( $set2 );  # like "AND", "while"
$set = $set1->complement;             # like "NOT", "negate", "invert"

if ( $set1->intersects( $set2 ) ) { ...  # like "touches", "interferes"
if ( $set1->contains( $set2 ) ) { ...    # like "is-fully-inside"

# data extraction
$date = $set1->start;           # first date of the span
$date = $set1->end;             # last date of the span

🦋 DESCRIPTION 🦋

DateTime::Span is the module you reach for when you're handling datetime spans — you might know them as ranges, or periods, as in "from X to Y, inclusive of all datetimes in between". 🫶

and like, this is different from a DateTime::Set, okay? a DateTime::Set is made of individual datetime points, whereas this is a range. also there's a DateTime::SpanSet module for handling sets of spans, iykyk. 💜

👑 METHODS 👑 (the main character section)

  • from_datetimes — creates a new span based on a starting and ending datetime. this one has options, bestie, listen up:

a 'closed' span includes its end-dates:

$span = DateTime::Span->from_datetimes( start => $dt1, end => $dt2 );

an 'open' span does not include its end-dates:

$span = DateTime::Span->from_datetimes( after => $dt1, before => $dt2 );

a 'semi-open' span includes one of its end-dates:

$span = DateTime::Span->from_datetimes( start => $dt1, before => $dt2 );
$span = DateTime::Span->from_datetimes( after => $dt1, end => $dt2 );

a span might have just a starting date, or just an ending date. these spans end, or start, in an imaginary 'forever' date:

$span = DateTime::Span->from_datetimes( start => $dt1 );
$span = DateTime::Span->from_datetimes( end => $dt2 );
$span = DateTime::Span->from_datetimes( after => $dt1 );
$span = DateTime::Span->from_datetimes( before => $dt2 );
⚠️ you cannot give both a start and after argument, and you also can't give both an end and before argument. either of these conditions will cause the from_datetimes() method to die. literally fatal, no cap. 💀

to summarize (and this is the part to remember fr fr): a datetime passed as either start or end is included in the span. a datetime passed as either after or before is excluded from the span. ✨

  • from_datetime_and_duration — creates a new span. 🧚
$span = DateTime::Span->from_datetime_and_duration(
    start => $dt1, duration => $dt_dur1 );
$span = DateTime::Span->from_datetime_and_duration(
    after => $dt1, hours => 12 );

the new "end of the set" is open by default.

  • clone — this object method returns a replica of the given object. a little copy, a lil twin, iconic behavior. 🎀
  • set_time_zone( $tz ) — this method accepts either a time zone object or a string that can be passed as the "name" parameter to DateTime::TimeZone->new(). if the new time zone's offset is different from the old time zone, then the local time is adjusted accordingly. 🕰️

if the old time zone was a floating time zone, then no adjustments to the local time are made, except to account for leap seconds. if the new time zone is floating, then the UTC time is adjusted in order to leave the local time untouched. (yes, the floating-time-zone lore goes deep. iykyk.)

  • duration — the total size of the set, as a DateTime::Duration object, or as a scalar containing infinity. ♾️

also available as size().

  • start, min — first date in the span. (grouped with end, max below, they're a duo 💜)
  • end, max — last date in the span.

first or last dates in the span, bestie. it is possible that the return value from these methods may be a DateTime::Infinite::Future or a DateTime::Infinite::Past object.

if the set ends "before" a date $dt, it returns $dt. note that in this case $dt is not a set element — but it is a set boundary. 🙈

these methods return just a copy of the actual boundary value. if you modify the result, the set will not be modified. (protect the original at all costs, periodt.)

  • start_is_closed — returns true if the first date belongs to the span ( start <= x <= end ).
  • end_is_closed — returns true if the last date belongs to the span ( start <= x <= end ).
  • start_is_open — returns true if the first date is excluded from the span ( start < x < end ).
  • end_is_open — returns true if the last date is excluded from the span ( start < x < end ).
  • union, intersection, complement — set operations! and the slay part? these may be performed not only with DateTime::Span objects, but also with DateTime::Set and DateTime::SpanSet objects. these set operations always return a DateTime::SpanSet object. 🔥
$set = $span->union( $set2 );         # like "OR", "insert", "both"
$set = $span->complement( $set2 );    # like "delete", "remove"
$set = $span->intersection( $set2 );  # like "AND", "while"
$set = $span->complement;             # like "NOT", "negate", "invert"
  • intersects, contains — these set functions return a boolean value. ✅
if ( $span->intersects( $set2 ) ) { ...  # like "touches", "interferes"
if ( $span->contains( $dt ) ) { ...    # like "is-fully-inside"

these methods can accept a DateTime, DateTime::Set, DateTime::Span, or DateTime::SpanSet object as an argument. so many options, we love a flexible icon. 💅

🫶 SUPPORT 🫶

support is offered through the "datetime@perl.org" mailing list. 💌

please report bugs using rt.cpan.org.

🌈 AUTHOR 🌈

Flavio Soibelmann Glock <fglock@gmail.com> ✨

the API was developed together with Dave Rolsky and the DateTime Community. (collab of the century, ngl.)

Copyright (c) 2003-2006 Flavio Soibelmann Glock. All rights reserved. This program is free software; you can distribute it and/or modify it under the same terms as Perl itself.

the full text of the license can be found in the LICENSE file included with this module. 📄

⭐ SEE ALSO ⭐

Set::Infinite

for details on the Perl DateTime Suite project please see <http://datetime.perl.org>. 🔗

and that's the whole page, bestie! 🎉 this was DateTime::Span(3pm) from perl v5.42.2, dated 2026-02-15 — go forth and span, you absolute icon 🦋💜

📦 where this page comes from