yearly monthly weekly daily hourly minutely secondly
These methods all return a new DateTime::Set object representing the given recurrence.
If no parameters are given, then the set members each occur at the beginning of the specified recurrence.
For example, by default, the monthly() method returns a set containing the first day of each month.
Without parameters, the weekly() method returns a set containing Mondays.
However, you can pass in parameters to alter where these datetimes fall. The parameters are the same as those given to the DateTime::Duration constructor for specifying the length of a duration. For example, to create a set representing a daily recurrence at 10:30 each day, we write this:
To represent every Tuesday (second day of the week):
A negative duration counts backwards from the end of the period. This is done in the same manner as is specified in RFC 2445 (iCal).
Negative durations are useful for creating recurrences such as the last day of each month:
You can also provide multiple sets of duration arguments, such as this:
This specifies a recurrence occurring every day at these 9 different times:
To create a set of recurrences occurring every thirty seconds, we could do this:
The following is also valid. See the section on the interval parameter:
Invalid values are skipped at run time.
For example, when days are added to a month, the result is checked for a nonexisting day (such as 31 or 30), and the invalid datetimes are skipped.
Another example of this would be creating a set via the daily() method and specifying hours => 25.
The days parameter can be combined with yearly, monthly, and weekly recurrences, resulting in six possible meanings:
# tuesday of every week my $set = DateTime::Event::Recurrence->weekly( days => 2 ); # 10th day of every month my $set = DateTime::Event::Recurrence->monthly( days => 10 ); # second tuesday of every month my $set = DateTime::Event::Recurrence->monthly( weeks => 2, days => 2 ); # 10th day of every year my $set = DateTime::Event::Recurrence->yearly( days => 10 ); # 10th day of every december my $set = DateTime::Event::Recurrence->yearly( months => 12, days => 10 ); # second tuesday of every year my $set = DateTime::Event::Recurrence->yearly( weeks => 2, days => 2 );
Week days can also be called by name, as is specified in RFC 2445 (iCal):
The interval parameter represents how often the recurrence rule repeats.
The optional start parameter specifies where to start counting:
This specifies a recurrence that happens at 10:30 on the day specified by start => $dt, and then every 11 days before and after $dt. So we get a set like this:
... 2003-06-04T10:30:00, 2003-06-15T10:30:00, 2003-06-26T10:30:00, ...
In this case, the method is used to specify the unit, so daily() means that our unit is a day, and interval => 11 specifies the quantity of our unit.
The start parameter should have no time zone.
The week_start_day parameter is intended for internal use by the DateTime::Event::ICal module, for generating RFC2445 recurrences.
The week_start_day represents how the first week of a period is calculated:
Defaults to 1mo Yearly recurrences default to mo (yearly())
mo, tu, we, th, fr, sa, su - The first week is one that starts on this week-day, and has the most days in this period. Works for weekly and yearly recurrences.
1mo, 1tu, 1we, 1th, 1fr, 1sa, 1su - The first week is one that starts on this week-day, and has all days in this period. This works for weekly(), monthly() and yearly() recurrences.
Recurrences are created in the floating time zone, as specified in the DateTime module.
If you want to specify a time zone for a recurrence, you can do this by calling set_time_zone() on the returned set:
You can also pass a DateTime.pm object with a time zone to the sets next() and previous() methods:
my $dt = DateTime->today( time_zone => Europe/Berlin ); my $next = $daily->next($dt);
A recurrence can be affected DST changes, so it would be possible to specify a recurrence that creates nonexistent datetimes. Because DateTime.pm throws an exception if asked to create a non-existent datetime, please be careful when setting a time zone for your recurrence.
It might be preferable to always use UTC for your sets, and then convert the returned object to the desired time zone.
There are no leap seconds, because the recurrences are created in the floating time zone.
The value 60 for seconds (the leap second) is ignored. If you really want the leap second, then specify the second as -1.
Flavio Soibelmann Glock email@example.com
The API was developed with help from the people in the firstname.lastname@example.org list.
Special thanks to Dave Rolsky, Ron Hill and Matt Sisk for being around with ideas.
If you can understand what this module does by reading the docs, you should thank Dave Rolsky. If you cant understand it, yell at him. He also helped removing weird idioms from the code.
Copyright (c) 2003 Flavio Soibelmann Glock. All rights reserved. This program is free software; you can redistribute 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.
email@example.com mailing list
DateTime Web page at http://datetime.perl.org/
DateTime - date and time :)
DateTime::SpanSet - sets of intervals, including recurring sets of intervals.
|perl v5.20.3||DATETIME::EVENT::RECURRENCE (3)||2015-11-11|