NAME
Date::Set - Date set math
SYNOPSIS
use Date::Set;
my $interval = Date::Set->new('20010501')->quantize(unit=>'months');
# print "This month: ", $interval, "\n\n";
# print "Weeks this month: ", $interval->quantize(unit=>'weeks'), "\n\n";
# print "Tuesdays this month: ", $interval->quantize(unit=>'weeks')->
offset( mode => 'begin', unit=>'days', value => [ 2, 3] );
# TODO: add some examples of RRULE syntax.
#
DESCRIPTION
Date::Set is a module for date/time sets. It allows you to generate groups of dates, like "every Wednesday", and then find all the dates matching that pattern. It waits until you ask for a particular recurrence before calculating it.
If you want to understand the context of this module, look at IETF RFC 2445 (iCalendar), which specifies a particular syntax for describing recurring events.
It requires Date::ICal and Set::Infinite. If you don't need iCalendar functionality, use Set::Infinite instead.
METHODS
event
event()Constructor. Returns 'forever', that is: (-Inf .. Inf). If you use this method, *must* limit the event by calling dtstart() to set a starting date for the event.
period
period( time => [time1, time2] )Another constructor. Returns "[time1 .. time2]" when called in a scalar context.
dtstart
dtstart( start => time1 )Returns set intersection [time1 .. Inf)
'dtstart' puts a limit on when the event starts. If the event already starts AFTER dtstart, it will not change.
dtend
dtend( end => time1 )Returns set intersection (Inf .. time1]
'dtend' puts a limit on when the event finishes. If the event already finish BEFORE dtend, it will not change.
duration
duration( unit => 'months', duration => 10 )All intervals are modified to 'duration'.
'unit' parameter can be years, months, days, weeks, hours, minutes, or seconds.
rrule
rrule ( period => date-set, DTSTART => time,
BYMONTH => [ list ], BYWEEKNO => [ list ],
BYYEARDAY => [ list ], BYMONTHDAY => [ list ],
BYDAY => [ list ], BYHOUR => [ list ],
BYMINUTE => [ list ], BYSECOND => [ list ],
BYSETPOS => [ list ],
UNTIL => time, FREQ => freq, INTERVAL => n, COUNT => n,
WKST => day )Implements RRULE from RFC2445.
FREQ can be: SECONDLY MINUTELY HOURLY DAILY WEEKLY MONTHLY or YEARLY
WKST and BYDAY list may contain: SU MO TU WE TH FR SA
BYxxx items must be array references (must be bracketed): BYMONTH => [ 10 ] or BYMONTH => [ 10, 11, 12 ] or BYMONTH => [ qw(10 11 12) ]
There are two operating modes: without 'period' it will filter out the rule from the set; with 'period' it will filter out the rule from the period, then add the list to the set.
DTSTART value can be given explicitly, otherwise it will be taken from 'period' or from the set.
exrule
exrule ( period => date-set, DTSTART => time,
BYMONTH => [ list ], BYWEEKNO => [ list ],
BYYEARDAY => [ list ], BYMONTHDAY => [ list ],
BYDAY => [ list ], BYHOUR => [ list ],
BYMINUTE => [ list ], BYSECOND => [ list ],
BYSETPOS => [ list ],
UNTIL => time, FREQ => freq, INTERVAL => n, COUNT => n,
WKST => day )Implements EXRULE (exclusion-rule) from RFC2445.
'period' is optional.
rdate
rdate( list => [time1, time2, ...] )Adds the (scalar) list to the set, or creates a new list.
exdate
exdate( list => [time1, time2, ...] )Removes each element of the list from the set.
occurrences
occurrences( period => date-set )Returns the occurrences for a given period. In other words, "when does this event occur during the given period?"
INHERITED METHODS
These methods are inherited from Set::Infinite.
Logic
$logic = $a->intersects($b);
$logic = $a->contains($b);
$logic = $a->is_null;Set
$i = $a->union($b);
$i = $a->intersection($b);
$i = $a->complement;
Note: 'unit' parameter can be years, months, days, weeks, hours, minutes, or seconds. BUGS
'rrule' method is not yet fully RFC2445 compliant.
'duration' and 'period' methods may change in future versions, to generate open-ended sets.
'WEEKLY' does not use 'WKST'
rrule syntax needs uppercase parameters
AUTHOR
Flavio Soibelmann Glock <fglock@pucrs.br> with the Reefknot team.