NAME

DateTime::Event::Recurrence - Perl DateTime extension for computing basic recurrences.

SYNOPSIS

use DateTime;
use DateTime::Event::Recurrence;

my $dt = DateTime->new( year   => 2000,
                        month  => 6,
                        day    => 20,
                 );

my $r_daily = daily DateTime::Event::Recurrence;

my $dt_next = $daily->next( $dt );

my $dt_previous = $daily->previous( $dt );

my $bool = $daily->contains( $dt );

my $set_days = $r_daily->as_set( start =>$dt1, end=>$dt2 );

my @days = $r_daily->as_list( start =>$dt1, end=>$dt2 );

my $set = $r_daily->intersection($dt_span);
my $iter = $set->iterator;
while ( my $dt = $iter->next ) {
    print ' ',$dt->datetime;
}

DESCRIPTION

This module will return a DateTime Recurrence-set object for a given recurrence rule.

USAGE

• yearly monthly weekly daily hourly minutely secondly

  my $r_daily = daily DateTime::Event::Recurrence;

  Build a DateTime::Event::Recurrence object.

  The constructors might take "duration" arguments:

  my $r_daily_at_evening = daily DateTime::Event::Recurrence( duration => $evening );
  
  my $r_daily_at_10_30 = daily DateTime::Event::Recurrence( hours => 10, minutes => 30 );

  Note: weekly without arguments returns mondays.

  my $r_tuesdays = weekly DateTime::Event::Recurrence( days => 1 );

  A negative duration has the meaning as specified in RFC2445: it counts backwards from the end of the period.

  This is useful for creating recurrences such as last day of month:

  my $r_last_day_of_month = monthly DateTime::Event::Recurrence( days => -1 );

  The constructors do not check for duration overflow, such as a duration bigger than the period. The behaviour in this case is undefined and it might change between versions.

  Note that the 'hours' duration is affected by DST changes and might return unexpected results.

  The constructors can also accept "multi-level" durations, such as the ones used by crontab and in RFC2445.

  my $daily = daily DateTime::Event::Recurrence ( 
      hours => [ -1, 10, 14 ],
      minutes => [ -15, 30, 15 ] );

  specifies a recurrence occuring everyday at these 9 different times:

  09:45,  10:15,  10:30,    # 10h ( -15 / +15 / +30 minutes )
  13:45,  14:15,  14:30,    # 14h ( -15 / +15 / +30 minutes )
  22:45,  23:15,  23:30,    # -1h ( -15 / +15 / +30 minutes )

  This is a recurrence occuring every 30 seconds:

  my $half_minute = minutely DateTime::Event::Recurrence ( 
      seconds => [ 0, 30 ] );

  Multi-level durations can also be specified as an Array-of-Arrays of duration objects:

  # specify a daily recurrence with hours and minutes
  my $daily = daily DateTime::Event::Recurrence ( 
     duration => [ 
         [  # first level: hours
            new DateTime::Duration( hours => -1 ),  # 23h
            new DateTime::Duration( hours => 10 ),
            new DateTime::Duration( hours => 14 ), 
         ],
         [  # second level: minutes
            new DateTime::Duration( minutes => -15 ),  # 45min
            new DateTime::Duration( minutes => 15 ),
            new DateTime::Duration( minutes => 30 ),
         ], 
     ] 
  );

  The durations in an Array-of-Arrays specification must be ordered.

• as_list

  my @dt = $r_daily->as_list( $span );

  This builds a DateTime array of events that happen inside the span.

• previous current next closest

  See DateTime::Set.

• contains

  my $bool = $r_daily->contains( $dt );

  Verify if a DateTime is a recurrence event.

• union intersection complement

  See DateTime::Set.

AUTHOR

Flavio Soibelmann Glock fglock@pucrs.br

CREDITS

The API is under development, 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.

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

DateTime::Set

DateTime::SpanSet