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, the modifiers must be applied as described below).
25 Examples include:
27 the first of every month
29 every other day
30 the 4th Thursday of each month at 2:00 PM
31 every 2 hours and 30 minutes
32 All of these can be expressed as a frequency.
34 NOTE: unlike date parsing, support for frequencies written out in
36 English (or whatever language you are working in) is extremely
37 limited. For example, the string "the first of every month" will
38 NOT be parsed as a valid frequency. A limited number of frequencies
39 can be expressed in a written out form (see OTHER FREQUENCY FORMATS
40 below), but most must be expressed in the format described below in
41 FREQUENCY NOTATION. In this document however, the written out form
42 will often be used for the sake of clarity.
43 Since a frequency typically refers to events could happen an
45 infinite number of times, you must specify either a date range or a
46 base date (or both) in order to determine actual dates on which an
47 event occurred.
48 Modifier
50 Complex recurring events may require the use of modifiers in order
51 to get them correct.
52 For example, in America, many places treat both Thanksgiving and
54 the day after as holidays. Thanksgiving is easy to define as the
55 frequency:
56 4th Thursday of every November
58 but the day after is NOT possible to define only as a frequency.
60 Depending on the year, the day after the 4th Thursday may be the
61 4th or 5th Friday.
62 The day after Thanksgiving must be defined as a frequency and a
64 modifier:
65 4th Thursday of every November
67 +1 day
68 The syntax for the various modifiers is described below in the
70 MODIFIERS section.
71 Base date
73 All recurrences have a base date which is a date on which a
74 recurring event is based.
75 The base date is not necessarily a date where the recurring event
77 occurs. Instead, it may be modified (with modifiers, or with values
78 specified in the recurrence) to actually produce a recurring event.
79 For example, if the frequency is
81 every other Friday at noon
83 the base date will be a Friday and the recurring event will happen
85 on that Friday, Friday two weeks later, Friday four weeks later,
86 etc. In all cases, the dates will be modified to be at noon.
87 If the frequency has a modifier, such as:
89 every other Friday
91 + 1 day
92 (and yes, this trivial example could be expressed as the frequency
94 'every other Saturday' with no modifiers), then the base date is
95 still on a Friday, but the actual recurring event is determined by
96 applying modifiers and occurs on Saturday.
97 Recurring events are assigned a number with the event that is
99 referred to by the base date being the 0th occurrence, the first
100 one after that as the 1st occurrence, etc. Recurring events can
101 also occur before the base date with the last time the recurring
102 event occurred before the base date is the -1th occurence.
103 So, if the frequency is
105 the first of every month
107 and the base date is 'Mar 1, 2000', then the 5 recurring events
109 around it are:
110 N Date
112 -2 Jan 1 2000
114 -1 Feb 1 2000
115 0 Mar 1 2000
116 +1 Apr 1 2000
117 +2 May 1 2000
118 In some cases, the Nth date may not be defined. For example, if the
120 frequency is:
121 the 31st of every month
123 and the base date is Mar 31, 2000, the 5 recurring events around it
125 are:
126 N Date
128 -2 Jan 31 2000
130 -1 undefined
131 0 Mar 31 2000
132 1 undefined
133 2 May 31 2000
134 As mentioned above, the base date is used to determine one of the
136 occurrences of the recurring event... but it may not actually be on
137 of those events.
138 As an example, for the recurring event:
140 every other Friday
142 a base date could be on a Friday, but it would also be possible to
144 have a base date on some other day of the week, and it could
145 unambiguously refer simply to a week, and the recurring event would
146 occur on Friday of that week.
147 In most cases, it won't be necessary to treat base dates with that
149 level of complexity, but with complicated recurring events, it may
150 be necessary. More information on how Date::Manip determines a
151 recurring event from a base date is given below in the section BASE
152 DATES.
153 Range
155 A date range is simply a starting and an ending date. When a range
156 is used (primarily in the dates method as described below), only
157 recurring events (with all modifiers applied) which happened on or
158 after the start date and on or before the end date are used.
159 For example, if the frequency was
161 the first of every month
163 and the start/end dates were Jan 1 2000 and May 31 2000, the list
165 of dates referred to would be:
166 Jan 1 2000
168 Feb 1 2000
169 Mar 1 2000
170 Apr 1 2000
171 May 1 2000
172 If no base date is specified, but a date range is specified, the
174 start date is used as the specified base date.
175 It should be noted that if both the range and base date are
177 specified, the range is not used to determine a base date. Also,
178 the first time the recurring event occurs in this range may NOT be
179 the 0th occurrence with respect to the base date, and that is
180 allowed.
181 NOTE: both dates in the range and the base date must all be in the
183 same time zone, and use the same Date::Manip::Base object.
184
186 The syntax for specifying a frequency requires some explanation. It is
187 very concise, but contains the flexibility to express every single type
188 of recurring event I could think of.
189 The syntax of the frequency description is a colon separated list of
191 the format Y:M:W:D:H:MN:S (which stand for year, month, week, etc.).
192 One (and only one) of the colons may optionally be replaced by an
193 asterisk, or an asterisk may be prepended to the string. For example,
194 the following are all valid frequency descriptions:
195 1:2:3:4:5:6:7
197 1:2*3:4:5:6:7
198 *1:2:3:4:5:6:7
199 But the following are NOT valid because they contain more than one
201 asterisk:
202 1:2*3:4:5*6:7
204 *1:2:3:4:5:6*7
205 When an asterisk is included, the portion to the left of it is called
207 the interval, and refers to an approximate time interval between
208 recurring events. For example, if the interval of the frequency is:
209 1:2*
211 it means that the recurring event occurs approximately every 1 year and
213 2 months. The interval is approximate because elements to the right of
214 the asterisk, as well as any modifiers included in the recurrence, will
215 affect when the events actually occur.
216 If no asterisks are included, then the entire recurrence is an
218 interval. For example,
219 0:0:0:1:12:0:0
221 refers to an event that occurs every 1 day, 12 hours.
223 The portion of the frequency that occur after an asterisk is called the
225 recurrence time (or rtime), and refers to a specific value (or values)
226 for that type of time element (i.e. exactly as it would appear on a
227 calendar or a clock). For example, if the frequency ends with the
228 rtime:
229 *12:0:0
231 then the recurring event occurs at 12:00:00 (noon).
233 For example:
235 0:0:0:2*12:30:0 every 2 days at 12:30 (each day)
237 Elements in the rtime can be listed as single values, ranges (2 numbers
239 separated by a dash "-"), or a comma separated list of values or
240 ranges. In some cases, negative values are appropriate for the week or
241 day values. -1 stands for the last possible value, -2 for the second to
242 the last, etc.
243 If multiple values are included in more than one field in the rtime,
245 every possible combination will be used. For example, if the frequency
246 ends with the rtime:
247 *12-13:0,30:0
249 the event will occur at 12:00, 12:30, 13:00, and 13:30.
251 Some examples are:
253 0:0:0:1*2,4,6:0:0 every day at at 02:00, 04:00, and 06:00
255 0:0:0:2*12-13:0,30:0 every other day at 12:00, 12:30, 13:00,
256 and 13:30
257 0:1:0*-1:0:0:0 the last day of every month
258 *1990-1995:12:0:1:0:0:0
259 Dec 1 in 1990 through 1995
260 There is no way to express the following with a single recurrence:
262 every day at 12:30 and 1:00
264 You have to use two recurrences to do this.
266 You can include negative numbers in ranges. For example, including the
268 range -2---1 means to go from the 2nd to the last to the last
269 occurrence. Negative values are only supported in the week and day
270 fields, and only in some cases.
271 You can even use a range like 2--2 (which means to go from the 2nd to
273 the 2nd to the last occurrence). However, this is STRONGLY discouraged
274 since this leads to a date which produces a variable number of events.
275 As a result, the only way to determine the Nth date is to calculate
276 every date starting at the base date. If you know that every date
277 produces exactly 4 recurring events, you can calculate the Nth date
278 without needing to determine every intermediate date.
279 When specifying a range, the first value must be less than the second
281 or else nothing will be returned.
282 When both the week and day elements are non-zero and the day is right
284 of the asterisk, the day refers to the day of week. The following
285 examples illustrate these type of frequencies:
286 0:1*4:2:0:0:0 4th Tuesday (day 2) of every month
288 0:1*-1:2:0:0:0 last Tuesday of every month
289 0:0:3*2:0:0:0 every 3rd Tuesday (every 3 weeks
290 on 2nd day of week)
291 1:0*12:2:0:0:0 the 12th Tuesday of each year
292 NOTE: The day of week refers to the numeric value of each day as
294 specified by ISO 8601. In other words, day 1 is ALWAY Monday, day 7 is
295 ALWAYS Sunday, etc., regardless of what day of the week the week is
296 defined to begin on (using the FirstDay config variable). So when the
297 day field refers to the day of week, it's value (or values if a range
298 or comma separated list are used) must be 1-7.
299 When the week element is zero and the month element is non-zero and the
301 day element is right of the asterisk, the day value is the day of the
302 month (it can be from 1 to 31 or -1 to -31 counting from the end of the
303 month).
304 3*1:0:2:12:0:0 every 3 years on Jan 2 at noon
306 0:1*0:2:12,14:0:0 2nd of every month at 12:00 and 14:00
307 0:1:0*-2:0:0:0 2nd to last day of every month
308 NOTE: If the day given refers to the 29th, 30th, or 31st, in a month
310 that does not have that number of days, it is ignored. For example, if
311 you ask for the 31st of every month, it will return dates in Jan, Mar,
312 May, Jul, etc. Months with fewer than 31 days will be ignored.
313 If both the month and week elements are zero, and the year element is
315 non-zero, the day value is the day of the year (1 to 365 or 366 -- or
316 the negative numbers to count backwards from the end of the year).
317 1:0:0*45:0:0:0 45th day of every year
319 Specifying a day that doesn't occur in that year silently ignores that
321 year. The only result of this is that specifying +366 or -366 will
322 ignore all years except leap years.
323 If the week element is non-zero and to the right of the asterisk, and
325 the day element is zero, the frequency refers to the first day of the
326 given week of the month or week of the year:
327 0:1*2:0:0:0:0 the first day of the 2nd week of
329 every month
330 1:0*2:0:0:0:0 the first day of the 2nd week of
331 every year
332 Although the meaning of almost every recurrence can be deduced by the
334 above rules, a set of tables describing every possible combination of
335 Y/M/W/D meanings, and giving an example of each is included below in
336 the section LIST OF Y/M/W/D FREQUENCY DEFINITIONS. It also explains a
337 small number of special cases.
338 NOTE: If all fields left of the asterisk are zero, the last one is
340 implied to be 1. In other words, the following are equivalent:
341 0:0:0*x:x:x:x
343 0:0:1*x:x:x:x
344 and can be thought of as every possible occurence of the rtime.
346 NOTE: When applying a frequency to get a list of dates on which a
348 recurring event occurs, a delta is created from the frequency which is
349 applied to get dates referred to by the interval. These are then
350 operated on by the rtime and by modifiers to actually get the recurring
351 events. The deltas will always be exact or approximate. There is no
352 support for business mode recurrences. However, with the careful use of
353 modifiers (discussed below), most recurring business events can be
354 determined too.
355
357 A recurrence of the form *Y:M:W:D:H:MN:S (which is technically speaking
358 not a recurring event... it is just a date or dates specified using the
359 recurrence syntax) uses the first date which matches the frequency as
360 the base date. Any base date specified will be completely ignored. A
361 date range may be specified to work with a subset of the dates.
362 All other recurrences use a specified base date in order to determine
364 when the 0th occurrence of a recurring event happens. As mentioned
365 above, the specified base date may be determined from the start date,
366 or specified explicitly.
367 The specified base date is used to provide the bare minimum
369 information. For example, the recurrence:
370 0:0:3*4:0:0:0 every 3 weeks on Thursday
372 requires a base date to determine the week, but nothing else. Using the
374 standard definition (Monday-Sunday) for a week, and given that one week
375 in August 2009 is Aug 10 to Aug 16, any date in the range Aug 10 to Aug
376 16 will give the same results. The definition of the week defaults to
377 Monday-Sunday, but may be modified using the FirstDay config variable.
378 Likewise, the recurrence:
380 1:3*0:4:0:0:0 every 1 year, 3 months on the 4th
382 day of the month
383 would only use the year and month of the base date, so all dates in a
385 given month would give the same set of recurring dates.
386 It should also be noted that a date may actually produce multiple
388 recurring events. For example, the recurrence:
389 0:0:2*4:12,14:0:0 every 2 weeks on Thursday at 12:00
391 and 14:00
392 produces 2 events for every date. So in this case, the base date
394 produces the 0th and 1st event, the base date + an offset produces the
395 2nd and 3rd events, etc.
396 It must be noted that the base date refers ONLY to the interval part of
398 the recurrence. The rtime and modifiers are NOT used in determining the
399 base date.
400
402 The interval of a frequency (everything left of the asterisk) will be
403 used to generate a list of dates (called interval dates). When rtime
404 values and modifiers are applied to an interval date, it produces the
405 actual recurring events.
406 As already noted, if the rtime values include multiple values for any
408 field, more than one event are produced by a single interval date.
409 It is important to understand is how the interval dates are calculated.
411 The interval is trivially turned into a delta. For example, with the
412 frequency 0:0:2*4:12:0:0, the interval is 0:0:2 which produces the
413 delta 0:0:2:0:0:0:0.
414 In order to get the Nth interval date, the delta is multiplied by N and
416 added to the base date. In other words:
417 D(0) = Jan 31
419 D(1) = Jan 31 + 1 month = Feb 28
420 D(2) = Jan 31 + 2 month = Mar 31
421
423 The start and end dates form the range in which recurring events can
424 fall into.
425 Every recurring date will fall in the limit:
427 start <= date <= end
429 When a recurrence is created, it may include a default range, and this
431 is handled by the RecurRange config variable.
432
434 There are a small handful of English strings (or the equivalent in
435 other languages) which can be parsed in place of a numerical frequency.
436 These include:
437 every Tuesday in June [1997]
439 2nd Tuesday in June [1997]
440 last Tuesday in June [1997]
441 every Tuesday of every month [in 1997]
443 2nd Tuesday of every month [in 1997]
444 last Tuesday of every month [in 1997]
445 every day of every month [in 1997]
447 2nd day of every month [in 1997]
448 last day of every month [in 1997]
449 every day [in 1997]
451 every 2nd day [in 1977]
452 every 2 days [in 1977]
453 Each of these set the frequency. If the year is include in the string,
455 it also sets the dates in the range to be the first and last day of the
456 year.
457 In each of these, the numerical part (i.e. 2nd in all of the examples
459 above) can be any number from 1 to 31. To make a frequency with a
460 larger number than that, you have to use the standard format discussed
461 above.
462 Due to the complexity of writing out (and parsing) frequencies written
464 out, I do not intend to add additional frequency formats, and the use
465 of these is discouraged. The frequency format described above is
466 preferred.
467
469 Any number of modifiers may be added to a frequency to get the actual
470 date of a recurring event. Modifiers are case sensitive.
471 Modifiers to set the day-of-week
473 The following modifiers can be used to adjust a date to a specific
474 day of the week.
475 PDn Means the previous day n not counting today
477 PTn Means the previous day n counting today
478 NDn Means the next day n not counting today
479 NTn Means the next day n counting today
480 WDn Day n (1-7) of the current week
481 In each of these, 'n' is 1-7 (1 being Sunday, 7 being Saturday).
483 For example, PD2/ND2 returns the previous/next Tuesday. If the date
485 that this is applied to is Tuesday, it modifies it to one week in
486 the past/future.
487 PT2/NT2 are similar, but will leave the date unmodified if it is a
489 Tuesday.
490 Modifiers to move forward/backward a number of days
492 These modifiers can be used to add/subtract n days to a date.
493 FDn Means step forward n days.
495 BDn Means step backward n days.
496 Modifiers to force events to be on business days
498 Modifiers can also be used to force recurring events to occur on
499 business days. These modifiers include:
500 FWn Means step forward n workdays.
502 BWn Means step backward n workdays.
503 CWD The closest work day (using the TomorrowFirst
505 config variable).
506 CWN The closest work day (looking forward first).
507 CWP The closest work day (looking backward first).
508 NWD The next work day counting today
510 PWD The previous work day counting today
511 DWD The closest work day (using the TomorrowFirst config
512 variable) counting today
513 IBD This discards the date if it is not a business day.
515 NBD This discards the date if it IS a business day.
516 The CWD, CWN, and CWP modifiers will always change the date to the
518 closest working day NOT counting the current date.
519 The NWD, PWD, and DWD modifiers always change the date to the
521 closest working day unless the current date is a work day. In that
522 case, it is left unmodified.
523 CWD, CWN, and CWP will usually return the same value, but if you
525 are starting at the middle day of a 3-day weekend (for example), it
526 will return either the first work day of the following week, or the
527 last work day of the previous week depending on whether it looks
528 forward or backward first.
529 All business day modifiers ignore the time, so if a date is
531 initially calculated at Saturday at noon, and the FW1 is applied,
532 the date is initially moved to the following Monday (assuming it is
533 a work day) and the FW1 moves it to Tuesday. The final result will
534 be Tuesday at noon.
535 The IBD and NBD modifiers eliminate dates from the list
537 immediately. In other words, if a recurrence has three modifiers:
538 FD1,IBD,FD1
540 then as a date is being tested, first the FD1 modifier is applied.
542 Then, it is tested to see if it is a business day. If it is, the
543 second FD1 modifier will be applied. Otherwise, the date will not
544 be included in the list of recurring events.
545 Special modifiers
547 The following modifiers do things that cannot be expressed using
548 any other combination of frequency and modifiers:
549 EASTER Set the date to Easter for this year.
551
553 In order to get a list of dates referred to by the recurrence, the
554 following steps are taken.
555 The recurrence is tested for errors
557 The recurrence must be completely specified with a base date
558 (either supplied explicitly, or derived from a start date) and date
559 range when necessary. All dates must be valid.
560 The actual base date is determined
562 Using information from the interval and the specified base date,
563 the actual base date is determined.
564 The Nth date is calculated
566 By applying the delta that corresponds to the interval, and then
567 applying rtime and modifier information, the Nth date is
568 determined.
569 This is repeated until all desired dates have been obtained.
571 The nth method described below has more details.
573 The range is tested
575 Any date that fall outside the range is discarded.
576 NOTE: when the recurrence contains no interval, it is not necessary
578 to specify the range, and if it is not specified, all of the dates
579 are used. The range MAY be specified to return only a subset of the
580 dates if desired.
581
583 Because the week and day values may have multiple meanings depending on
584 where the asterisk is, and which of the fields have non-zero values, a
585 list of every possible combination is included here (though most can be
586 determined using the rules above).
587 When the asterisk occurs before the day element, and the day element is
589 non-zero, the day element can take on multiple meanings depending on
590 where the asterisk occurs, and which leading elements (year, month,
591 week) have non-zero values. It can refer to the day of the week, day of
592 the month, or day of the year.
593 When the asterisk occurs before the week element, the week element of
595 the frequency can also take on multiple meanings as well. When the
596 month field and day fields are zero, it refers to the week of the year.
597 Since the week of the year is well defined in the ISO 8601 spec, there
598 is no ambiguity.
599 When the month field is zero, but the day field is not, the week field
601 refers to the nth occurrence of the day of week referred to by the day
602 field in the year.
603 When the month field is non-zero, the week field refers to the nth
605 occurrence of the day of week in the month.
606 In the tables below only the first 4 elements of the frequency are
608 shown. The actual frequency will include the hour, minute, and second
609 elements in addition to the ones shown.
610 When all elements left of the asterisk are 0, the interval is such that
612 it occurs the maximum times possible (without changing the type of
613 elements to the right of the asterisk). Another way of looking at it is
614 that the last 0 element of the interval is changed to 1. So, the
615 interval:
616 0:0*3:0
618 is equivalent to
620 0:1*3:0
622 When the year field is zero, and is right of the asterisk, it means the
624 current year.
625 All elements left of the asterisk
627 When all of the month, week, and day elements are left of the
628 asterisk, the simple definitions of the frequency are used:
629 frequency meaning
631 1:2:3:4 every 1 year, 2 months, 3 weeks,
633 4 days
634 Any, or all of the fields can be zero.
636 Non-zero day, non-zero week
638 When both the day and week elements are non-zero, the day element
639 always refers to the day of week. Values must be in the range (1 to
640 7) and no negative values are allowed.
641 The following tables shows all possible variations of the frequency
643 where this can happen (where day 4 = Thursday).
644 When the week is left of the asterisk, the interval is used to get
646 the weeks on the calendar containing a recurring date, and the day
647 is used to set the day of the week. The following are possible:
648 frequency meaning
650 1:2:3*4 every 1 year, 2 months, 3 weeks
652 on Thur
653 1:0:3*4 every 1 year, 3 weeks on Thur
655 0:2:3*4 every 2 months, 3 weeks on Thur
657 0:0:3*4 every 3 weeks on Thur
659 When the week is right of the asterisk, and a non-zero month is
661 left of the asterisk, the recurrence refers to a specific
662 occurrence of a day-of-week during a month. The following are
663 possible:
664 frequency meaning
666 1:2*3:4 every 1 year, 2 months on the
668 3rd Thursday of the month
669 0:2*3:4 every 2 months on the 3rd Thur
671 of the month
672 When the week and month are both non-zero and right of the
674 asterisk, the recurrence refers to an occurrence of day-of-week
675 during the given month. Possibilities are:
676 frequency meaning
678 1*2:3:4 every 1 year in February on
680 the 3rd Thur
681 0*2:3:4 same as 1*2:3:4
683 *1:2:3:4 in Feb 0001 on the 3rd Thur
685 of the month
686 *0:2:3:4 on the 3rd Thur of Feb in the
688 current year
689 When the week is right of the asterisk, and the month is zero, the
691 recurrence refers to an occurence of the day-of-week during the
692 year. The following are possible:
693 frequency meaning
695 1:0*3:4 every 1 year on the 3rd Thursday
697 1*0:3:4 of the year
698 *1:0:3:4 in 0001 on the 3rd Thur of
700 the year
701 0*0:3:4 same as 1*0:3:4
703 *0:0:3:4 on the 3rd Thur of the current
705 year
706 There is one special case:
708 frequency meaning
710 0:0*3:4 same as 0:1*3:4 (every month on
712 the 3rd Thur of the month)
713 Non-zero day, non-zero month
715 When a non-zero day element occurs to the right of the asterisk and
716 the week element is zero, but the month element is non-zero, the
717 day elements always refers to a the day of month in the range (1 to
718 31) or (-1 to -31).
719 The following table shows all possible variations of the frequency
721 where this can happen:
722 frequency meaning
724 1:2:0*4 every 1 year, 2 months on the
726 1:2*0:4 4th day of the month
727 1*2:0:4 every year on Feb 4th
729 *1:2:0:4 Feb 4th, 0001
731 0:2:0*4 every 2 months on the 4th day
733 0:2*0:4 of the month
734 0*2:0:4 same as 1*2:0:4
736 *0:2:0:4 Feb 4th of the current year
738 Zero day, non-zero week
740 When a day is zero, and the week is non-zero, the recurrence refers
741 to a specific occurrence of the first day of the week (as given by
742 the FirstDay variable).
743 The frequency can refer to an occurrence of FirstDay in a specific
745 week (if the week is left of the asterisk):
746 frequency meaning
748 1:2:3*0 every 1 year, 2 months, 3 weeks on
750 FirstDay
751 1:0:3*0 every 1 year, 3 weeks on FirstDay
753 0:2:3*0 every 2 months, 3 weeks on FirstDay
755 0:0:3*0 every 3 weeks on FirstDay
757 or to a week in the year (if the week is right of the asterisk, and
759 the month is zero):
760 frequency meaning
762 1:0*3:0 every 1 year on the first day of the
764 1*0:3:0 3rd week of the year
765 *1:0:3:0 the first day of the 3rd week of 0001
767 or to an occurrence of FirstDay in a month (if the week is right of
769 the asterisk and month is non-zero):
770 frequency meaning
772 1:2*3:0 every 1 year, 2 months on the 3rd
774 occurence of FirstDay
775 0:2*3:0 every 2 months on the 3rd occurence
777 of FirstDay
778 1*2:3:0 every year on the 3rd occurence
780 of FirstDay in Feb
781 0*2:3:0 same as 1*2:3:0
783 *1:2:3:0 the 3rd occurence of FirstDay
785 Feb 0001
786 *0:2:3:0 the 3rd occurence of FirstDay
788 in Feb of the current year
789 NOTE: in the last group, a slightly more intuitive definition of
791 these would have been to say that the week field refers to the week
792 of the month, but given the ISO 8601 manner of defining when weeks
793 start, this definition would have virtually no practical
794 application. So the definition of the week field referring to the
795 Nth occurence of FirstDay in a month was used instead.
796 There are a few special cases here:
798 frequency meaning
800 0:0*3:0 same as 0:1*3:0 (every month on the 3rd
802 occurence of the first day of week)
803 0*0:3:0 same as 1*0:3:0
805 *0:0:3:0 the first day of the 3rd week of the
807 current year
808 Non-zero day
810 When a non-zero day element occurs and both the month and week
811 elements are zero, the day elements always refers to a the day of
812 year (1 to 366 or -1 to -366 to count from the end).
813 The following table shows all possible variations of the frequency
815 where this can happen:
816 frequency meaning
818 1:0:0*4 every year on the 4th day of
820 1:0*0:4 the year
821 1*0:0:4
822 *1:0:0:4 the 4th day of 0001
824 Other non-zero day variations have multiple meanings for the day
826 element:
827 frequency meaning
829 0:0:0*4 same as 0:0:1*4 (every week on Thur)
831 0:0*0:4 same as 0:1*0:4 (every month on the 4th)
833 0*0:0:4 same as 1*0:0:4
835 *0:0:0:4 the 4th day of the current year
837 All other variations
839 The remaining variations have zero values for both week and day.
840 They are:
841 frequency meaning
843 1:2:0*0 every 1 year, 2 months on the first
845 1:2*0:0 day of the month
846 1*2:0:0 every year on Feb 1
848 *1:2:0:0 Feb 1, 0001
850 1:0:0*0 every 1 year on Jan 1
852 1:0*0:0
853 1*0:0:0
854 *1:0:0:0 Jan 1, 0001
856 0:2:0*0 every 2 months on the first day of
858 0:2*0:0 the month
859 0*2:0:0 same as 1*2:0:0
861 *0:2:0:0 Feb 1 of the current year
863 0:0:0*0 same as 0:0:1*0 (every week on
865 the first day of the week)
866 0:0*0:0 same as 0:1*0:0 (every month
868 on the 1st)
869 0*0:0:0 same as 1*0:0:0
871 *0:0:0:0 Jan 1 of the current year
873
875 new
876 new_config
877 new_date
878 new_delta
879 new_recur
880 base
881 tz
882 is_date
883 is_delta
884 is_recur
885 config
886 err Please refer to the Date::Manip::Obj documentation for these
887 methods.
888 parse
890 $err = $recur->parse($string [,$modifiers] [,$base,$start,$end]);
891 This creates a new recurrence. A string containing a valid
893 frequency is required. In addition, $start, $end, and $base dates
894 can be passed in (either as Date::Manip::Date objects, or as
895 strings containing dates that can be parsed), and any number of the
896 modifiers listed above.
897 If the $start or $end dates are not included, they may be supplied
899 automatically, based on the value of the RecurRange variable. If
900 any of the dates are passed in, they must be included in the order
901 given (though it is safe to pass an empty string or undef in for
902 any of them if you only want to set some, but not all of them).
903 The $modifiers argument must either contain valid modifiers, or be
905 left out of the argument list entirely. You cannot pass an empty
906 string or undef in for it.
907 $err = $recur->parse($string);
909 This creates a recurrence from a string which contains all of the
911 necessary elements of the recurrence. The string is of the format:
912 FREQ*MODIFIERS*BASE*START*END
914 where FREQ is a string containing a frequency, MODIFIERS is a
916 string containing a comma separated list of modifiers, BASE, START,
917 and END are strings containing parseable dates.
918 All pieces are optional, but order must be maintained, so all of
920 the following are valid:
921 FREQ*MODIFIERS
923 FREQ**BASE
924 FREQ**BASE*START*END
925 If a part of the recurrence is passed in both as part of $string
927 and as an argument, the argument overrides the string portion, with
928 the possible exception of modifiers. The modifiers in the argument
929 override the string version unless the first one is a '+' in which
930 case they are appended. See the modifiers method below for more
931 information.
932 frequency
934 start
935 end
936 basedate
937 modifiers
938 You can also create a recurrency in steps (or replace parts of an
939 existing recurrence) using the following:
940 $err = $recur->frequency($frequency);
942 $err = $recur->start($start);
944 $err = $recur->end($end);
945 $err = $recur->basedate($base);
947 $err = $recur->modifiers($modifiers);
949 $err = $recur->modifiers(@modifiers);
950 These set the appropriate part of the recurrence.
952 Calling the frequency method discards all information currently
954 stored in the Recur object (including an existing start, end, and
955 base date), so this method should be called first.
956 In the modifiers method, the modifiers can be passed in as a string
958 containing a comma separated list of modifiers, or as a list of
959 modifiers. The modifiers passed in override all previously set
960 modifiers UNLESS the first one is the string "+", in which case the
961 new modifiers are appended to the list.
962 In the start, end, and base methods, the date passed in can be a
964 Date::Manip::Date object, or a string that can be parsed to get a
965 date.
966 NOTE: the parse method will overwrite all parts of the recurrence,
968 so it is not appropriate to do:
969 $recur->modifiers($modifiers);
971 $recur->parse($string);
972 The modifiers passed in in the first call will be overwritten.
974 These functions can also be used to look up the values.
976 $freq = $recur->frequency();
978 $start = $recur->start();
979 $end = $recur->end();
980 @mods = $recur->modifiers();
981 ($base,$actual) = $recur->basedate();
983 The basedate function will return both the specified base and the
985 actual base dates.
986 If any of the values are not yet determined, nothing will be
988 returned.
989 dates
991 @dates = $recur->dates([$start,$end]);
992 Returns the list of dates defined by the full recurrence. If there
994 is an error, or if there are no dates, an empty list will be
995 returned.
996 $start and $end are either undef, or dates which can be used to
998 limit the set of dates passed back (they can be Date::Manip::Date
999 objects or strings that can be parsed).
1000 If the recurrence does not have a start and end date already,
1002 passing in $start and $end will set the range (but they will NOT be
1003 stored in the recurrence).
1004 If the recurrence does have a start and end date stored in it, the
1006 $start and $end arguments can be used to temporarily override the
1007 limits. For example, if a recurrence has a start date of Jan 1,
1008 2006 00:00:00 and and end date of Dec 31, 2006 23:59:59 stored in
1009 the recurrence, passing in $start of Jul 1, 2006 00:00:00 will
1010 limit the dates returned to the range of Jul 1 to Dec 31.
1011 Passing in a start date of Jul 1, 2007 will mean that no dates are
1013 returned since the recurrence limits the date to be in 2006.
1014 If one or both of $start and $end are undef, then the stored values
1016 will be used.
1017 nth
1019 ($date,$err) = $recur->nth($n);
1020 This returns the $n'th recurring event ($n may be any integer). If
1022 an error occurs, it is returned (but it is not set in $recur since
1023 it may be properly, though perhaps incompletely, defined). The
1024 following errors may be returned:
1025 Invalid recurrence
1027 The recurrence has an error flag set.
1028 Incomplete recurrence
1030 The recurrence is incomplete. It needs either a
1031 base date or a date range.
1032 Range invalid
1034 The recurrence has an invalid date range (i.e.
1035 the end date occurs before the start date).
1036 Start invalid
1038 End invalid
1039 Base invalid
1040 An invalid date was entered for one of the dates.
1041 There are a few special circumstances to be aware of.
1043 1) If the recurrence contains no interval (i.e. is of the form
1045 *Y:M:W:D:H:MN:S), the dates come directly from the rtime values.
1046 In this case, the 0th event is the first date in the list of dates
1047 specified by the rtime. As such, $n must be a positive integer. If
1048 $n is negative, or outside the range of dates specified, the
1049 returned date will be undef (but this is not an error).
1050 2) A very small number of recurrences have an unknown number of
1052 recurring events associated with each date. This only happens if
1053 one of the values in the rtime is specified as a range including
1054 both a positive and negative index. For example, if the day field
1055 in an rtime refers to the day of month, and is 15--15 (i.e. the
1056 15th day to the 15th to the last day), this may include 3 events
1057 (on a month with 31 days), 2 event (months with 30 days), 1 event
1058 (months with 29 days), or 0 events (months with 28 days). As such,
1059 in order to calculate the Nth date, you have to start with the 0th
1060 (i.e. base) date and calculate every event until you get the Nth
1061 one. For this reason, it is highly recommended that this type of
1062 frequency be avoided as it will be quite slow.
1063 3) Most recurrences have a known number of events (equal to the
1065 number of combinations of values in the rtime) for each date. For
1066 these, calculating the Nth date is much faster. However, in this
1067 case, some of them may refer to an invalid date. For example, if
1068 the frequency is 'the 31st of every month' and the base (0th) date
1069 is Jan 31, the 1st event would refer to Feb 31. Since that isn't
1070 valid, undef would be returned for $n=1. Obviously, it would be
1071 possible to actually determine the Nth valid event by calculating
1072 all N-1 dates, but in the interest of performance, this is not
1073 done.
1074 4) The way the Nth recurring event is calculated differs slightly
1076 for NE>0 and N<0 if the delta referred to by the frequency is
1077 approximate. To calculate the Nth recurring event (where N>0), you
1078 take the base date and add N*DELTA (where DELTA is the delta
1079 determined by the frequency). To get the Nth recurring event
1080 (where N<0), a date is determine which, if N*DELTA were added to
1081 it, would produce the base date. For more details, refer to the
1082 Date::Manip::Calc document. In the SUBTRACTION section in the
1083 discussion of approximate date-delta calculations, calculations are
1084 done with $subtract = 2.
1085 next
1087 prev
1088 ($date,$err) = $recur->next();
1089 ($date,$err) = $recur->prev();
1090 These return the next/previous recurring event.
1092 The first time next/prev is called, one of the recurring events
1094 will be selected and returned (using the rules discussed below).
1095 Subsequent calls to next/prev will return the next or previous
1096 event.
1097 Unlike the nth method which will return a specific event (or undef
1099 if the Nth even is not defined), the next and prev methods will
1100 only work with defined events.
1101 So, for the recurrence:
1103 the 31st of every month
1105 next might return the following sequence of events:
1107 Jan 31 2000
1109 Mar 31 2000
1110 May 31 2000
1111 The rules for determining what event to return the first time one
1113 of these is called are as follows:
1114 1) If there is a range, next will return the first event that
1116 occurs after the start of the range. prev will return the last
1117 event that occurs before the end of the range.
1118 2) If there is no range, next will return the first event on or
1120 after the base date. prev will return the last event before the
1121 base date.
1122 The error codes are the same as for the nth method.
1124
1126 I realize that the frequency notation described above looks quite
1127 complicated at first glance, but it is (IMO) the best notation for
1128 expressing recurring events in existence. I actually consider it the
1129 single most important contribution to date/time handling in
1130 Date::Manip.
1131 When I first decided to add recurring events to Date::Manip, I first
1133 came up with a list of common ways of specifying recurring events, and
1134 then went looking for a notation that could be used to define them. I
1135 was hoping for a notation that would be similar to cron notation, but
1136 more powerful.
1137 After looking in several specifications (including ISO 8601) and after
1139 a discussion on a mailing list of calendar related topics, it appeared
1140 that there was no concise, flexible notation for handling recurring
1141 events that would handle all of the common forms I'd come up with.
1142 So, as a matter of necessity, I set about inventing my own notation.
1144 As I was looking at my list, it struck me that all of the parts which
1145 specified a frequency were higher level (i.e. referred to a larger unit
1146 of time) than those parts which specified a specific value (what I've
1147 called the rtime). In other words, when the terms were laid out from
1148 year down to seconds, the frequency part was always left of specific
1149 values.
1150 That led immediately to the notation described above, so I started
1152 analyzing it to figure out if it could express all of the recurring
1153 events I'd come up with. It succeeded on 100% of them. Not only that,
1154 but by playing with different values (especially different combinations
1155 of m/w/d values), I found that it would define recurring events that I
1156 hadn't even thought of, but which seemed perfectly reasonable in
1157 hindsight.
1158 After a very short period, I realized just how powerful this notation
1160 was, and set about implementing it, and as I said above, of all the
1161 contributions that Date::Manip has made, I consider this to be the most
1162 important.
1163
1165 If you specify a recurrence which cannot be satisfied for the base
1166 date, or for any time after the base date, the recurrence will crash.
1167 This can only happen if you specify a recurrence that always occurs in
1168 the spring DST transition using the current timezone rules.
1169 For example, in a US timezone, the current timezone rules state that a
1171 DST transition occurs at 02:00:00 on the 2nd Sunday in March and the
1172 clock jumps to 03:00. This started in 2006. As a result, the
1173 recurrence
1174 1*3:2:7:2:0:0
1176 with a base date of 2006 or later cannot be satisfied.
1178
1180 Please refer to the Date::Manip::Problems documentation for information
1181 on submitting bug reports or questions to the author.
1182
1184 Date::Manip - main module documentation
1185
1187 This script is free software; you can redistribute it and/or modify it
1188 under the same terms as Perl itself.
1189
1191 Sullivan Beck (sbeck@cpan.org)
1192perl v5.16.3 2014-06-09 Date::Manip::Recur(3)