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 defining when a recurring
15 event occurs. For example, if an event occurs every other Friday or
16 every 4 hours, this can be defined as a recurrence. A fully specified
17 recurrence consists of the following pieces of information:
18 Frequency
20 The most basic piece of information is a frequency which is the
21 description of when the event occurs.
22 Examples include:
24 the first of every month
26 every other day
27 the 4th Thursday of each month at 2:00 PM
28 every 2 hours and 30 minutes
29 All of these can be expressed as a frequency.
31 NOTE: When applying a frequency to get a list of dates on which a
33 recurring event occurs, a delta is created from the frequency which
34 is applied repeatedly to get all dates on which a recurring event
35 occurs. The deltas will always be exact or approximate. There is
36 no support for business mode recurrences. However, with the careful
37 use of modifiers (discussed below), most recurring business events
38 can be determined too.
39 Range
41 In order to actually get a list of dates on which a recurring event
42 occur, a start and end date are required for all but the most
43 trivial recurrences.
44 For example, if the frequency was
46 the first of every month
48 and the start/end dates were Jan 1 2000 and May 31 2000, you could
50 get the dates:
51 Jan 1 2000
53 Feb 1 2000
54 Mar 1 2000
55 Apr 1 2000
56 May 1 2000
57 Base date
59 With most frequencies, it is necessary to have a base date (a date
60 on which the recurring event occurred) in order to determine other
61 dates when it will occur.
62 A frequency like:
64 the first of every month
66 does not require a base date, but a frequency like:
68 every other Friday
70 does. Without a base date, it's impossible to determine whether any
72 given Friday is one in which the event occurs, or one in which it
73 does not occur.
74 NOTE: For performance reasons, it is useful (but not required) for
76 the base date to occur as close to the start of the range as
77 possible. Placing the base date as the last date on which the event
78 occurs on or before the start date is ideal. The further the base
79 date is away from this date, the more intermediate calculations
80 will need to be done.
81 Modifier
83 Complex recurring events may require the use of modifiers in order
84 to get them correct.
85 For example, in America, many places treat Thanksgiving and the day
87 after as holidays.
88 Thanksgiving is easy to define using the frequency:
90 4th Thursday of every November
92 but the day after is NOT possible to define only as a frequency.
94 Depending on the year, the day after the 4th Thursday may be the
95 4th or 5th Friday.
96 The day after Thanksgiving can be defined as the frequency and
98 modifier:
99 4th Thursday of every November
101 +1 day
102 Modifiers can also be used to create events that happen only on
104 business days.
105 With these pieces of information, the list of dates in the range can be
107 obtained where the recurring event occurs.
108 NOTE: both dates in the range and the base date (if necessary) must all
110 be in the same time zone, and use the same Date::Manip::Base object.
111
113 The syntax for specifying a frequency requires some explanation. It is
114 very concise, but contains the flexibility to express every single type
115 of recurring event I could think of.
116 The syntax of the frequency description is a colon separated list of
118 the format Y:M:W:D:H:MN:S (which stand for year, month, week, etc.).
119 One (and only one) of the colons may optionally be replaced by an
120 asterisk, or an asterisk may be prepended to the string. For example,
121 the following are all valid frequency descriptions:
122 1:2:3:4:5:6:7
124 1:2*3:4:5:6:7
125 *1:2:3:4:5:6:7
126 But the following are NOT valid because they contain 2 or more
128 asterisks:
129 1:2*3:4:5*6:7
131 *1:2:3:4:5:6*7
132 When an asterisk is included, the portion to the left of it is called
134 the interval, and refers to a time interval between recurring events.
135 For example, if the interval of the frequency is:
136 1:2*
138 it means that the recurring event occurs approximately every 1 year and
140 2 months. The interval is approximate because elements to the right of
141 the asterisk, as well as any modifiers included in the recurrence, will
142 affect when the actual events occur.
143 If no asterisks are included, then the entire recurrence is an
145 interval. For example,
146 0:0:0:1:12:0:0
148 refers to an event that occurs every 1 day, 12 hours.
150 The portion of the frequency that occur after an asterisk is called the
152 recurrence time (or rtime), and refers to a specific value (or values)
153 for that type of time element (i.e. exactly as it would appear on a
154 calendar or a clock). For example, if the frequency ends with the
155 rtime:
156 *12:0:0
158 then the recurring event occurs at 12:00:00 (noon).
160 For example:
162 0:0:0:2*12:30:0 every 2 days at 12:30 (each day)
164 Elements in the rtime can be listed as single values, ranges (2 numbers
166 separated by a dash "-"), or a comma separated list of values or
167 ranges. In most cases, negative values are appropriate for the week or
168 day values. -1 stands for the last possible value, -2 for the second to
169 the last, etc.
170 If multiple values are included in more than one field in the rtime,
172 every possible combination will be used. For example, if the frequency
173 ends with the rtime:
174 *12-13:0,30:0
176 the event will occur at 12:00, 12:30, 13:00, and 13:30.
178 Some examples are:
180 0:0:0:1*2,4,6:0:0 every day at at 02:00, 04:00, and 06:00
182 0:0:0:2*12-13:0,30:0 every other day at 12:00, 12:30, 13:00,
183 and 13:30
184 0:1:0*-1:0:0:0 the last day of every month
185 *1990-1995:12:0:1:0:0:0
186 Dec 1 in 1990 through 1995
187 There is no way to express the following with a single recurrence:
189 every day at 12:30 and 1:00
191 You have to use two recurrences to do this.
193 You can include negative numbers in ranges. For example, including the
195 range 2--2 in the day element means to go from the 2nd day to the 2nd
196 to the last day. Currently, negative values are only defined in the
197 week and day fields.
198 When specifying a range, the first value must be less than the second
200 or else nothing will be returned.
201 When both the week and day elements are non-zero and the day is right
203 of the asterisk, the day refers to the day of week. The following
204 examples illustrate these type of frequencies:
205 0:1*4:2:0:0:0 4th Tuesday (day 2) of every month
207 0:1*-1:2:0:0:0 last Tuesday of every month
208 0:0:3*2:0:0:0 every 3rd Tuesday (every 3 weeks
209 on 2nd day of week)
210 1:0*12:2:0:0:0 the 12th Tuesday of each year
211 NOTE: The day of week refers to the numeric value of each day as
213 specified by ISO 8601. In other words, day 1 is ALWAY Monday, day 7 is
214 ALWAYS Sunday, etc., regardless of what day of the week the week is
215 defined to begin on (using the FirstDay config variable). So when the
216 day field refers to the day of week, it's value must be 1-7 (it cannot
217 be a negative number), a range, or a comma separated list.
218 When the week element is zero and the month element is non-zero and the
220 day element is right of the asterisk, the day value is the day of the
221 month (it can be from 1 to 31 or -1 to -31 counting from the end of the
222 month).
223 3*1:0:2:12:0:0 every 3 years on Jan 2 at noon
225 0:1*0:2:12,14:0:0 2nd of every month at 12:00 and 14:00
226 0:1:0*-2:0:0:0 2nd to last day of every month
227 NOTE: If the day given refers to the 29th, 30th, or 31st, in a month
229 that does not have that number of days, it is ignored. For example, if
230 you ask for the 31st of every month, it will return dates in Jan, Mar,
231 May, Jul, etc. Months with fewer than 31 days will be ignored.
232 If both the month and week elements are zero, and the year element is
234 non-zero, the day value is the day of the year (1 to 365 or 366 -- or
235 the negative numbers to count backwards from the end of the year).
236 1:0:0*45:0:0:0 45th day of every year
238 Specifying a day that doesn't occur in that year silently ignores that
240 year. The only result of this is that specifying +366 or -366 will
241 ignore all years except leap years.
242 If the week element is non-zero and to the right of the asterisk, and
244 the day element is zero, the frequency refers to the first day of the
245 given week of the month or week of the year:
246 0:1*2:0:0:0:0 the first day of the 2nd week of
248 every month
249 1:0*2:0:0:0:0 the first day of the 2nd week of
250 every year
251 A set of tables describing every possible combination of Y/M/W/D
253 meanings, and giving an example of each is included below in the
254 section LIST OF Y/M/W/D FREQUENCY DEFINITIONS.
255 NOTE: If all fields left of the asterisk are zero, the last one is
257 implied to be 1. In other words, the following are equivalent:
258 0:0:0*x:x:x:x
260 0:0:1*x:x:x:x
261 and can be thought of as every possible occurence of the rtime.
263
265 As mentioned above, base dates are not required for some types of
266 recurrences.
267 Any time a frequency refers to every single possible value as specified
269 by the rtime, no base date is required.
270 For example, the frequency:
272 0:0:1*1:12:0:0 every Monday at noon
274 refers to every single "Monday at noon" (which is the value specified
276 by the rtime).
277 The frequency:
279 0:0:2*1:12:0:0 every other Monday at noon
281 does not, so a base date is required.
283 The general rule is that if an interval consists of zeros followed by a
285 single one (i.e. 0:0:1), no base date is required.
286 A recurrence of the form *Y:M:W:D:H:MN:S also does not use a base date.
288 The base date is used to provide the bare minimum information. For
290 example, the recurrence:
291 0:0:3*4:0:0:0 every 3 weeks on Thursday
293 requires a base date to determine the week, but nothing else. Using the
295 standard definition (Monday-Sunday) for a week, and given that one week
296 in August 2009 is Aug 10 to Aug 16, any date in the range Aug 10 to Aug
297 16 will give the same results.
298 Likewise, the recurrence:
300 1:3*0:4:0:0:0 every 1 year, 3 months on the 4th
302 day of the month
303 would only use the year and month of the base date, so all dates in a
305 given month would give the same set of recurring dates.
306 If a base date is specified for a recurrence which does not require it,
308 it will be completely ignored.
309 A default base date is not supplied when a recurrence is created.
311
313 The start and end dates form the range in which recurring events can
314 fall into.
315 Every recurring date will fall in the limit:
317 start <= date <= end
319 When a recurrence is created, it may include a default range, and this
321 is handled by the RecurRange config variable.
322
324 There are a small handful of English strings (or the equivalent in
325 other languages) which can be parsed in place of a numerical frequency.
326 These include:
327 every Tuesday in June [1997]
329 2nd Tuesday in June [1997]
330 last Tuesday in June [1997]
331 every Tuesday of every month [in 1997]
333 2nd Tuesday of every month [in 1997]
334 last Tuesday of every month [in 1997]
335 every day of every month [in 1997]
337 2nd day of every month [in 1997]
338 last day of every month [in 1997]
339 every day [in 1997]
341 every 2nd day [in 1977]
342 every 2 days [in 1977]
343 Each of these set the frequency. If the year is include in the string,
345 it also sets the dates in the range to be the first and last day of the
346 year.
347 In each of these, the numerical part (i.e. 2nd in all of the examples
349 above) can be any number from 1 to 31. To make a frequency with a
350 larger number than that, you have to use the standard format discussed
351 above.
352
354 The following modifiers can be used (all of which are case
355 insensitive).
356 PDn : n is 1-7. Means the previous day n not counting
358 today
359 PTn : n is 1-7. Means the previous day n counting today
360 NDn : n is 1-7. Means the next day n not counting today
361 NTn : n is 1-7. Means the next day n counting today
362 FDn : n is any number. Means step forward n days.
364 BDn : n is any number. Means step backward n days.
365 FWn : n is any number. Means step forward n workdays.
366 BWn : n is any number. Means step backward n workdays.
367 CWD : the closest work day (using the TomorrowFirst
369 config variable).
370 CWN : the closest work day (looking forward first).
371 CWP : the closest work day (looking backward first).
372 The CWD. CWM. amd CWP will always change the
374 date to the closest work day NOT counting
375 today.
376 NWD : next work day counting today
378 PWD : previous work day counting today
379 DWD : closest work day (using the TomorrowFirst config
380 variable) counting today
381 The NWD, PWD, and DWD flags all leave the date
383 unchanged if it is a work day.
384 EASTER: select easter for this year.
386 CWD, CWN, and CWP will usually return the same value, but if you are
388 starting at the middle day of a 3-day weekend (for example), it will
389 return either the first work day of the following week, or the last
390 work day of the previous week depending on whether it looks forward or
391 backward first.
392 All business day modifiers ignored the time, so if a date is initially
394 calculated at Saturday at noon, and the FW1 is applied, the date is
395 initially moved to the following Monday (assuming it is a work day) and
396 the FW1 moves it to Tuesday. The final result will be Tuesday at noon.
397 There is a practical limitation on how the list of dates are
399 calculated.
400 When calculating a list of dates, the first thing is to use the
402 interval to get a list if dates. The rtime and modifiers are then
403 applied to this list, and the final list is compared to the start and
404 end dates, and those dates within this range are returned.
405 Because dates near the edge of the range may (based on the rtime and
407 modifiers) move outside the range, and dates just outside the range may
408 move into the range, dates outside the range have to be added to the
409 initial list. As a result, when modifiers are present, the first thing
410 to do is to expand the initial range to include all dates which will
411 fall inside the actual range (as specified by the begin/end date).
412 So, for example, if you have begin and end dates of Jan 10 and Jan 15,
414 and a modifier of FD2 (forward 2 days), then the interval will be
415 applied to dates in the range Jan 7 to Jan 14. This is obtained by
416 applying the FD2 modifier to get Jan 8 to Jan 13 and then adding a 1
417 day fudge factor on each side to account for any changes due to the
418 mtime.
419 The only problem is when applying business day modifiers. Moving
421 forward 1 business day (with no holidays defined, and only using the
422 standard weekend definition) may mean moving forward anywhere from 1 to
423 3 days. With holidays included, it could theoretically mean moving
424 forward up to a year (i.e. if there were only 1 work day in the year,
425 and all others were holidays).
426 In real life, it won't ever get quite that bad, but it is not at all
428 unheard of for companies to close for one or two weeks at a time. As a
429 result, there is no way to know exactly how many days to adjust the
430 range by to be guaranteed of getting all valid dates.
431 A best guess is obtained by taking into account the length of the week
433 and then applying a somewhat arbitrary fudge factor.
434 For example, if the standard work week is 5 days on, 2 days off, and
436 you move forward 2 business days, that could be anywhere from 2 to 5
437 actual days. Finally a fudge factor is applied to make sure that the
438 range includes all possible days.
439 The default fudge factor is 5 days, so forward 2 business days would be
441 treated as forward 2 to 10 actual days, which should be enough to get
442 every possible date in real life.
443 The fudge factor can be set to something other than 5 using the
445 RecurNumFudgeDays config variable. It it is set to be the total number
446 of holidays in the year plus 1, it should always yield correct results,
447 but at some expense.
448
450 In order to get a list of dates referred to by the recurrence, the
451 following steps are taken.
452 A list of dates is calculated
454 Based on the interval, the base date, and the range, a list of
455 dates is calculated from the interval.
456 The list of dates initially includes all dates that fall inside the
458 range plus at least one before the range, and at least one after
459 the range. This allows dates near the edge of the range which
460 might be pushed across the edge when the rtime values are applied,
461 or modifiers applied.
462 NOTE: if the recurrence contains no interval (i.e. is of the form
464 *Y:M:W:D:H:MN:S), no date list is determined. The dates come
465 directly from the rtime values.
466 The rtime values are applied
468 All rtime values are applied to the list. Any combination of rtime
469 values which produce an invalid date are ignored.
470 For example, if the rtime values refer to the '31st of each month',
472 only any dates from the list which contain months with 31 days will
473 be used. The others will be discarded.
474 Modifiers applied
476 Next, all modifiers are applied.
477 The range is tested
479 Finally, any dates that fall before or after the range are
480 discarded.
481 The resulting list of dates is returned.
483 NOTE: when the recurrence contains no interval, it is not necessary
485 to specify the range, and if it is not specified, all of the dates
486 will be returned. The range MAY be specified to return only a
487 subset of the dates if desired.
488
490 I realize that the frequency notation described above looks quite
491 complicated at first glance, but it is (IMO) the best notation for
492 expressing recurring events in existence. I actually consider it the
493 single most important contribution to date/time handling in
494 Date::Manip.
495 When I first decided to add recurring events to Date::Manip, I first
497 came up with a list of common ways of specifying recurring events, and
498 then went looking for a notation that could be used to define them.
499 After looking in several specifications (including ISO 8601) and after
501 a discussion on a mailing list of calendar related topics, it appeared
502 like there was no concise, flexible notation for handling recurring
503 events that would handle all of the common forms I'd come up with.
504 So, as a matter of necessity, I set about inventing my own notation. As
506 I was looking at my list, it struck me that all of the parts which
507 specified a frequency were higher level (i.e. referred to a larger unit
508 of time) than those parts which specified a specific value (what I've
509 called the rtime). In other words, when the terms were laid out from
510 year down to seconds, the frequency part was always left of specific
511 values.
512 That led immediately to the notation described above, so I started
514 analyzing it to figure out if it could express all of the recurring
515 events I'd come up with. It succeeded on 100% of them. Not only that,
516 but by playing with different values (especially different combinations
517 of m/w/d values), I found that it would define recurring events that I
518 hadn't even thought of, but which seemed perfectly reasonable in
519 hindsight.
520 After a very short period, I realized just how powerful this notation
522 was, and set about implementing it, and as I said above, of all the
523 contributions that Date::Manip has made, I consider this to be the most
524 important.
525
527 Because the week and day values may have multiple meanings depending on
528 where the asterisk is, and which of the fields have non-zero values, a
529 list of every possible combination is included here (though most can be
530 determined using the rules above).
531 When the asterisk occurs before the day element, and the day element is
533 non-zero, the day element can take on multiple meanings depending on
534 where the asterisk occurs, and which leading elements (year, month,
535 week) have non-zero values. It can refer to the day of the week, day of
536 the month, or day of the year.
537 When the asterisk occurs before the week element, the week element of
539 the frequency can also take on multiple meanings as well. When the
540 month field and day fields are zero, it refers to the week of the year.
541 Since the week of the year is well defined in the ISO 8601 spec, there
542 is no ambiguity.
543 When the month field is zero, but the day field is not, the week field
545 refers to the nth occurrence of the day of week referred to by the day
546 field in the year.
547 When the month field is non-zero, the week field refers to the nth
549 occurrence of the day of week in the month.
550 In the tables below only the first 4 elements of the frequency are
552 shown. The actual frequency will include the hour, minute, and second
553 elements in addition to the ones shown.
554 When all elements left of the asterisk are 0, the interval is such that
556 it occurs the maximum times possible (without changing the type of
557 elements to the right of the asterisk). Another way of looking at it is
558 that the last 0 element of the interval is changed to 1. So, the
559 interval:
560 0:0*3:0
562 is equivalent to
564 0:1*3:0
566 When the year field is zero, and is right of the asterisk, it means the
568 current year.
569 All elements left of the asterisk
571 When all of the month, week, and day elements are left of the
572 asterisk, the simple definitions of the frequency are used:
573 frequency meaning
575 1:2:3:4 every 1 year, 2 months, 3 weeks,
577 4 days
578 Any, or all of the fields can be zero.
580 Non-zero day, non-zero week
582 When both the day and week elements are non-zero, the day element
583 always refers to the day of week. Values must be in the range (1 to
584 7) and no negative values are allowed.
585 The following tables shows all possible variations of the frequency
587 where this can happen (where day 4 = Thursday).
588 When the week is left of the asterisk, the interval is used to get
590 the weeks on the calendar containing a recurring date, and the day
591 is used to set the day of the week. The following are possible:
592 frequency meaning
594 1:2:3*4 every 1 year, 2 months, 3 weeks
596 on Thur
597 1:0:3*4 every 1 year, 3 weeks on Thur
599 0:2:3*4 every 2 months, 3 weeks on Thur
601 0:0:3*4 every 3 weeks on Thur
603 The base date is necessary for all frequencies (except 0:0:1*D) to
605 get the starting week.
606 When the week is right of the asterisk, and a non-zero month is
608 left of the asterisk, the recurrence refers to a specific
609 occurrence of a day-of-week during a month. The following are
610 possible:
611 frequency meaning
613 1:2*3:4 every 1 year, 2 months on the
615 3rd Thursday of the month
616 0:2*3:4 every 2 months on the 3rd Thur
618 of the month
619 The base date is necessary for all of these (except 0:1*W:D) to get
621 the starting month.
622 When the week and month are both non-zero and right of the
624 asterisk, the recurrence refers to an occurrence of day-of-week
625 during the given month. Possibilities are:
626 frequency meaning
628 1*2:3:4 every 1 year in February on
630 the 3rd Thur
631 0*2:3:4 same as 1*2:3:4
633 *1:2:3:4 in Feb 0001 on the 3rd Thur
635 of the month
636 *0:2:3:4 on the 3rd Thur of Feb in the
638 current year
639 The base date is necessary only for Y*M:W:D where Y>1.
641 When the week is right of the asterisk, and the month is zero, the
643 recurrence refers to an occurence of the day-of-week during the
644 year. The following are possible:
645 frequency meaning
647 1:0*3:4 every 1 year on the 3rd Thursday
649 1*0:3:4 of the year
650 *1:0:3:4 in 0001 on the 3rd Thur of
652 the year
653 0*0:3:4 same as 1*0:3:4
655 *0:0:3:4 on the 3rd Thur of the current
657 year
658 The base date is only required for Y*0:W:D when Y>1 to get the
660 starting year.
661 There is one special case:
663 frequency meaning
665 0:0*3:4 same as 0:1*3:4 (every month on
667 the 3rd Thur of the month)
668 Non-zero day, non-zero month
670 When a non-zero day element occurs to the right of the asterisk and
671 the week element is zero, but the month element is non-zero, the
672 day elements always refers to a the day of month in the range (1 to
673 31) or (-1 to -31).
674 The following table shows all possible variations of the frequency
676 where this can happen:
677 frequency meaning
679 1:2:0*4 every 1 year, 2 months on the
681 1:2*0:4 4th day of the month
682 1*2:0:4 every year on Feb 4th
684 *1:2:0:4 Feb 4th, 0001
686 0:2:0*4 every 2 months on the 4th day
688 0:2*0:4 of the month
689 0*2:0:4 same as 1*2:0:4
691 *0:2:0:4 Feb 4th of the current year
693 The base date is required for all except 0:1*0:D, 1*M:0:D, and
695 *Y:M:0:D and is used to get the year and month.
696 Zero day, non-zero week
698 When a day is zero, and the week is non-zero, the recurrence refers
699 to a specific occurrence of the first day of the week (as given by
700 the FirstDay variable).
701 The frequency can refer to an occurrence of FirstDay in a specific
703 week (if the week is left of the asterisk):
704 frequency meaning
706 1:2:3*0 every 1 year, 2 months, 3 weeks on
708 FirstDay
709 1:0:3*0 every 1 year, 3 weeks on FirstDay
711 0:2:3*0 every 2 months, 3 weeks on FirstDay
713 0:0:3*0 every 3 weeks on FirstDay
715 or to a week in the year (if the week is right of the asterisk, and
717 the month is zero):
718 frequency meaning
720 1:0*3:0 every 1 year on the first day of the
722 1*0:3:0 3rd week of the year
723 *1:0:3:0 the first day of the 3rd week of 0001
725 or to an occurrence of FirstDay in a month (if the week is right of
727 the asterisk and month is non-zero):
728 frequency meaning
730 1:2*3:0 every 1 year, 2 months on the 3rd
732 occurence of FirstDay
733 0:2*3:0 every 2 months on the 3rd occurence
735 of FirstDay
736 1*2:3:0 every year on the 3rd occurence
738 of FirstDay in Feb
739 0*2:3:0 same as 1*2:3:0
741 *1:2:3:0 the 3rd occurence of FirstDay
743 Feb 0001
744 *0:2:3:0 the 3rd occurence of FirstDay
746 in Feb of the current year
747 NOTE: in the last group, a slightly more intuitive definition of
749 these would have been to say that the week field refers to the week
750 of the month, but given the ISO 8601 manner of defining when weeks
751 start, this definition would have virtually no practical
752 application. So the definition of the week field referring to the
753 Nth occurence of FirstDay in a month was used instead.
754 There are a few special cases here:
756 frequency meaning
758 0:0*3:0 same as 0:1*3:0 (every month on the 3rd
760 occurence of the first day of week)
761 0*0:3:0 same as 1*0:3:0
763 *0:0:3:0 the first day of the 3rd week of the
765 current year
766 Non-zero day
768 When a non-zero day element occurs and both the month and week
769 elements are zero, the day elements always refers to a the day of
770 year (1 to 366 or -1 to -366 to count from the end).
771 The following table shows all possible variations of the frequency
773 where this can happen:
774 frequency meaning
776 1:0:0*4 every year on the 4th day of
778 1:0*0:4 the year
779 1*0:0:4
780 *1:0:0:4 the 4th day of 0001
782 Other non-zero day variations have multiple meanings for the day
784 element:
785 frequency meaning
787 0:0:0*4 same as 0:0:1*4 (every week on Thur)
789 0:0*0:4 same as 0:1*0:4 (every month on the 4th)
791 0*0:0:4 same as 1*0:0:4
793 *0:0:0:4 the 4th day of the current year
795 All other variations
797 The remaining variations have zero values for both week and day.
798 They are:
799 frequency meaning
801 1:2:0*0 every 1 year, 2 months on the first
803 1:2*0:0 day of the month
804 1*2:0:0 every year on Feb 1
806 *1:2:0:0 Feb 1, 0001
808 1:0:0*0 every 1 year on Jan 1
810 1:0*0:0
811 1*0:0:0
812 *1:0:0:0 Jan 1, 0001
814 0:2:0*0 every 2 months on the first day of
816 0:2*0:0 the month
817 0*2:0:0 same as 1*2:0:0
819 *0:2:0:0 Feb 1 of the current year
821 0:0:0*0 same as 0:0:1*0 (every week on
823 the first day of the week)
824 0:0*0:0 same as 0:1*0:0 (every month
826 on the 1st)
827 0*0:0:0 same as 1*0:0:0
829 *0:0:0:0 Jan 1 of the current year
831
833 new
834 new_config
835 new_date
836 new_delta
837 new_recur
838 base
839 tz
840 is_date
841 is_delta
842 is_recur
843 config
844 err Please refer to the Date::Manip::Obj documentation for these
845 methods.
846 parse
848 $err = $recur->parse($string [,$modifiers] [,$base,$start,$end]);
849 This creates a new recurrence. A string containing a valid
851 frequency is required. In addition, $start, $end, and $base dates
852 can be passed in (either as Date::Manip::Date objects, or as
853 strings containing dates that can be parsed), and any number of the
854 modifiers listed above.
855 If the $start or $end dates are not included, they may be supplied
857 automatically, based on the value of the RecurRange variable. If
858 any of the dates are passed in, they must be included in the order
859 given (though it is safe to pass an empty string or undef in for
860 any of them if you only want to set some, but not all of them).
861 The $modifiers argument must either contain valid modifiers, or be
863 left out of the argument list entirely. You cannot pass an empty
864 string or undef in for it.
865 $err = $recur->parse($string);
867 This creates a recurrence from a string which contains all of the
869 necessary elements of the recurrence. The string is of the format:
870 FREQ*MODIFIERS*BASE*START*END
872 where FREQ is a string containing a frequency, MODIFIERS is a
874 string containing a comma separated list of modifiers, BASE, START,
875 and END are strings containing parseable dates.
876 All pieces are optional, but order must be maintained, so all of
878 the following are valid:
879 FREQ*MODIFIERS
881 FREQ**BASE
882 FREQ**BASE*START*END
883 frequency
885 start
886 end
887 base
888 modifiers
889 You can also create a recurrency in steps (or replace parts of an
890 existing recurrence) using the following:
891 $err = $recur->frequency($frequency);
893 $err = $recur->start($start);
895 $err = $recur->end($end);
896 $err = $recur->base($base);
898 $err = $recur->modifiers($modifiers);
900 $err = $recur->modifiers(@modifiers);
901 These set the appropriate part of the recurrence.
903 Calling the frequency method discards all information currently
905 stored in the Recur object (including an existing start, end, and
906 base date), so this method should be called first.
907 In the modifiers method, the modifiers can be passed in as a string
909 containing a comma separated list of modifiers, or as a list of
910 modifiers. The modifiers passed in override all previously set
911 modifiers UNLESS the first one is the string "+", in which case the
912 new modifiers are appended to the list.
913 In the start, end, and base methods, the date passed in can be a
915 Date::Manip::Date object, or a string that can be parsed to get a
916 date.
917 dates
919 @dates = $recur->dates([$start,$end]);
920 Returns the list of dates defined by the full recurrence. If there
922 is an error, @dates will be empty, and the error flag will be set
923 in the $recur object.
924 $start and $end are either undef, or dates which can be used to
926 limit the set of dates passed back.
927 If the recurrence does not have a start and end date already,
929 passing in $start and $end will set the range (but they will NOT be
930 stored in the recurrence).
931 If the recurrence does have a start and end date stored in it, the
933 $start and $end arguments can be used to further limit the dates
934 returned. In other words, if a recurrence has a start date of Jan
935 1, 2006 00:00:00 and and end date of Dec 31, 2006 23:59:59 stored
936 in the recurrence, passing in $start of Jul 1, 2006 00:00:00 will
937 limit the dates returned to the range of Jul 1 to Dec 31.
938 Passing in a start date of Jul 1, 2007 will mean that no dates are
940 returned since the recurrence limits the date to be in 2006.
941
943 None known.
944
946 Please refer to the Date::Manip::Problems documentation for information
947 on submitting bug reports or questions to the author.
948
950 Date::Manip - main module documentation
951
953 This script is free software; you can redistribute it and/or modify it
954 under the same terms as Perl itself.
955
957 Sullivan Beck (sbeck@cpan.org)
958perl v5.12.0 2010-04-27 Date::Manip::Recur(3)