1Date::Manip::Recur(3) User Contributed Perl DocumentationDate::Manip::Recur(3)
2
6 Date::Manip::Recur - methods for working with recurring events
7
9 use Date::Manip::Recur;
10 $date = new Date::Manip::Recur;
11
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 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 Examples of recurring events include:
28 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 All of these can be expressed as a frequency.
35 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 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 Modifier
56 Complex recurring events may require the use of modifiers in order
57 to get them correct.
58 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 4th Thursday of every November
64 In the frequency notation (described below), this would be written
66 as:
67 1*11:4:5:0:0:0
69 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 The only way to accurately define the day after Thanksgiving is to
75 specify a frequency and a modifier:
76 4th Thursday of every November
78 +1 day
79 In frequency notation, this can be expressed as:
81 1*11:4:5:0:0:0*FD1
83 The syntax for the various modifiers is described below in the
85 "MODIFIERS" section.
86 Base date
88 Many recurrences have a base date which is a date on which a
89 recurring event is based.
90 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 For example, if the frequency is
96 every other Friday at noon
98 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 If the frequency has a modifier, such as:
104 every other Friday
106 + 1 day
107 (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 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 So, if the frequency is
120 the first of every month
122 and the base date is 'Mar 1, 2000', then the 5 recurring events
124 around it are:
125 N Date
127 -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 In some cases, the Nth date may not be defined. For example, if the
135 frequency is:
136 the 31st of every month
138 and the base date is Mar 31, 2000, the 5 recurring events around it
140 are:
141 N Date
143 -2 Jan 31 2000
145 -1 undefined
146 0 Mar 31 2000
147 1 undefined
148 2 May 31 2000
149 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 As an example, for the recurring event:
155 every other Friday
157 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 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 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 For example, if the frequency was
176 the first of every month
178 and the start/end dates were Jan 1 2000 and May 31 2000, the list
180 of dates referred to would be:
181 Jan 1 2000
183 Feb 1 2000
184 Mar 1 2000
185 Apr 1 2000
186 May 1 2000
187 If no base date is specified, but a date range is specified, the
189 start date is used as the specified base date.
190 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 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 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 This definition is described in more detail below.
205
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 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 1:2:3:4:5:6:7
218 1:2*3:4:5:6:7
219 *1:2:3:4:5:6:7
220 But the following are NOT valid because they contain more than one
222 asterisk:
223 1:2*3:4:5*6:7
225 *1:2:3:4:5:6*7
226 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 1:2*
232 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 If no asterisks are included, then the entire recurrence is an
239 interval. For example,
240 0:0:0:1:12:0:0
242 refers to an event that occurs every 1 day, 12 hours.
244 The format of the interval is very simple. It is colon separated
246 digits only. No other characters are allowed.
247 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 *12:0:0
255 then the recurring event occurs at 12:00:00 (noon).
257 For example:
259 0:0:0:2*12:30:0 every 2 days at 12:30 (each day)
261 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 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 *12-13:0,30:0
273 the event will occur at 12:00, 12:30, 13:00, and 13:30.
275 Some examples are:
277 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 There is no way to express the following with a single recurrence:
286 every day at 12:30 and 1:00
288 You have to use two recurrences to do this.
290 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 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 When specifying a range, the first value must be less than the second
305 or else nothing will be returned.
306 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 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 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 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 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 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 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 1:0:0*45:0:0:0 45th day of every year
343 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 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 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 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 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 0:0:0*x:x:x:x
367 0:0:1*x:x:x:x
368 and can be thought of as every possible occurrence of the rtime.
370 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
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 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 The specified base date is used to provide the bare minimum
393 information. For example, the recurrence:
394 0:0:3*4:0:0:0 every 3 weeks on Thursday
396 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 Likewise, the recurrence:
404 1:3*0:4:0:0:0 every 1 year, 3 months on the 4th
406 day of the month
407 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 It should also be noted that a date may actually produce multiple
412 recurring events. For example, the recurrence:
413 0:0:2*4:12,14:0:0 every 2 weeks on Thursday at 12:00
415 and 14:00
416 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 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
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 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 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 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 D(0) = Jan 31
443 D(1) = Jan 31 + 1 month = Feb 28
444 D(2) = Jan 31 + 2 month = Mar 31
445
447 The start and end dates form the range in which recurring events can
448 fall into.
449 Every recurring date will fall in the limit:
451 start <= date <= end
453 When a recurrence is created, it may include a default range, and this
455 is handled by the RecurRange config variable.
456 By default, the date range applies to the final dates once all
458 modifiers have been applied.
459 This behavior can be changed by applying the range to the unmodified
461 dates.
462 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 1*1:0:1:0:0:0*DWD
467 which means Jan 1 modified to the nearest working day.
469 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 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 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 So:
484 1*1:0:1:0:0:0*DWD**2005-01-01-00:00:00*2005-12-31-23:59:59
486 will return no dates, but:
488 1*1:0:1:0:0:0*DWD**2005-01-01-00:00:00*2005-12-31-23:59:59*1
490 will return:
492 2004-12-31-00:00:00
494
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 every Tuesday in June [1997]
501 2nd Tuesday in June [1997]
502 last Tuesday in June [1997]
503 every Tuesday of every month [in 1997]
505 2nd Tuesday of every month [in 1997]
506 last Tuesday of every month [in 1997]
507 every day of every month [in 1997]
509 2nd day of every month [in 1997]
510 last day of every month [in 1997]
511 every day [in 1997]
513 every 2nd day [in 1977]
514 every 2 days [in 1977]
515 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 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 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
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 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 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 In each of these, 'n' is 1-7 (1 being Sunday, 7 being Saturday).
545 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 PT2/NT2 are similar, but will leave the date unmodified if it is a
551 Tuesday.
552 Modifiers to move forward/backward a number of days
554 These modifiers can be used to add/subtract n days to a date.
555 FDn Means step forward n days.
557 BDn Means step backward n days.
558 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 FWn Means step forward n workdays.
564 BWn Means step backward n workdays.
565 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 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 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 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 The CWD, CWN, and CWP modifiers will always change the date to the
584 closest working day NOT counting the current date.
585 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 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 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 The IBD, NBD, IWn, and NWn modifiers eliminate dates from the list
603 immediately. In other words, if a recurrence has three modifiers:
604 FD1,IBD,FD1
606 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 Special modifiers
613 The following modifiers do things that cannot be expressed using
614 any other combination of frequency and modifiers:
615 EASTER Set the date to Easter for this year.
617
619 In order to get a list of dates referred to by the recurrence, the
620 following steps are taken.
621 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 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 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 This is repeated until all desired dates have been obtained.
637 The nth method described below has more details.
639 The range is tested
641 Any date that fall outside the range is discarded.
642 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
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 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 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 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 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 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 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 0:0*3:0
684 is equivalent to
686 0:1*3:0
688 When the year field is zero, and is right of the asterisk, it means the
690 current year.
691 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 frequency meaning
697 1:2:3:4 every 1 year, 2 months, 3 weeks,
699 4 days
700 Any, or all of the fields can be zero.
702 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 The following tables shows all possible variations of the frequency
709 where this can happen (where day 4 = Thursday).
710 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 frequency meaning
716 1:2:3*4 every 1 year, 2 months, 3 weeks
718 on Thur
719 1:0:3*4 every 1 year, 3 weeks on Thur
721 0:2:3*4 every 2 months, 3 weeks on Thur
723 0:0:3*4 every 3 weeks on Thur
725 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 frequency meaning
732 1:2*3:4 every 1 year, 2 months on the
734 3rd Thursday of the month
735 0:2*3:4 every 2 months on the 3rd Thur
737 of the month
738 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 frequency meaning
744 1*2:3:4 every 1 year in February on
746 the 3rd Thur
747 0*2:3:4 same as 1*2:3:4
749 *1:2:3:4 in Feb 0001 on the 3rd Thur
751 of the month
752 *0:2:3:4 on the 3rd Thur of Feb in the
754 current year
755 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 frequency meaning
761 1:0*3:4 every 1 year on the 3rd Thursday
763 1*0:3:4 of the year
764 *1:0:3:4 in 0001 on the 3rd Thur of
766 the year
767 0*0:3:4 same as 1*0:3:4
769 *0:0:3:4 on the 3rd Thur of the current
771 year
772 There is one special case:
774 frequency meaning
776 0:0*3:4 same as 0:1*3:4 (every month on
778 the 3rd Thur of the month)
779 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 The following table shows all possible variations of the frequency
787 where this can happen:
788 frequency meaning
790 1:2:0*4 every 1 year, 2 months on the
792 1:2*0:4 4th day of the month
793 1*2:0:4 every year on Feb 4th
795 *1:2:0:4 Feb 4th, 0001
797 0:2:0*4 every 2 months on the 4th day
799 0:2*0:4 of the month
800 0*2:0:4 same as 1*2:0:4
802 *0:2:0:4 Feb 4th of the current year
804 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 The frequency can refer to an occurrence of FirstDay in a specific
811 week (if the week is left of the asterisk):
812 frequency meaning
814 1:2:3*0 every 1 year, 2 months, 3 weeks on
816 FirstDay
817 1:0:3*0 every 1 year, 3 weeks on FirstDay
819 0:2:3*0 every 2 months, 3 weeks on FirstDay
821 0:0:3*0 every 3 weeks on FirstDay
823 or to a week in the year (if the week is right of the asterisk, and
825 the month is zero):
826 frequency meaning
828 1:0*3:0 every 1 year on the first day of the
830 1*0:3:0 3rd week of the year
831 *1:0:3:0 the first day of the 3rd week of 0001
833 or to an occurrence of FirstDay in a month (if the week is right of
835 the asterisk and month is non-zero):
836 frequency meaning
838 1:2*3:0 every 1 year, 2 months on the 3rd
840 occurrence of FirstDay
841 0:2*3:0 every 2 months on the 3rd occurrence
843 of FirstDay
844 1*2:3:0 every year on the 3rd occurrence
846 of FirstDay in Feb
847 0*2:3:0 same as 1*2:3:0
849 *1:2:3:0 the 3rd occurrence of FirstDay
851 Feb 0001
852 *0:2:3:0 the 3rd occurrence of FirstDay
854 in Feb of the current year
855 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 There are a few special cases here:
864 frequency meaning
866 0:0*3:0 same as 0:1*3:0 (every month on the 3rd
868 occurrence of the first day of week)
869 0*0:3:0 same as 1*0:3:0
871 *0:0:3:0 the first day of the 3rd week of the
873 current year
874 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 The following table shows all possible variations of the frequency
881 where this can happen:
882 frequency meaning
884 1:0:0*4 every year on the 4th day of
886 1:0*0:4 the year
887 1*0:0:4
888 *1:0:0:4 the 4th day of 0001
890 Other non-zero day variations have multiple meanings for the day
892 element:
893 frequency meaning
895 0:0:0*4 same as 0:0:1*4 (every week on Thur)
897 0:0*0:4 same as 0:1*0:4 (every month on the 4th)
899 0*0:0:4 same as 1*0:0:4
901 *0:0:0:4 the 4th day of the current year
903 All other variations
905 The remaining variations have zero values for both week and day.
906 They are:
907 frequency meaning
909 1:2:0*0 every 1 year, 2 months on the first
911 1:2*0:0 day of the month
912 1*2:0:0 every year on Feb 1
914 *1:2:0:0 Feb 1, 0001
916 1:0:0*0 every 1 year on Jan 1
918 1:0*0:0
919 1*0:0:0
920 *1:0:0:0 Jan 1, 0001
922 0:2:0*0 every 2 months on the first day of
924 0:2*0:0 the month
925 0*2:0:0 same as 1*2:0:0
927 *0:2:0:0 Feb 1 of the current year
929 0:0:0*0 same as 0:0:1*0 (every week on
931 the first day of the week)
932 0:0*0:0 same as 0:1*0:0 (every month
934 on the 1st)
935 0*0:0:0 same as 1*0:0:0
937 *0:0:0:0 Jan 1 of the current year
939
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 parse
956 $err = $recur->parse($string [,$modifiers] [,$base,$start,$end,$unmod]);
957 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 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 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 $err = $recur->parse($string);
977 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 FREQ*MODIFIERS*BASE*START*END*UNMOD
982 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 All pieces are optional, but order must be maintained, so all of
988 the following are valid:
989 FREQ*MODIFIERS
991 FREQ**BASE
992 FREQ**BASE*START*END
993 FREQ***START*END*UNMOD
994 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 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 $err = $recur->frequency($frequency);
1011 $err = $recur->start($start);
1013 $err = $recur->start($start,$unmod);
1014 $err = $recur->end($end);
1015 $err = $recur->basedate($base);
1017 $err = $recur->modifiers($modifiers);
1019 $err = $recur->modifiers(@modifiers);
1020 These set the appropriate part of the recurrence.
1022 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 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 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 NOTE: the parse method will overwrite all parts of the recurrence,
1039 so it is not appropriate to do:
1040 $recur->modifiers($modifiers);
1042 $recur->parse($string);
1043 The modifiers passed in in the first call will be overwritten.
1045 These functions can also be used to look up the values.
1047 $freq = $recur->frequency();
1049 $start = $recur->start();
1050 $end = $recur->end();
1051 @mods = $recur->modifiers();
1052 ($base,$actual) = $recur->basedate();
1054 The basedate function will return both the specified base and the
1056 actual base dates.
1057 If any of the values are not yet determined, nothing will be
1059 returned.
1060 dates
1062 @dates = $recur->dates([$start,$end,$unmod]);
1063 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 $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 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 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 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 If one or both of $start and $end are "undef", then the stored
1087 values will be used.
1088 nth
1090 ($date,$err) = $recur->nth($n);
1091 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 Invalid recurrence
1098 The recurrence has an error flag set.
1099 Incomplete recurrence
1101 The recurrence is incomplete. It needs either a
1102 base date or a date range.
1103 Range invalid
1105 The recurrence has an invalid date range (i.e.
1106 the end date occurs before the start date).
1107 Start invalid
1109 End invalid
1110 Base invalid
1111 An invalid date was entered for one of the dates.
1112 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 There are a few special circumstances to be aware of.
1121 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 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 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 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 next
1165 prev
1166 ($date,$err) = $recur->next();
1167 ($date,$err) = $recur->prev();
1168 These return the next/previous recurring event.
1170 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 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 So, for the recurrence:
1181 the 31st of every month
1183 next might return the following sequence of events:
1185 Jan 31 2000
1187 Mar 31 2000
1188 May 31 2000
1189 The rules for determining what event to return the first time one
1191 of these is called are as follows:
1192 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 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 The error codes are the same as for the nth method.
1202
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 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 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 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 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 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
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 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 1*3:2:7:2:0:0
1254 with a base date of 2006 or later cannot be satisfied.
1256
1258 Please refer to the Date::Manip::Problems documentation for information
1259 on submitting bug reports or questions to the author.
1260
1262 Date::Manip - main module documentation
1263
1265 This script is free software; you can redistribute it and/or modify it
1266 under the same terms as Perl itself.
1267
1269 Sullivan Beck (sbeck@cpan.org)
1270perl v5.32.0 2020-12-15 Date::Manip::Recur(3)