1Date::Manip::Recur(3) User Contributed Perl DocumentationDate::Manip::Recur(3)
2
3
4

NAME

6       Date::Manip::Recur - methods for working with recurring events
7

SYNOPSIS

9          use Date::Manip::Recur;
10          $date = new Date::Manip::Recur;
11

DESCRIPTION

13       This module contains functions useful in parsing and manipulating
14       recurrences.  A recurrence is a notation for specifying when a
15       recurring event occurs.  For example, if an event occurs every other
16       Friday or every 4 hours, this can be defined as a recurrence. A fully
17       specified recurrence consists of the following pieces of information:
18
19       Frequency
20           The most basic piece of information is the frequency.  For
21           relatively simple recurring events, the frequency defines when
22           those events occur. For more complicated recurring events, the
23           frequency tells approximately when the events occur (but to get the
24           actual events, certain modifiers must be applied as described
25           below).
26
27           Examples of recurring events include:
28
29              the first of every month
30              every other day
31              the 4th Thursday of each month at 2:00 PM
32              every 2 hours and 30 minutes
33
34           All of these can be expressed as a frequency.
35
36           NOTE: unlike date parsing, support for frequencies written out in
37           English (or whatever language you are working in) is extremely
38           limited. For example, the string "the first of every month" will
39           NOT be parsed as a valid frequency. A limited number of frequencies
40           can be expressed in a written out form (see the <L/"OTHER FREQUENCY
41           FORMATS" section below), but most must be expressed in the format
42           described below in <L/"FREQUENCY NOTATION">. In this document
43           however, the written out form will often be used for the sake of
44           clarity.
45
46           Since a frequency typically refers to events that could happen an
47           infinite number of times, you usually have to specify a date range
48           to get the actual dates.  Some frequencies also require a base date
49           (i.e.  information about when one such even actually occurred)
50           since the frequency is otherwise ambiguous.  For example, the
51           frequency 'every other day' does not include enough information to
52           specify the dates that the event happened on, so you have to
53           explicitly define one of them.  Then all others can be derived.
54
55       Modifier
56           Complex recurring events may require the use of modifiers in order
57           to get them correct.
58
59           For example, in America, many places treat both Thanksgiving and
60           the day after as holidays. Thanksgiving is easy to define since it
61           is defined as:
62
63              4th Thursday of every November
64
65           In the frequency notation (described below), this would be written
66           as:
67
68              1*11:4:5:0:0:0
69
70           The day after Thanksgiving is NOT possible to define in the same
71           way.  Depending on the year, the day after the 4th Thursday may be
72           the 4th or 5th Friday.
73
74           The only way to accurately define the day after Thanksgiving is to
75           specify a frequency and a modifier:
76
77              4th Thursday of every November
78              +1 day
79
80           In frequency notation, this can be expressed as:
81
82              1*11:4:5:0:0:0*FD1
83
84           The syntax for the various modifiers is described below in the
85           "MODIFIERS" section.
86
87       Base date
88           Many recurrences have a base date which is a date on which a
89           recurring event is based.
90
91           The base date is not necessarily a date where the recurring event
92           occurs. Instead, it may be modified (with modifiers, or with values
93           specified in the recurrence) to actually produce a recurring event.
94
95           For example, if the frequency is
96
97              every other Friday at noon
98
99           the base date will be a Friday and the recurring event will happen
100           on that Friday, Friday two weeks later, Friday four weeks later,
101           etc.  In all cases, the dates will be modified to be at noon.
102
103           If the frequency has a modifier, such as:
104
105              every other Friday
106              + 1 day
107
108           (and yes, this trivial example could be expressed as the frequency
109           'every other Saturday' with no modifiers), then the base date is
110           still on a Friday, but the actual recurring event is determined by
111           applying modifiers and occurs on Saturday.
112
113           Recurring events are assigned a number with the event that is
114           referred to by the base date being the 0th occurrence, the first
115           one after that as the 1st occurrence, etc.  Recurring events can
116           also occur before the base date with the last time the recurring
117           event occurred before the base date is the -1th occurrence.
118
119           So, if the frequency is
120
121              the first of every month
122
123           and the base date is 'Mar 1, 2000', then the 5 recurring events
124           around it are:
125
126              N    Date
127
128              -2   Jan 1 2000
129              -1   Feb 1 2000
130               0   Mar 1 2000
131              +1   Apr 1 2000
132              +2   May 1 2000
133
134           In some cases, the Nth date may not be defined. For example, if the
135           frequency is:
136
137              the 31st of every month
138
139           and the base date is Mar 31, 2000, the 5 recurring events around it
140           are:
141
142              N   Date
143
144              -2  Jan 31 2000
145              -1  undefined
146               0  Mar 31 2000
147               1  undefined
148               2  May 31 2000
149
150           As mentioned above, the base date is used to determine one of the
151           occurrences of the recurring event... but it may not actually be on
152           of those events.
153
154           As an example, for the recurring event:
155
156              every other Friday
157
158           a base date could be on a Friday, but it would also be possible to
159           have a base date on some other day of the week, and it could
160           unambiguously refer simply to a week, and the recurring event would
161           occur on Friday of that week.
162
163           In most cases, it won't be necessary to treat base dates with that
164           level of complexity, but with complicated recurring events, it may
165           be necessary.  More information on how Date::Manip determines a
166           recurring event from a base date is given below in the section
167           "BASE DATES".
168
169       Range
170           A date range is simply a starting and an ending date. When a range
171           is used (primarily in the dates method as described below), only
172           recurring events (with all modifiers applied) which happened on or
173           after the start date and on or before the end date are used.
174
175           For example, if the frequency was
176
177              the first of every month
178
179           and the start/end dates were Jan 1 2000 and May 31 2000, the list
180           of dates referred to would be:
181
182              Jan 1 2000
183              Feb 1 2000
184              Mar 1 2000
185              Apr 1 2000
186              May 1 2000
187
188           If no base date is specified, but a date range is specified, the
189           start date is used as the specified base date.
190
191           It should be noted that if both the range and base date are
192           specified, the range is not used to determine a base date. Also,
193           the first time the recurring event occurs in this range may NOT be
194           the 0th occurrence with respect to the base date, and that is
195           allowed.
196
197           NOTE: both dates in the range and the base date must all be in the
198           same time zone, and use the same Date::Manip::Base object.
199
200           An alternate definition of the range may also be used to specify
201           that the recurring events based only on the interval and BEFORE any
202           modifiers are applied fall in the range.
203
204           This definition is described in more detail below.
205

FREQUENCY NOTATION

207       The syntax for specifying a frequency requires some explanation. It is
208       very concise, but contains the flexibility to express every single type
209       of recurring event I could think of.
210
211       The syntax of the frequency description is a colon separated list of
212       the format Y:M:W:D:H:MN:S (which stand for year, month, week, etc.).
213       One (and only one) of the colons may optionally be replaced by an
214       asterisk, or an asterisk may be prepended to the string.  For example,
215       the following are all valid frequency descriptions:
216
217         1:2:3:4:5:6:7
218         1:2*3:4:5:6:7
219        *1:2:3:4:5:6:7
220
221       But the following are NOT valid because they contain more than one
222       asterisk:
223
224         1:2*3:4:5*6:7
225        *1:2:3:4:5:6*7
226
227       When an asterisk is included, the portion to the left of it is called
228       the interval, and refers to an approximate time interval between
229       recurring events.  For example, if the interval of the frequency is:
230
231         1:2*
232
233       it means that the recurring event occurs approximately every 1 year and
234       2 months.  The interval is approximate because elements to the right of
235       the asterisk, as well as any modifiers included in the recurrence, will
236       affect when the events actually occur.
237
238       If no asterisks are included, then the entire recurrence is an
239       interval.  For example,
240
241         0:0:0:1:12:0:0
242
243       refers to an event that occurs every 1 day, 12 hours.
244
245       The format of the interval is very simple.  It is colon separated
246       digits only.  No other characters are allowed.
247
248       The portion of the frequency that occur after an asterisk is called the
249       recurrence time (or rtime), and refers to a specific value (or values)
250       for that type of time element (i.e. exactly as it would appear on a
251       calendar or a clock).  For example, if the frequency ends with the
252       rtime:
253
254         *12:0:0
255
256       then the recurring event occurs at 12:00:00 (noon).
257
258       For example:
259
260         0:0:0:2*12:30:0      every 2 days at 12:30 (each day)
261
262       Elements in the rtime can be listed as single values, ranges (2 numbers
263       separated by a dash "-"), or a comma separated list of values or
264       ranges.  In some cases, negative values are appropriate for the week or
265       day values. -1 stands for the last possible value, -2 for the second to
266       the last, etc.
267
268       If multiple values are included in more than one field in the rtime,
269       every possible combination will be used. For example, if the frequency
270       ends with the rtime:
271
272         *12-13:0,30:0
273
274       the event will occur at 12:00, 12:30, 13:00, and 13:30.
275
276       Some examples are:
277
278         0:0:0:1*2,4,6:0:0    every day at at 02:00, 04:00, and 06:00
279         0:0:0:2*12-13:0,30:0 every other day at 12:00, 12:30, 13:00,
280                              and 13:30
281         0:1:0*-1:0:0:0       the last day of every month
282         *1990-1995:12:0:1:0:0:0
283                              Dec 1 in 1990 through 1995
284
285       There is no way to express the following with a single recurrence:
286
287         every day at 12:30 and 1:00
288
289       You have to use two recurrences to do this.
290
291       You can include negative numbers in ranges. For example, including the
292       range -2--1 means to go from the 2nd to the last to the last
293       occurrence.  Negative values are only supported in the week and day
294       fields, and only in some cases.
295
296       You can even use a range like 2--2 (which means to go from the 2nd to
297       the 2nd to the last occurrence). However, this is STRONGLY discouraged
298       since this leads to a date which produces a variable number of events.
299       As a result, the only way to determine the Nth date is to calculate
300       every date starting at the base date. If you know that every date
301       produces exactly 4 recurring events, you can calculate the Nth date
302       without needing to determine every intermediate date.
303
304       When specifying a range, the first value must be less than the second
305       or else nothing will be returned.
306
307       When both the week and day elements are non-zero and the day is right
308       of the asterisk, the day refers to the day of week. The following
309       examples illustrate these type of frequencies:
310
311         0:1*4:2:0:0:0        4th Tuesday (day 2) of every month
312         0:1*-1:2:0:0:0       last Tuesday of every month
313         0:0:3*2:0:0:0        every 3rd Tuesday (every 3 weeks
314                              on 2nd day of week)
315         1:0*12:2:0:0:0       the 12th Tuesday of each year
316
317       NOTE: The day of week refers to the numeric value of each day as
318       specified by ISO 8601. In other words, day 1 is ALWAYS Monday, day 7 is
319       ALWAYS Sunday, etc., regardless of what day of the week the week is
320       defined to begin on (using the FirstDay config variable). So when the
321       day field refers to the day of week, it's value (or values if a range
322       or comma separated list are used) must be 1-7.
323
324       When the week element is zero and the month element is non-zero and the
325       day element is right of the asterisk, the day value is the day of the
326       month (it can be from 1 to 31 or -1 to -31 counting from the end of the
327       month).
328
329         3*1:0:2:12:0:0       every 3 years on Jan 2 at noon
330         0:1*0:2:12,14:0:0    2nd of every month at 12:00 and 14:00
331         0:1:0*-2:0:0:0       2nd to last day of every month
332
333       NOTE: If the day given refers to the 29th, 30th, or 31st, in a month
334       that does not have that number of days, it is ignored. For example, if
335       you ask for the 31st of every month, it will return dates in Jan, Mar,
336       May, Jul, etc.  Months with fewer than 31 days will be ignored.
337
338       If both the month and week elements are zero, and the year element is
339       non-zero, the day value is the day of the year (1 to 365 or 366 -- or
340       the negative numbers to count backwards from the end of the year).
341
342         1:0:0*45:0:0:0       45th day of every year
343
344       Specifying a day that doesn't occur in that year silently ignores that
345       year. The only result of this is that specifying +366 or -366 will
346       ignore all years except leap years.
347
348       If the week element is non-zero and to the right of the asterisk, and
349       the day element is zero, the frequency refers to the first day of the
350       given week of the month or week of the year:
351
352         0:1*2:0:0:0:0        the first day of the 2nd week of
353                              every month
354         1:0*2:0:0:0:0        the first day of the 2nd week of
355                              every year
356
357       Although the meaning of almost every recurrence can be deduced by the
358       above rules, a set of tables describing every possible combination of
359       Y/M/W/D meanings, and giving an example of each is included below in
360       the section "LIST OF Y/M/W/D FREQUENCY DEFINITIONS". It also explains a
361       small number of special cases.
362
363       NOTE: If all fields left of the asterisk are zero, the last one is
364       implied to be 1. In other words, the following are equivalent:
365
366          0:0:0*x:x:x:x
367          0:0:1*x:x:x:x
368
369       and can be thought of as every possible occurrence of the rtime.
370
371       NOTE: When applying a frequency to get a list of dates on which a
372       recurring event occurs, a delta is created from the frequency which is
373       applied to get dates referred to by the interval. These are then
374       operated on by the rtime and by modifiers to actually get the recurring
375       events.  The deltas will always be exact or approximate.  There is no
376       support for business mode recurrences. However, with the careful use of
377       modifiers (discussed below), most recurring business events can be
378       determined too.
379

