DateTime::Event::Recurrence - DateTime::Set extension for create basic recurrence sets


NAME

DateTime::Event::Recurrence - DateTime::Set extension for create basic recurrence sets


SYNOPSIS

 use DateTime;
 use DateTime::Event::Recurrence;
 
 my $dt = DateTime->new( year   => 2000,
                         month  => 6,
                         day    => 20,
                       );
 my $daily_set = DateTime::Event::Recurrence->daily;
 my $dt_next = $daily_set->next( $dt );
 my $dt_previous = $daily_set->previous( $dt );
 my $bool = $daily_set->contains( $dt );
 my @days = $daily_set->as_list( start => $dt1, end => $dt2 );
 my $iter = $daily_set->iterator;
 while ( my $dt = $iter->next ) {
     print ' ', $dt->datetime;
 }


DESCRIPTION

This module provides convenience methods that let you easily create DateTime::Set objects for various recurrences, such as ``once a month'' or ``every day''. You can also create more complicated recurrences, such as ``every Monday, Wednesday and Thursday at 10:00 AM and 2:00 PM''.


USAGE

Invalid DateTimes

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

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):

  my $weekly_on_tuesday_set =
      DateTime::Event::Recurrence->weekly( days => 'tu' );
      
The "days" parameter defaults to "the first day".
See also the section on the "week start day" parameter.
    
    # second monday of every month
    my $set = DateTime::Event::Recurrence->monthly( weeks => 2 );
    
=head2 The "interval" and "start" Parameters

The ``interval'' parameter represents how often the recurrence rule repeats.

The optional ``start'' parameter specifies where to start counting:

    my $dt_start = DateTime->new( year => 2003, month => 6, day => 15 );
    my $set = DateTime::Event::Recurrence->daily
                  ( interval => 11,
                    hours    => 10,
                    minutes  => 30,
                    start    => $dt_start,
                  );

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

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:

``mo'' - this is the default. The first week is one that starts in monday, and has the most days in this period.

``tu'', ``we'', ``th'', ``fr'', ``sa'', ``su'' - The first week is one that starts in this week-day, and has the most days in this period. Works for weekly and yearly recurrences.

``1tu'', ``1we'', ``1th'', ``1fr'', ``1sa'', ``1su'' - The first week is one that starts in this week-day, and has all days in this period. This works for weekly(), monthly() and yearly() recurrences.

Time Zones

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:

  my $daily = DateTime::Event::Recurrence->daily;
  $daily->set_time_zone( 'Europe/Berlin' );

You can also pass a DateTime.pm object with a time zone to the set's 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.

Leap Seconds

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.


AUTHOR

Flavio Soibelmann Glock fglock@pucrs.br


CREDITS

The API was developed with help from the people in the datetime@perl.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 can't understand it, yell at him. He also helped removing weird idioms from the code.

Jerrad Pierce came with the idea to move ``interval'' from DateTime::Event::ICal to here.


COPYRIGHT

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.


SEE ALSO

datetime@perl.org mailing list

DateTime Web page at http://datetime.perl.org/

DateTime - date and time :)

DateTime::Set - for recurrence-set accessors docs. You can use DateTime::Set to specify recurrences using callback subroutines.

DateTime::Event::ICal - if you need more complex recurrences.

DateTime::SpanSet - sets of intervals, including recurring sets of intervals.

 DateTime::Event::Recurrence - DateTime::Set extension for create basic recurrence sets