Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DateTime::Event::RecurUsereContributed Perl DocuDateTime::Event::Recurrence(3)

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
       o   yearly monthly weekly daily hourly minutely secondly

	   These methods all return a new "DateTime::Set" object representing
	   the given recurrence.

	     my	$daily_set = DateTime::Event::Recurrence->daily;

	   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:

	     my	$daily_at_10_30_set =
		 DateTime::Event::Recurrence->daily( hours => 10, minutes => 30	);

	   To represent	every Tuesday (second day of the week):

	     my	$weekly_on_tuesday_set =
		 DateTime::Event::Recurrence->weekly( days => 2	);

	   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:

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

	   You can also	provide	multiple sets of duration arguments, such as
	   this:

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

	   This	specifies a recurrence occurring every day at these 9
	   different times:

	     10:15,  10:30,  10:45,   #	+10h	     ( +15min /	+30min / last 15min (-15) )
	     14:15,  14:30,  14:45,   #	+14h	     ( +15min /	+30min / last 15min (-15) )
	     23:15,  23:30,  23:45,   #	last 1h	(-1) ( +15min /	+30min / last 15min (-15) )

	   To create a set of recurrences occurring every thirty seconds, we
	   could do this:

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

	   The following is also valid.	See the	section	on the "interval"
	   parameter:

	       my $every_30_seconds_set	=
		   DateTime::Event::Recurrence->secondly( interval => 30 );

   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 full week of every month, on tuesday
	   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 week of every year,	on tuesday
	   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 full week of every month, on monday
	   my $set = DateTime::Event::Recurrence->monthly( weeks => 2 );

	   # second tuesday of every month
	   my $set = DateTime::Event::Recurrence->monthly( weeks => 2, days => "tu", week_start_day => "1tu" );

   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" represents how the 'first week' of a period	is
       calculated:

       "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.

       The "week_start_day" defaults to	"1mo", except in yearly	("yearly()")
       recurrences which default to "mo".

   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@gmail.com

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.

perl v5.24.1			  2017-03-07	DateTime::Event::Recurrence(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | AUTHOR | CREDITS | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DateTime::Event::Recurrence&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help