DateTime::Span - Datetime spans
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
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").
DateTime::Span
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.
DateTime::Set
DateTime::SpanSet
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.
from_datetimes()
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.
DateTime::TimeZone->new()
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.
DateTime::Duration
Also available as size().
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::Pastxs object.
DateTime::Infinite::Future
DateTime::Infinite::Past
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.
before
$dt
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.
DateTime
Support is offered through the datetime@perl.org mailing list.
datetime@perl.org
Please report bugs using rt.cpan.org
Flavio Soibelmann Glock <fglock@gmail.com>
The API was developed together with Dave Rolsky and the DateTime Community.
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.
Set::Infinite
For details on the Perl DateTime Suite project please see http://datetime.perl.org.
To install DateTime::Set, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DateTime::Set
CPAN shell
perl -MCPAN -e shell install DateTime::Set
For more information on module installation, please visit the detailed CPAN module installation guide.