--- name: "DateTime::Span" section: "3pm" platform: "linux" package: "perl-datetime-set" version: "0.3900-5" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/DateTime::Span" --- # DateTime::Span(3pm) Datetime spans ## NAME DateTime::Span - Datetime spans ## 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 a module for handling datetime spans, otherwise known as ranges or periods ("from X to Y, inclusive of all datetimes in between"). This is different from a `"DateTime::Set"`, which is made of individual datetime points as opposed to a range. There is also a module `"DateTime::SpanSet"` to handle sets of spans. ## METHODS - • from\_datetimes Creates a new span based on a starting and ending datetime. 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, nor can you give both an "end" and "before" argument. Either of these conditions will cause the `from_datetimes()` method to die. To summarize, 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. - • 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. - • duration The total size of the set, as a `"DateTime::Duration"` object, or as a scalar containing infinity. Also available as `size()`. - • start, min - • end, max First or last dates in the span. It is possible that the return value from these methods may be a `"DateTime::Infinite::Future"` or a `"DateTime::Infinite::Past"`xs 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. - • start\_is\_closed - • end\_is\_closed Returns true if the first or last dates belong to the span ( start \<= x \<= end ). - • start\_is\_open - • end\_is\_open Returns true if the first or last dates are excluded from the span ( start \< x \< end ). - • union - • intersection - • complement Set operations 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. ## SUPPORT Support is offered through the `"datetime@perl.org"` mailing list. Please report bugs using rt.cpan.org ## AUTHOR Flavio Soibelmann Glock \ The API was developed together with Dave Rolsky and the DateTime Community. ## COPYRIGHT 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 \.