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.
duration
duration( unit => months, duration => 10 )All intervals for the quantize function are modified to 'duration'.
'unit' parameter can be years, months, days, weeks, hours, minutes, or seconds.
rrule
rrule ( 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) ]
(some documentation needed!)
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.
'byday' does not understand (scalar . string) formats yet (like '-2FR')
'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.