BASE DATES

381       A recurrence of the form *Y:M:W:D:H:MN:S (which is technically speaking
382       not a recurring event... it is just a date or dates specified using the
383       frequency syntax) uses the first date which matches the frequency as
384       the base date. Any base date specified will be completely ignored. A
385       date range may be specified to work with a subset of the dates.
386
387       All other recurrences use a specified base date in order to determine
388       when the 0th occurrence of a recurring event happens. As mentioned
389       above, the specified base date may be determined from the start date,
390       or specified explicitly.
391
392       The specified base date is used to provide the bare minimum
393       information. For example, the recurrence:
394
395          0:0:3*4:0:0:0       every 3 weeks on Thursday
396
397       requires a base date to determine the week, but nothing else. Using the
398       standard definition (Monday-Sunday) for a week, and given that one week
399       in August 2009 is Aug 10 to Aug 16, any date in the range Aug 10 to Aug
400       16 will give the same results. The definition of the week defaults to
401       Monday-Sunday, but may be modified using the FirstDay config variable.
402
403       Likewise, the recurrence:
404
405         1:3*0:4:0:0:0        every 1 year, 3 months on the 4th
406                              day of the month
407
408       would only use the year and month of the base date, so all dates in a
409       given month would give the same set of recurring dates.
410
411       It should also be noted that a date may actually produce multiple
412       recurring events. For example, the recurrence:
413
414          0:0:2*4:12,14:0:0   every 2 weeks on Thursday at 12:00
415                              and 14:00
416
417       produces 2 events for every date. So in this case, the base date
418       produces the 0th and 1st event, the base date + an offset produces the
419       2nd and 3rd events, etc.
420
421       It must be noted that the base date refers ONLY to the interval part of
422       the recurrence. The rtime and modifiers are NOT used in determining the
423       base date.
424

