.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "DateTime::Event::Recurrence 3pm"
.TH DateTime::Event::Recurrence 3pm "2017-08-03" "perl v5.26.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DateTime::Event::Recurrence \- DateTime::Set extension for create basic recurrence sets
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& 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 \*(Aq \*(Aq, $dt\->datetime;
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides convenience methods that let you easily create
\&\f(CW\*(C`DateTime::Set\*(C'\fR objects for various recurrences, such as \*(L"once a
month\*(R" or \*(L"every day\*(R".  You can also create more complicated
recurrences, such as \*(L"every Monday, Wednesday and Thursday at 10:00 \s-1AM\s0
and 2:00 \s-1PM\*(R".\s0
.SH "USAGE"
.IX Header "USAGE"
.IP "\(bu" 4
yearly monthly weekly daily hourly minutely secondly
.Sp
These methods all return a new \f(CW\*(C`DateTime::Set\*(C'\fR object representing
the given recurrence.
.Sp
.Vb 1
\&  my $daily_set = DateTime::Event::Recurrence\->daily;
.Ve
.Sp
If no parameters are given, then the set members each occur at the
\&\fIbeginning\fR of the specified recurrence.
.Sp
For example, by default, the \f(CW\*(C`monthly()\*(C'\fR method returns a set
containing the first day of each month.
.Sp
Without parameters, the \f(CW\*(C`weekly()\*(C'\fR method returns a set containing
\&\fIMondays\fR.
.Sp
However, you can pass in parameters to alter where these datetimes
fall.  The parameters are the same as those given to the
\&\f(CW\*(C`DateTime::Duration\*(C'\fR 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:
.Sp
.Vb 2
\&  my $daily_at_10_30_set =
\&      DateTime::Event::Recurrence\->daily( hours => 10, minutes => 30 );
.Ve
.Sp
To represent every \fITuesday\fR (second day of the week):
.Sp
.Vb 2
\&  my $weekly_on_tuesday_set =
\&      DateTime::Event::Recurrence\->weekly( days => 2 );
.Ve
.Sp
A negative duration counts backwards from the end of the period.  This
is done in the same manner as is specified in \s-1RFC 2445\s0 (iCal).
.Sp
Negative durations are useful for creating recurrences such as the 
\&\fIlast day of each month\fR:
.Sp
.Vb 2
\&  my $last_day_of_month_set =
\&      DateTime::Event::Recurrence\->monthly( days => \-1 );
.Ve
.Sp
You can also provide multiple sets of duration arguments, such as
this:
.Sp
.Vb 4
\&    my $set = DateTime::Event::Recurrence\->daily
\&                  ( hours =>   [ 10, 14,  \-1 ],
\&                    minutes => [ 15, 30, \-15 ],
\&                  );
.Ve
.Sp
This specifies a recurrence occurring every day at these 9 different
times:
.Sp
.Vb 3
\&  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) )
.Ve
.Sp
To create a set of recurrences occurring every thirty seconds, we could do this:
.Sp
.Vb 2
\&    my $every_30_seconds_set =
\&        DateTime::Event::Recurrence\->minutely( seconds => [ 0, 30 ] );
.Ve
.Sp
The following is also valid. See the section on the \*(L"interval\*(R" parameter:
.Sp
.Vb 2
\&    my $every_30_seconds_set =
\&        DateTime::Event::Recurrence\->secondly( interval => 30 );
.Ve
.SS "Invalid DateTimes"
.IX Subsection "Invalid DateTimes"
Invalid values are skipped at run time.
.PP
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.
.PP
Another example of this would be creating a set via the
\&\f(CW\*(C`daily()\*(C'\fR method and specifying \f(CW\*(C`hours => 25\*(C'\fR.
.ie n .SS "The ""days"" Parameter"
.el .SS "The ``days'' Parameter"
.IX Subsection "The days Parameter"
The \*(L"days\*(R" parameter can be combined with yearly, monthly, and weekly
recurrences, resulting in six possible meanings:
.PP
.Vb 2
\&    # 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 );
.Ve
.PP
Week days can also be called by name, as is specified in \s-1RFC 2445\s0 (iCal):
.PP
.Vb 2
\&  my $weekly_on_tuesday_set =
\&      DateTime::Event::Recurrence\->weekly( days => \*(Aqtu\*(Aq );
.Ve
.PP
The \*(L"days\*(R" parameter defaults to \*(L"the first day\*(R".
See also the section on the \*(L"week_start_day\*(R" parameter.
.PP
.Vb 2
\&    # 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" );
.Ve
.ie n .SS "The ""interval"" and ""start"" Parameters"
.el .SS "The ``interval'' and ``start'' Parameters"
.IX Subsection "The interval and start Parameters"
The \*(L"interval\*(R" parameter represents how often the recurrence rule repeats.
.PP
The optional \*(L"start\*(R" parameter specifies where to start counting:
.PP
.Vb 1
\&    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,
\&                  );
.Ve
.PP
This specifies a recurrence that happens at 10:30 on the day specified
by \f(CW\*(C`start => $dt\*(C'\fR, and then every 11 days \fIbefore and after\fR
\&\f(CW$dt\fR.  So we get a set like this:
.PP
.Vb 5
\&    ...
\&    2003\-06\-04T10:30:00,
\&    2003\-06\-15T10:30:00,
\&    2003\-06\-26T10:30:00,
\&    ...
.Ve
.PP
In this case, the method is used to specify the unit, so \f(CW\*(C`daily()\*(C'\fR
means that our unit is a day, and \f(CW\*(C`interval => 11\*(C'\fR specifies the
quantity of our unit.
.PP
The \*(L"start\*(R" parameter should have no time zone.
.ie n .SS "The ""week_start_day"" Parameter"
.el .SS "The ``week_start_day'' Parameter"
.IX Subsection "The week_start_day Parameter"
The \f(CW\*(C`week_start_day\*(C'\fR represents how the 'first week' of a period is
calculated:
.PP
\&\*(L"mo\*(R", \*(L"tu\*(R", \*(L"we\*(R", \*(L"th\*(R", \*(L"fr\*(R", \*(L"sa\*(R", \*(L"su\*(R" \- The first week is one that starts
on this week-day, and has \fIthe most days\fR in this period.  Works for
\&\f(CW\*(C`weekly\*(C'\fR and \f(CW\*(C`yearly\*(C'\fR recurrences.
.PP
\&\*(L"1mo\*(R", \*(L"1tu\*(R", \*(L"1we\*(R", \*(L"1th\*(R", \*(L"1fr\*(R", \*(L"1sa\*(R", \*(L"1su\*(R" \- The first week is one that
starts on this week-day, and has \fIall days\fR in this period.  This
works for \f(CW\*(C`weekly()\*(C'\fR, \f(CW\*(C`monthly()\*(C'\fR and \f(CW\*(C`yearly()\*(C'\fR recurrences.
.PP
The \f(CW\*(C`week_start_day\*(C'\fR defaults to \*(L"1mo\*(R",
except in yearly (\f(CW\*(C`yearly()\*(C'\fR) recurrences which default to \*(L"mo\*(R".
.SS "Time Zones"
.IX Subsection "Time Zones"
Recurrences are created in the 'floating' time zone, as specified in
the \f(CW\*(C`DateTime\*(C'\fR module.
.PP
If you want to specify a time zone for a recurrence, you can do this
by calling \f(CW\*(C`set_time_zone()\*(C'\fR on the returned set:
.PP
.Vb 2
\&  my $daily = DateTime::Event::Recurrence\->daily;
\&  $daily\->set_time_zone( \*(AqEurope/Berlin\*(Aq );
.Ve
.PP
You can also pass a \f(CW\*(C`DateTime.pm\*(C'\fR object with a time zone to
the set's \f(CW\*(C`next()\*(C'\fR and \f(CW\*(C`previous()\*(C'\fR methods:
.PP
.Vb 2
\&  my $dt = DateTime\->today( time_zone => \*(AqEurope/Berlin\*(Aq );
\&  my $next = $daily\->next($dt);
.Ve
.PP
A recurrence can be affected \s-1DST\s0 changes, so it would be possible to
specify a recurrence that creates nonexistent datetimes.  Because
\&\f(CW\*(C`DateTime.pm\*(C'\fR throws an exception if asked to create a non-existent
datetime, please be careful when setting a time zone for your
recurrence.
.PP
It might be preferable to always use \*(L"\s-1UTC\*(R"\s0 for your sets, and then
convert the returned object to the desired time zone.
.SS "Leap Seconds"
.IX Subsection "Leap Seconds"
There are no leap seconds, because the recurrences are created in the 
\&'floating' time zone.
.PP
The value \f(CW60\fR for seconds (the leap second) is ignored.  If you
\&\fIreally\fR want the leap second, then specify the second as \f(CW\*(C`\-1\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Flavio Soibelmann Glock
fglock@gmail.com
.SH "CREDITS"
.IX Header "CREDITS"
The \s-1API\s0 was developed with help from the people in the
datetime@perl.org list.
.PP
Special thanks to Dave Rolsky, 
Ron Hill and Matt Sisk for being around with ideas.
.PP
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.
.PP
Jerrad Pierce came with the idea to move \*(L"interval\*(R" from
DateTime::Event::ICal to here.
.SH "COPYRIGHT"
.IX Header "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.
.PP
The full text of the license can be found in the \s-1LICENSE\s0 file included
with this module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
datetime@perl.org mailing list
.PP
DateTime Web page at http://datetime.perl.org/
.PP
DateTime \- date and time :)
.PP
DateTime::Set \- for recurrence-set accessors docs.
You can use DateTime::Set to specify recurrences using callback subroutines.
.PP
DateTime::Event::ICal \- if you need more complex recurrences.
.PP
DateTime::SpanSet \- sets of intervals, including recurring sets of intervals.