NAME
DateTime::Set - Datetime sets and set math
SYNOPSIS
use DateTime;
use DateTime::Set;
$date1 = DateTime->new( year => 2002, month => 3, day => 11 );
$set1 = DateTime::Set->from_datetimes( dates => [ $date1 ] );
# set1 = 2002-03-11
$date2 = DateTime->new( year => 2003, month => 4, day => 12 );
$set2 = DateTime::Set->from_datetimes( dates => [ $date1, $date2 ] );
# set2 = 2002-03-11, and 2003-04-12
# a 'monthly' recurrence:
$set = DateTime::Set->from_recurrence(
recurrence => sub {
$_[0]->truncate( to => 'month' )->add( months => 1 )
},
span => $date_span1, # optional span
);
$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->min; # first date of the set
$date = $set1->max; # last date of the set
$iter = $set1->iterator;
while ( $dt = $iter->next ) {
print $dt->ymd;
};
DESCRIPTION
DateTime::Set is a module for date/time sets. It can be used to handle two different types of sets.
The first is a fixed set of predefined datetime objects. For example, if we wanted to create a set of dates containing the birthdays of people in our family.
The second type of set that it can handle is one based on the idea of a recurrence, such as "every Wednesday", or "noon on the 15th day of every month". This type of set can have fixed starting and ending datetimes, but neither is required. So our "every Wednesday set" could be "every Wednesday from the beginning of time until the end of time", or "every Wednesday after 2003-03-05 until the end of time", or "every Wednesday between 2003-03-05 and 2004-01-07".
METHODS
from_datetimes
Creates a new set from a list of dates.
$dates = DateTime::Set->from_datetimes( dates => [ $dt1, $dt2, $dt3 ] );
from_recurrence
Creates a new set specified via a "recurrence" callback.
$months = DateTime::Set->from_recurrence( span => $dt_span_this_year, # optional span recurrence => sub { $_[0]->truncate( to => 'month' )->add( months => 1 ) }, );
The
span
parameter is optional. It must be aDateTime::Span
object.The span can also be specified using
begin
/after
andbefore
/end
parameters, as in theDateTime::Span
constructor. In this case, if there is aspan
parameter it will be ignored.$months = DateTime::Set->from_recurrence( after => $dt_now, recurrence => sub { $_[0]->truncate( to => 'month' )->add( months => 1 ) }, );
The recurrence will be passed a single parameter, a DateTime.pm object. The recurrence must generate the next event after that object. There is no guarantee as to what the object will be set to, only that it will be greater than the last object passed to the recurrence.
For example, if you wanted a recurrence that generated datetimes in increments of 30 seconds would look like this:
sub every_30_seconds { my $dt = shift; $dt->truncate( to => 'seconds' ); if ( $dt->second < 30 ) { $dt->add( seconds => 30 - $dt->second ); } else { $dt->add( seconds => 60 - $dt->second ); } }
Of course, this recurrence ignores leap seconds, but we'll leave that as an exercise for the reader ;)
It is also possible to create a recurrence by specifying either or both 'next' and 'previous' callbacks.
See also
DateTime::Event::Recurrence
and the otherDateTime::Event::*
modules for generating specialized recurrences, such as sunrise and sunset time, and holidays.empty_set
Creates a new empty set.
clone
This object method returns a replica of the given object.
add_duration( $duration )
$dtd = new DateTime::Duration( year => 1 ); $new_set = $set->add( duration => $dtd );
This method returns a new set which is the same as the existing set with the specified duration added to every element of the set.
add
$meetings_2004 = $meetings_2003->add( years => 1 );
This method is syntactic sugar around the
add_duration()
method.subtract_duration( $duration_object )
When given a
DateTime::Duration
object, this method simply callsinvert()
on that object and passes that new duration to theadd_duration
method.subtract( DateTime::Duration->new parameters )
Like
add()
, this is syntactic sugar for thesubtract_duration()
method.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.
min / max
The first and last dates in the set. These methods may return
undef
if the set is empty. It is also possible that these methods may return aDateTime::Infinite::Past
orDateTime::Infinite::Future
object.span
Returns the total span of the set, as a
DateTime::Span
object.iterator / next / previous
These methods can be used to iterate over the dates in a set.
$iter = $set1->iterator; while ( $dt = $iter->next ) { print $dt->ymd; }
The boundaries of the iterator can be limited by passing it a
span
parameter. This should be aDateTime::Span
object which delimits the iterator's boundaries. Optionally, instead of passing an object, you can pass any parameters that would work for one of theDateTime::Span
class's constructors, and an object will be created for you.Obviously, if the span you specify does is not restricted both at the start and end, then your iterator may iterate forever, depending on the nature of your set. User beware!
The
next()
orprevious()
method will returnundef
when there are no more datetimes in the iterator.as_list
Returns a list of
DateTime
objects.my @dt = $set->as_list( span => $span );
Just as with the
iterator()
method, theas_list()
method can be limited by a span.If a set is specified as a recurrence and has no fixed begin and end datetimes, then
as_list
will returnundef
unless you limit it with a span. Please note that this is explicitly not an empty list, since an empty list is a valid return value for empty sets!count
Returns a count of
DateTime
objects in the set.my $n = $set->count( span => $span );
Just as with the
iterator()
method, thecount()
method can be limited by a span.If a set is specified as a recurrence and has no fixed begin and end datetimes, then
count
will returnundef
, unless you limit it with a span. Please note that this is explicitly not a scalarzero
, since a zero count is a valid return value for empty sets!union / intersection / complement
These set operation methods can accept a
DateTime
list, aDateTime::Set
, aDateTime::Span
, or aDateTime::SpanSet
object as an argument.$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"
The
union
of aDateTime::Set
with aDateTime::Span
or aDateTime::SpanSet
object returns aDateTime::SpanSet
object.If
complement
is called without any arguments, then the result is aDateTime::SpanSet
object representing the spans between each of the set's elements. If complement is given an argument, then the return value is aDateTime::Set
object.All other operations will always return a
DateTime::Set
.intersects / contains
These set operations result in a boolean value.
if ( $set1->intersects( $set2 ) ) { ... # like "touches", "interferes" if ( $set1->contains( $dt ) ) { ... # like "is-fully-inside"
These methods can accept a
DateTime
list, aDateTime::Set
, aDateTime::Span
, or aDateTime::SpanSet
object as an argument.previous / next / current / closest
my $dt = $set->next( $dt ); my $dt = $set->previous( $dt );
These methods are used to find a set member relative to a given datetime.
The
current()
method returns$dt
if $dt is an event, otherwise it returns the previous event.The
closest()
method returns$dt
if $dt is an event, otherwise it returns the closest event (previous or next).All of these methods may return
undef
if there is no matching datetime in the set.
SUPPORT
Support is offered through the datetime@perl.org
mailing list.
Please report bugs using rt.cpan.org
AUTHOR
Flavio Soibelmann Glock <fglock@pucrs.br>
The API was developed together with Dave Rolsky and the DateTime Community.
COPYRIGHT
Copyright (c) 2003 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.