INTERVAL

426       The interval of a frequency (everything left of the asterisk) will be
427       used to generate a list of dates (called interval dates). When rtime
428       values and modifiers are applied to an interval date, it produces the
429       actual recurring events.
430
431       As already noted, if the rtime values include multiple values for any
432       field, more than one event are produced by a single interval date.
433
434       It is important to understand is how the interval dates are calculated.
435       The interval is trivially turned into a delta. For example, with the
436       frequency 0:0:2*4:12:0:0, the interval is 0:0:2 which produces the
437       delta 0:0:2:0:0:0:0.
438
439       In order to get the Nth interval date, the delta is multiplied by N and
440       added to the base date. In other words:
441
442          D(0) = Jan 31
443          D(1) = Jan 31 + 1 month = Feb 28
444          D(2) = Jan 31 + 2 month = Mar 31
445

DATE RANGE

447       The start and end dates form the range in which recurring events can
448       fall into.
449
450       Every recurring date will fall in the limit:
451
452          start <= date <= end
453
454       When a recurrence is created, it may include a default range, and this
455       is handled by the RecurRange config variable.
456
457       By default, the date range applies to the final dates once all
458       modifiers have been applied.
459
460       This behavior can be changed by applying the range to the unmodified
461       dates.
462
463       An example of how this applies might be in defining New Year's Day
464       (observed).  The most useful definition of this would be:
465
466          1*1:0:1:0:0:0*DWD
467
468       which means Jan 1 modified to the nearest working day.
469
470       But if you wanted to find New Year's for 2005 using this definition by
471       passing in a start date of 2005-01-01-00:00:00 and an end date of
472       2005-12-31-23:59:59, you won't find anything because New Year's day
473       will actually be observed on 2004-12-31 (since Jan 1 is a Saturday).
474
475       To get around this, you can pass in a non-zero parameter with the
476       recurrence which means that this range will be applied to the
477       unmodified dates.
478
479       In effect, this discards the modifier (DWD), gets the dates that fall
480       in the range, and for all that fall in the range, the modifiers are
481       applied.
482
483       So:
484
485          1*1:0:1:0:0:0*DWD**2005-01-01-00:00:00*2005-12-31-23:59:59
486
487       will return no dates, but:
488
489          1*1:0:1:0:0:0*DWD**2005-01-01-00:00:00*2005-12-31-23:59:59*1
490
491       will return:
492
493          2004-12-31-00:00:00
494

OTHER FREQUENCY FORMATS

496       There are a small handful of English strings (or the equivalent in
497       other languages) which can be parsed in place of a numerical frequency.
498       These include:
499
500         every Tuesday in June [1997]
501         2nd Tuesday in June [1997]
502         last Tuesday in June [1997]
503
504         every Tuesday of every month [in 1997]
505         2nd Tuesday of every month [in 1997]
506         last Tuesday of every month [in 1997]
507
508         every day of every month [in 1997]
509         2nd day of every month [in 1997]
510         last day of every month [in 1997]
511
512         every day [in 1997]
513         every 2nd day [in 1977]
514         every 2 days [in 1977]
515
516       Each of these set the frequency. If the year is include in the string,
517       it also sets the dates in the range to be the first and last day of the
518       year.
519
520       In each of these, the numerical part (i.e. 2nd in all of the examples
521       above) can be any number from 1 to 31. To make a frequency with a
522       larger number than that, you have to use the standard format discussed
523       above.
524
525       Due to the complexity of writing out (and parsing) frequencies written
526       out, I do not intend to add additional frequency formats, and the use
527       of these is discouraged. The frequency format described above is
528       preferred.
529

MODIFIERS

531       Any number of modifiers may be added to a frequency to get the actual
532       date of a recurring event.  Modifiers are case sensitive.
533
534       Modifiers to set the day-of-week
535           The following modifiers can be used to adjust a date to a specific
536           day of the week.
537
538             PDn   Means the previous day n not counting today
539             PTn   Means the previous day n counting today
540             NDn   Means the next day n not counting today
541             NTn   Means the next day n counting today
542             WDn   Day n (1-7) of the current week
543
544           In each of these, 'n' is 1-7 (1 being Sunday, 7 being Saturday).
545
546           For example, PD2/ND2 returns the previous/next Tuesday. If the date
547           that this is applied to is Tuesday, it modifies it to one week in
548           the past/future.
549
550           PT2/NT2 are similar, but will leave the date unmodified if it is a
551           Tuesday.
552
553       Modifiers to move forward/backward a number of days
554           These modifiers can be used to add/subtract n days to a date.
555
556             FDn   Means step forward n days.
557             BDn   Means step backward n days.
558
559       Modifiers to force events to be on business days
560           Modifiers can also be used to force recurring events to occur on
561           business days. These modifiers include:
562
563             FWn   Means step forward n workdays.
564             BWn   Means step backward n workdays.
565
566             CWD   The closest work day (using the TomorrowFirst
567                   config variable).
568             CWN   The closest work day (looking forward first).
569             CWP   The closest work day (looking backward first).
570
571             NWD   The next work day counting today
572             PWD   The previous work day counting today
573             DWD   The closest work day (using the TomorrowFirst config
574                   variable) counting today
575
576             IBD   This discards the date if it is not a business day.
577             NBD   This discards the date if it IS a business day.
578
579             IWn   This discards the date if it is not the n'th day
580                   of the week (n=1-7, 1 is Monday)
581             NWn   This discards the date if it IS the n'th day of the week
582
583           The CWD, CWN, and CWP modifiers will always change the date to the
584           closest working day NOT counting the current date.
585
586           The NWD, PWD, and DWD modifiers always change the date to the
587           closest working day unless the current date is a work day. In that
588           case, it is left unmodified.
589
590           CWD, CWN, and CWP will usually return the same value, but if you
591           are starting at the middle day of a 3-day weekend (for example), it
592           will return either the first work day of the following week, or the
593           last work day of the previous week depending on whether it looks
594           forward or backward first.
595
596           All business day modifiers ignore the time, so if a date is
597           initially calculated at Saturday at noon, and the FW1 is applied,
598           the date is initially moved to the following Monday (assuming it is
599           a work day) and the FW1 moves it to Tuesday. The final result will
600           be Tuesday at noon.
601
602           The IBD, NBD, IWn, and NWn modifiers eliminate dates from the list
603           immediately.  In other words, if a recurrence has three modifiers:
604
605             FD1,IBD,FD1
606
607           then as a date is being tested, first the FD1 modifier is applied.
608           Then, it is tested to see if it is a business day.  If it is, the
609           second FD1 modifier will be applied.  Otherwise, the date will not
610           be included in the list of recurring events.
611
612       Special modifiers
613           The following modifiers do things that cannot be expressed using
614           any other combination of frequency and modifiers:
615
616             EASTER   Set the date to Easter for this year.
617

DETERMINING DATES

619       In order to get a list of dates referred to by the recurrence, the
620       following steps are taken.
621
622       The recurrence is tested for errors
623           The recurrence must be completely specified with a base date
624           (either supplied explicitly, or derived from a start date) and date
625           range when necessary. All dates must be valid.
626
627       The actual base date is determined
628           Using information from the interval and the specified base date,
629           the actual base date is determined.
630
631       The Nth date is calculated
632           By applying the delta that corresponds to the interval, and then
633           applying rtime and modifier information, the Nth date is
634           determined.
635
636           This is repeated until all desired dates have been obtained.
637
638           The nth method described below has more details.
639
640       The range is tested
641           Any date that fall outside the range is discarded.
642
643           NOTE: when the recurrence contains no interval, it is not necessary
644           to specify the range, and if it is not specified, all of the dates
645           are used. The range MAY be specified to return only a subset of the
646           dates if desired.
647

LIST OF Y/M/W/D FREQUENCY DEFINITIONS

649       Because the week and day values may have multiple meanings depending on
650       where the asterisk is, and which of the fields have non-zero values, a
651       list of every possible combination is included here (though most can be
652       determined using the rules above).
653
654       When the asterisk occurs before the day element, and the day element is
655       non-zero, the day element can take on multiple meanings depending on
656       where the asterisk occurs, and which leading elements (year, month,
657       week) have non-zero values. It can refer to the day of the week, day of
658       the month, or day of the year.
659
660       When the asterisk occurs before the week element, the week element of
661       the frequency can also take on multiple meanings as well. When the
662       month field and day fields are zero, it refers to the week of the year.
663       Since the week of the year is well defined in the ISO 8601 spec, there
664       is no ambiguity.
665
666       When the month field is zero, but the day field is not, the week field
667       refers to the nth occurrence of the day of week referred to by the day
668       field in the year.
669
670       When the month field is non-zero, the week field refers to the nth
671       occurrence of the day of week in the month.
672
673       In the tables below only the first 4 elements of the frequency are
674       shown. The actual frequency will include the hour, minute, and second
675       elements in addition to the ones shown.
676
677       When all elements left of the asterisk are 0, the interval is such that
678       it occurs the maximum times possible (without changing the type of
679       elements to the right of the asterisk). Another way of looking at it is
680       that the last 0 element of the interval is changed to 1. So, the
681       interval:
682
683         0:0*3:0
684
685       is equivalent to
686
687         0:1*3:0
688
689       When the year field is zero, and is right of the asterisk, it means the
690       current year.
691
692       All elements left of the asterisk
693           When all of the month, week, and day elements are left of the
694           asterisk, the simple definitions of the frequency are used:
695
696             frequency     meaning
697
698             1:2:3:4       every 1 year, 2 months, 3 weeks,
699                           4 days
700
701           Any, or all of the fields can be zero.
702
703       Non-zero day, non-zero week
704           When both the day and week elements are non-zero, the day element
705           always refers to the day of week. Values must be in the range (1 to
706           7) and no negative values are allowed.
707
708           The following tables shows all possible variations of the frequency
709           where this can happen (where day 4 = Thursday).
710
711           When the week is left of the asterisk, the interval is used to get
712           the weeks on the calendar containing a recurring date, and the day
713           is used to set the day of the week.  The following are possible:
714
715             frequency     meaning
716
717             1:2:3*4       every 1 year, 2 months, 3 weeks
718                           on Thur
719
720             1:0:3*4       every 1 year, 3 weeks on Thur
721
722             0:2:3*4       every 2 months, 3 weeks on Thur
723
724             0:0:3*4       every 3 weeks on Thur
725
726           When the week is right of the asterisk, and a non-zero month is
727           left of the asterisk, the recurrence refers to a specific
728           occurrence of a day-of-week during a month. The following are
729           possible:
730
731             frequency     meaning
732
733             1:2*3:4       every 1 year, 2 months on the
734                           3rd Thursday of the month
735
736             0:2*3:4       every 2 months on the 3rd Thur
737                           of the month
738
739           When the week and month are both non-zero and right of the
740           asterisk, the recurrence refers to an occurrence of day-of-week
741           during the given month.  Possibilities are:
742
743             frequency     meaning
744
745             1*2:3:4       every 1 year in February on
746                           the 3rd Thur
747
748             0*2:3:4       same as 1*2:3:4
749
750            *1:2:3:4       in Feb 0001 on the 3rd Thur
751                           of the month
752
753            *0:2:3:4       on the 3rd Thur of Feb in the
754                           current year
755
756           When the week is right of the asterisk, and the month is zero, the
757           recurrence refers to an occurrence of the day-of-week during the
758           year. The following are possible:
759
760             frequency     meaning
761
762             1:0*3:4       every 1 year on the 3rd Thursday
763             1*0:3:4       of the year
764
765            *1:0:3:4       in 0001 on the 3rd Thur of
766                           the year
767
768             0*0:3:4       same as 1*0:3:4
769
770            *0:0:3:4       on the 3rd Thur of the current
771                           year
772
773           There is one special case:
774
775             frequency     meaning
776
777             0:0*3:4       same as 0:1*3:4 (every month on
778                           the 3rd Thur of the month)
779
780       Non-zero day, non-zero month
781           When a non-zero day element occurs to the right of the asterisk and
782           the week element is zero, but the month element is non-zero, the
783           day elements always refers to a the day of month in the range (1 to
784           31) or (-1 to -31).
785
786           The following table shows all possible variations of the frequency
787           where this can happen:
788
789             frequency     meaning
790
791             1:2:0*4       every 1 year, 2 months on the
792             1:2*0:4       4th day of the month
793
794             1*2:0:4       every year on Feb 4th
795
796            *1:2:0:4       Feb 4th, 0001
797
798             0:2:0*4       every 2 months on the 4th day
799             0:2*0:4       of the month
800
801             0*2:0:4       same as 1*2:0:4
802
803            *0:2:0:4       Feb 4th of the current year
804
805       Zero day, non-zero week
806           When a day is zero, and the week is non-zero, the recurrence refers
807           to a specific occurrence of the first day of the week (as given by
808           the FirstDay variable).
809
810           The frequency can refer to an occurrence of FirstDay in a specific
811           week (if the week is left of the asterisk):
812
813             frequency     meaning
814
815             1:2:3*0       every 1 year, 2 months, 3 weeks on
816                           FirstDay
817
818             1:0:3*0       every 1 year, 3 weeks on FirstDay
819
820             0:2:3*0       every 2 months, 3 weeks on FirstDay
821
822             0:0:3*0       every 3 weeks on FirstDay
823
824           or to a week in the year (if the week is right of the asterisk, and
825           the month is zero):
826
827             frequency     meaning
828
829             1:0*3:0       every 1 year on the first day of the
830             1*0:3:0       3rd week of the year
831
832            *1:0:3:0       the first day of the 3rd week of 0001
833
834           or to an occurrence of FirstDay in a month (if the week is right of
835           the asterisk and month is non-zero):
836
837             frequency     meaning
838
839             1:2*3:0       every 1 year, 2 months on the 3rd
840                           occurrence of FirstDay
841
842             0:2*3:0       every 2 months on the 3rd occurrence
843                           of FirstDay
844
845             1*2:3:0       every year on the 3rd occurrence
846                           of FirstDay in Feb
847
848             0*2:3:0       same as 1*2:3:0
849
850            *1:2:3:0       the 3rd occurrence of FirstDay
851                           Feb 0001
852
853            *0:2:3:0       the 3rd occurrence of FirstDay
854                           in Feb of the current year
855
856           NOTE: in the last group, a slightly more intuitive definition of
857           these would have been to say that the week field refers to the week
858           of the month, but given the ISO 8601 manner of defining when weeks
859           start, this definition would have virtually no practical
860           application. So the definition of the week field referring to the
861           Nth occurrence of FirstDay in a month was used instead.
862
863           There are a few special cases here:
864
865             frequency     meaning
866
867             0:0*3:0       same as 0:1*3:0   (every month on the 3rd
868                           occurrence of the first day of week)
869
870             0*0:3:0       same as 1*0:3:0
871
872            *0:0:3:0       the first day of the 3rd week of the
873                           current year
874
875       Non-zero day
876           When a non-zero day element occurs and both the month and week
877           elements are zero, the day elements always refers to a the day of
878           year (1 to 366 or -1 to -366 to count from the end).
879
880           The following table shows all possible variations of the frequency
881           where this can happen:
882
883             frequency     meaning
884
885             1:0:0*4       every year on the 4th day of
886             1:0*0:4       the year
887             1*0:0:4
888
889            *1:0:0:4       the 4th day of 0001
890
891           Other non-zero day variations have multiple meanings for the day
892           element:
893
894             frequency     meaning
895
896             0:0:0*4       same as 0:0:1*4  (every week on Thur)
897
898             0:0*0:4       same as 0:1*0:4  (every month on the 4th)
899
900             0*0:0:4       same as 1*0:0:4
901
902            *0:0:0:4       the 4th day of the current year
903
904       All other variations
905           The remaining variations have zero values for both week and day.
906           They are:
907
908             frequency     meaning
909
910             1:2:0*0       every 1 year, 2 months on the first
911             1:2*0:0       day of the month
912
913             1*2:0:0       every year on Feb 1
914
915            *1:2:0:0       Feb 1, 0001
916
917             1:0:0*0       every 1 year on Jan 1
918             1:0*0:0
919             1*0:0:0
920
921            *1:0:0:0       Jan 1, 0001
922
923             0:2:0*0       every 2 months on the first day of
924             0:2*0:0       the month
925
926             0*2:0:0       same as 1*2:0:0
927
928            *0:2:0:0       Feb 1 of the current year
929
930             0:0:0*0       same as 0:0:1*0 (every week on
931                           the first day of the week)
932
933             0:0*0:0       same as 0:1*0:0 (every month
934                           on the 1st)
935
936             0*0:0:0       same as 1*0:0:0
937
938            *0:0:0:0       Jan 1 of the current year
939

METHODS

941       new
942       new_config
943       new_date
944       new_delta
945       new_recur
946       base
947       tz
948       is_date
949       is_delta
950       is_recur
951       config
952       err Please refer to the Date::Manip::Obj documentation for these
953           methods.
954
955       parse
956              $err = $recur->parse($string [,$modifiers] [,$base,$start,$end,$unmod]);
957
958           This creates a new recurrence. A string containing a valid
959           frequency is required. In addition, $start, $end, and $base dates
960           can be passed in (either as Date::Manip::Date objects, or as
961           strings containing dates that can be parsed), and any number of the
962           modifiers listed above.
963
964           If the $start or $end dates are not included, they may be supplied
965           automatically, based on the value of the RecurRange variable. If
966           any of the dates are passed in, they must be included in the order
967           given (though it is safe to pass an empty string or undef in for
968           any of them if you only want to set some, but not all of them).  If
969           $unmod is true, the range will apply to unmodified dates rather
970           than the modified dates.
971
972           The $modifiers argument must contain valid modifiers, or be left
973           out of the argument list entirely. You cannot pass an empty string
974           or undef in for it.
975
976              $err = $recur->parse($string);
977
978           This creates a recurrence from a string which contains all of the
979           necessary elements of the recurrence. The string is of the format:
980
981              FREQ*MODIFIERS*BASE*START*END*UNMOD
982
983           where FREQ is a string containing a frequency, MODIFIERS is a
984           string containing a comma separated list of modifiers, BASE, START,
985           and END are strings containing parseable dates.
986
987           All pieces are optional, but order must be maintained, so all of
988           the following are valid:
989
990              FREQ*MODIFIERS
991              FREQ**BASE
992              FREQ**BASE*START*END
993              FREQ***START*END*UNMOD
994
995           If a part of the recurrence is passed in both as part of $string
996           and as an argument, the argument overrides the string portion, with
997           the possible exception of modifiers. The modifiers in the argument
998           override the string version unless the first one is a '+' in which
999           case they are appended. See the modifiers method below for more
1000           information.
1001
1002       frequency
1003       start
1004       end
1005       basedate
1006       modifiers
1007           You can also create a recurrency in steps (or replace parts of an
1008           existing recurrence) using the following:
1009
1010              $err = $recur->frequency($frequency);
1011
1012              $err = $recur->start($start);
1013              $err = $recur->start($start,$unmod);
1014              $err = $recur->end($end);
1015
1016              $err = $recur->basedate($base);
1017
1018              $err = $recur->modifiers($modifiers);
1019              $err = $recur->modifiers(@modifiers);
1020
1021           These set the appropriate part of the recurrence.
1022
1023           Calling the frequency method discards all information currently
1024           stored in the Recur object (including an existing start, end, and
1025           base date), so this method should be called first.
1026
1027           In the modifiers method, the modifiers can be passed in as a string
1028           containing a comma separated list of modifiers, or as a list of
1029           modifiers. The modifiers passed in override all previously set
1030           modifiers UNLESS the first one is the string "+", in which case the
1031           new modifiers are appended to the list.
1032
1033           In the start, end, and base methods, the date passed in can be a
1034           Date::Manip::Date object, or a string that can be parsed to get a
1035           date.  If $unmod is true, it will mean that the range will apply to
1036           unmodified dates.
1037
1038           NOTE: the parse method will overwrite all parts of the recurrence,
1039           so it is not appropriate to do:
1040
1041              $recur->modifiers($modifiers);
1042              $recur->parse($string);
1043
1044           The modifiers passed in in the first call will be overwritten.
1045
1046           These functions can also be used to look up the values.
1047
1048              $freq  = $recur->frequency();
1049              $start = $recur->start();
1050              $end   = $recur->end();
1051              @mods  = $recur->modifiers();
1052
1053              ($base,$actual) = $recur->basedate();
1054
1055           The basedate function will return both the specified base and the
1056           actual base dates.
1057
1058           If any of the values are not yet determined, nothing will be
1059           returned.
1060
1061       dates
1062              @dates = $recur->dates([$start,$end,$unmod]);
1063
1064           Returns the list of dates defined by the full recurrence. If there
1065           is an error, or if there are no dates, an empty list will be
1066           returned.
1067
1068           $start and $end are either "undef," or dates which can be used to
1069           limit the set of dates passed back (they can be Date::Manip::Date
1070           objects or strings that can be parsed).
1071
1072           If the recurrence does not have a start and end date already,
1073           passing in $start and $end will set the range (but they will NOT be
1074           stored in the recurrence).
1075
1076           If the recurrence does have a start and end date stored in it, the
1077           $start and $end arguments can be used to temporarily override the
1078           limits. For example, if a recurrence has a start date of Jan 1,
1079           2006 00:00:00 and and end date of Dec 31, 2006 23:59:59 stored in
1080           the recurrence, passing in $start of Jul 1, 2006 00:00:00 will
1081           limit the dates returned to the range of Jul 1 to Dec 31.
1082
1083           Passing in a start date of Jul 1, 2007 will mean that no dates are
1084           returned since the recurrence limits the date to be in 2006.
1085
1086           If one or both of $start and $end are "undef", then the stored
1087           values will be used.
1088
1089       nth
1090              ($date,$err) = $recur->nth($n);
1091
1092           This returns the $nth recurring event ($n may be any integer). If
1093           an error occurs, it is returned (but it is not set in $recur since
1094           it may be properly, though perhaps incompletely, defined). The
1095           following errors may be returned:
1096
1097              Invalid recurrence
1098                 The recurrence has an error flag set.
1099
1100              Incomplete recurrence
1101                 The recurrence is incomplete. It needs either a
1102                 base date or a date range.
1103
1104              Range invalid
1105                 The recurrence has an invalid date range (i.e.
1106                 the end date occurs before the start date).
1107
1108              Start invalid
1109              End invalid
1110              Base invalid
1111                 An invalid date was entered for one of the dates.
1112
1113              Not found
1114                 In some cases, a recurrence may appear valid, but
1115                 does not refer to any actual occurrences.  If no
1116                 dates are found within a certain number of attempts
1117                 (given by the MaxRecurAttempts config variable), this
1118                 error is returned.
1119
1120           There are a few special circumstances to be aware of.
1121
1122           1) If the recurrence contains no interval (i.e. is of the form
1123           *Y:M:W:D:H:MN:S), the dates come directly from the rtime values.
1124           In this case, the 0th event is the first date in the list of dates
1125           specified by the rtime. As such, $n must be a positive integer.  If
1126           $n is negative, or outside the range of dates specified, the
1127           returned date will be "undef" (but this is not an error).
1128
1129           2) A very small number of recurrences have an unknown number of
1130           recurring events associated with each date.  This only happens if
1131           one of the values in the rtime is specified as a range including
1132           both a positive and negative index.  For example, if the day field
1133           in an rtime refers to the day of month, and is 15--15 (i.e. the
1134           15th day to the 15th to the last day), this may include 3 events
1135           (on a month with 31 days), 2 event (months with 30 days), 1 event
1136           (months with 29 days), or 0 events (months with 28 days). As such,
1137           in order to calculate the Nth date, you have to start with the 0th
1138           (i.e. base) date and calculate every event until you get the Nth
1139           one. For this reason, it is highly recommended that this type of
1140           frequency be avoided as it will be quite slow.
1141
1142           3) Most recurrences have a known number of events (equal to the
1143           number of combinations of values in the rtime) for each date. For
1144           these, calculating the Nth date is much faster. However, in this
1145           case, some of them may refer to an invalid date. For example, if
1146           the frequency is 'the 31st of every month' and the base (0th) date
1147           is Jan 31, the 1st event would refer to Feb 31. Since that isn't
1148           valid, "undef" would be returned for "$n=1." Obviously, it would be
1149           possible to actually determine the Nth valid event by calculating
1150           all N-1 dates, but in the interest of performance, this is not
1151           done.
1152
1153           4) The way the Nth recurring event is calculated differs slightly
1154           for NE>0 and N<0 if the delta referred to by the frequency is
1155           approximate. To calculate the Nth recurring event (where N>0), you
1156           take the base date and add N*DELTA (where DELTA is the delta
1157           determined by the frequency).  To get the Nth recurring event
1158           (where N<0), a date is determine which, if N*DELTA were added to
1159           it, would produce the base date. For more details, refer to the
1160           Date::Manip::Calc document.  In the "SUBTRACTION" in
1161           Date::Manip::Calc section in the discussion of approximate date-
1162           delta calculations, calculations are done with $subtract = 2.
1163
1164       next
1165       prev
1166              ($date,$err) = $recur->next();
1167              ($date,$err) = $recur->prev();
1168
1169           These return the next/previous recurring event.
1170
1171           The first time next/prev is called, one of the recurring events
1172           will be selected and returned (using the rules discussed below).
1173           Subsequent calls to next/prev will return the next or previous
1174           event.
1175
1176           Unlike the nth method which will return a specific event (or undef
1177           if the Nth even is not defined), the next and prev methods will
1178           only work with defined events.
1179
1180           So, for the recurrence:
1181
1182              the 31st of every month
1183
1184           next might return the following sequence of events:
1185
1186              Jan 31 2000
1187              Mar 31 2000
1188              May 31 2000
1189
1190           The rules for determining what event to return the first time one
1191           of these is called are as follows:
1192
1193           1) If there is a range, next will return the first event that
1194           occurs after the start of the range.  prev will return the last
1195           event that occurs before the end of the range.
1196
1197           2) If there is no range, next will return the first event on or
1198           after the base date.  prev will return the last event before the
1199           base date.
1200
1201           The error codes are the same as for the nth method.
1202

HISTORY OF THE FREQUENCY NOTATION

1204       I realize that the frequency notation described above looks quite
1205       complicated at first glance, but it is (IMO) the best notation for
1206       expressing recurring events in existence. I actually consider it the
1207       single most important contribution to date/time handling in
1208       Date::Manip.
1209
1210       When I first decided to add recurring events to Date::Manip, I first
1211       came up with a list of common ways of specifying recurring events, and
1212       then went looking for a notation that could be used to define them.  I
1213       was hoping for a notation that would be similar to cron notation, but
1214       more powerful.
1215
1216       After looking in several specifications (including ISO 8601) and after
1217       a discussion on a mailing list of calendar related topics, it appeared
1218       that there was no concise, flexible notation for handling recurring
1219       events that would handle all of the common forms I'd come up with.
1220
1221       So, as a matter of necessity, I set about inventing my own notation.
1222       As I was looking at my list, it struck me that all of the parts which
1223       specified a frequency were higher level (i.e. referred to a larger unit
1224       of time) than those parts which specified a specific value (what I've
1225       called the rtime). In other words, when the terms were laid out from
1226       year down to seconds, the frequency part was always left of specific
1227       values.
1228
1229       That led immediately to the notation described above, so I started
1230       analyzing it to figure out if it could express all of the recurring
1231       events I'd come up with. It succeeded on 100% of them. Not only that,
1232       but by playing with different values (especially different combinations
1233       of m/w/d values), I found that it would define recurring events that I
1234       hadn't even thought of, but which seemed perfectly reasonable in
1235       hindsight.
1236
1237       After a very short period, I realized just how powerful this notation
1238       was, and set about implementing it, and as I said above, of all the
1239       contributions that Date::Manip has made, I consider this to be the most
1240       important.
1241

KNOWN BUGS

1243       If you specify a recurrence which cannot be satisfied for the base
1244       date, or for any time after the base date, the recurrence will crash.
1245       This can only happen if you specify a recurrence that always occurs in
1246       the spring DST transition using the current timezone rules.
1247
1248       For example, in a US timezone, the current timezone rules state that a
1249       DST transition occurs at 02:00:00 on the 2nd Sunday in March and the
1250       clock jumps to 03:00.  This started in 2006.  As a result, the
1251       recurrence
1252
1253          1*3:2:7:2:0:0
1254
1255       with a base date of 2006 or later cannot be satisfied.
1256

BUGS AND QUESTIONS

1258       Please refer to the Date::Manip::Problems documentation for information
1259       on submitting bug reports or questions to the author.
1260

SEE ALSO

1262       Date::Manip        - main module documentation
1263

LICENSE

1265       This script is free software; you can redistribute it and/or modify it
1266       under the same terms as Perl itself.
1267

AUTHOR

1269       Sullivan Beck (sbeck@cpan.org)
1270
1271
1272
1273perl v5.36.0                      2022-12-10             Date::Manip::Recur(3)
Impressum