{ "content": [ { "type": "text", "text": "# Date::Manip::Recur (perldoc)\n\n## NAME\n\nDate::Manip::Recur - methods for working with recurring events\n\n## SYNOPSIS\n\nuse Date::Manip::Recur;\n$date = new Date::Manip::Recur;\n\n## DESCRIPTION\n\nThis module contains functions useful in parsing and manipulating recurrences. A recurrence is a\nnotation for specifying when a recurring event occurs. For example, if an event occurs every\nother Friday or every 4 hours, this can be defined as a recurrence. A fully specified recurrence\nconsists of the following pieces of information:\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **FREQUENCY NOTATION**\n- **BASE DATES**\n- **INTERVAL**\n- **DATE RANGE**\n- **OTHER FREQUENCY FORMATS**\n- **MODIFIERS**\n- **DETERMINING DATES**\n- **LIST OF Y/M/W/D FREQUENCY DEFINITIONS**\n- **METHODS**\n- **HISTORY OF THE FREQUENCY NOTATION**\n- **KNOWN BUGS**\n- **BUGS AND QUESTIONS**\n- **SEE ALSO**\n- **LICENSE**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Date::Manip::Recur", "section": "", "mode": "perldoc", "summary": "Date::Manip::Recur - methods for working with recurring events", "synopsis": "use Date::Manip::Recur;\n$date = new Date::Manip::Recur;", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 3, "subsections": [] }, { "name": "DESCRIPTION", "lines": 166, "subsections": [] }, { "name": "FREQUENCY NOTATION", "lines": 152, "subsections": [] }, { "name": "BASE DATES", "lines": 39, "subsections": [] }, { "name": "INTERVAL", "lines": 18, "subsections": [] }, { "name": "DATE RANGE", "lines": 42, "subsections": [] }, { "name": "OTHER FREQUENCY FORMATS", "lines": 30, "subsections": [] }, { "name": "MODIFIERS", "lines": 80, "subsections": [] }, { "name": "DETERMINING DATES", "lines": 25, "subsections": [] }, { "name": "LIST OF Y/M/W/D FREQUENCY DEFINITIONS", "lines": 270, "subsections": [] }, { "name": "METHODS", "lines": 228, "subsections": [] }, { "name": "HISTORY OF THE FREQUENCY NOTATION", "lines": 29, "subsections": [] }, { "name": "KNOWN BUGS", "lines": 12, "subsections": [] }, { "name": "BUGS AND QUESTIONS", "lines": 3, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "LICENSE", "lines": 3, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] } ], "sections": { "NAME": { "content": "Date::Manip::Recur - methods for working with recurring events\n", "subsections": [] }, "SYNOPSIS": { "content": "use Date::Manip::Recur;\n$date = new Date::Manip::Recur;\n", "subsections": [] }, "DESCRIPTION": { "content": "This module contains functions useful in parsing and manipulating recurrences. A recurrence is a\nnotation for specifying when a recurring event occurs. For example, if an event occurs every\nother Friday or every 4 hours, this can be defined as a recurrence. A fully specified recurrence\nconsists of the following pieces of information:\n\nFrequency\nThe most basic piece of information is the frequency. For relatively simple recurring\nevents, the frequency defines when those events occur. For more complicated recurring\nevents, the frequency tells approximately when the events occur (but to get the actual\nevents, certain modifiers must be applied as described below).\n\nExamples of recurring events include:\n\nthe first of every month\nevery other day\nthe 4th Thursday of each month at 2:00 PM\nevery 2 hours and 30 minutes\n\nAll of these can be expressed as a frequency.\n\nNOTE: unlike date parsing, support for frequencies written out in English (or whatever\nlanguage you are working in) is extremely limited. For example, the string \"the first of\nevery month\" will NOT be parsed as a valid frequency. A limited number of frequencies can be\nexpressed in a written out form (see the . In this\ndocument however, the written out form will often be used for the sake of clarity.\n\nSince a frequency typically refers to events that could happen an infinite number of times,\nyou usually have to specify a date range to get the actual dates. Some frequencies also\nrequire a base date (i.e. information about when one such even actually occurred) since the\nfrequency is otherwise ambiguous. For example, the frequency 'every other day' does not\ninclude enough information to specify the dates that the event happened on, so you have to\nexplicitly define one of them. Then all others can be derived.\n\nModifier\nComplex recurring events may require the use of modifiers in order to get them correct.\n\nFor example, in America, many places treat both Thanksgiving and the day after as holidays.\nThanksgiving is easy to define since it is defined as:\n\n4th Thursday of every November\n\nIn the frequency notation (described below), this would be written as:\n\n1*11:4:5:0:0:0\n\nThe day after Thanksgiving is NOT possible to define in the same way. Depending on the year,\nthe day after the 4th Thursday may be the 4th or 5th Friday.\n\nThe only way to accurately define the day after Thanksgiving is to specify a frequency and a\nmodifier:\n\n4th Thursday of every November\n+1 day\n\nIn frequency notation, this can be expressed as:\n\n1*11:4:5:0:0:0*FD1\n\nThe syntax for the various modifiers is described below in the \"MODIFIERS\" section.\n\nBase date\nMany recurrences have a base date which is a date on which a recurring event is based.\n\nThe base date is not necessarily a date where the recurring event occurs. Instead, it may be\nmodified (with modifiers, or with values specified in the recurrence) to actually produce a\nrecurring event.\n\nFor example, if the frequency is\n\nevery other Friday at noon\n\nthe base date will be a Friday and the recurring event will happen on that Friday, Friday\ntwo weeks later, Friday four weeks later, etc. In all cases, the dates will be modified to\nbe at noon.\n\nIf the frequency has a modifier, such as:\n\nevery other Friday\n+ 1 day\n\n(and yes, this trivial example could be expressed as the frequency 'every other Saturday'\nwith no modifiers), then the base date is still on a Friday, but the actual recurring event\nis determined by applying modifiers and occurs on Saturday.\n\nRecurring events are assigned a number with the event that is referred to by the base date\nbeing the 0th occurrence, the first one after that as the 1st occurrence, etc. Recurring\nevents can also occur before the base date with the last time the recurring event occurred\nbefore the base date is the -1th occurrence.\n\nSo, if the frequency is\n\nthe first of every month\n\nand the base date is 'Mar 1, 2000', then the 5 recurring events around it are:\n\nN Date\n\n-2 Jan 1 2000\n-1 Feb 1 2000\n0 Mar 1 2000\n+1 Apr 1 2000\n+2 May 1 2000\n\nIn some cases, the Nth date may not be defined. For example, if the frequency is:\n\nthe 31st of every month\n\nand the base date is Mar 31, 2000, the 5 recurring events around it are:\n\nN Date\n\n-2 Jan 31 2000\n-1 undefined\n0 Mar 31 2000\n1 undefined\n2 May 31 2000\n\nAs mentioned above, the base date is used to determine one of the occurrences of the\nrecurring event... but it may not actually be on of those events.\n\nAs an example, for the recurring event:\n\nevery other Friday\n\na base date could be on a Friday, but it would also be possible to have a base date on some\nother day of the week, and it could unambiguously refer simply to a week, and the recurring\nevent would occur on Friday of that week.\n\nIn most cases, it won't be necessary to treat base dates with that level of complexity, but\nwith complicated recurring events, it may be necessary. More information on how Date::Manip\ndetermines a recurring event from a base date is given below in the section \"BASE DATES\".\n\nRange\nA date range is simply a starting and an ending date. When a range is used (primarily in the\ndates method as described below), only recurring events (with all modifiers applied) which\nhappened on or after the start date and on or before the end date are used.\n\nFor example, if the frequency was\n\nthe first of every month\n\nand the start/end dates were Jan 1 2000 and May 31 2000, the list of dates referred to would\nbe:\n\nJan 1 2000\nFeb 1 2000\nMar 1 2000\nApr 1 2000\nMay 1 2000\n\nIf no base date is specified, but a date range is specified, the start date is used as the\nspecified base date.\n\nIt should be noted that if both the range and base date are specified, the range is not used\nto determine a base date. Also, the first time the recurring event occurs in this range may\nNOT be the 0th occurrence with respect to the base date, and that is allowed.\n\nNOTE: both dates in the range and the base date must all be in the same time zone, and use\nthe same Date::Manip::Base object.\n\nAn alternate definition of the range may also be used to specify that the recurring events\nbased only on the interval and BEFORE any modifiers are applied fall in the range.\n\nThis definition is described in more detail below.\n", "subsections": [] }, "FREQUENCY NOTATION": { "content": "The syntax for specifying a frequency requires some explanation. It is very concise, but\ncontains the flexibility to express every single type of recurring event I could think of.\n\nThe syntax of the frequency description is a colon separated list of the format Y:M:W:D:H:MN:S\n(which stand for year, month, week, etc.). One (and only one) of the colons may optionally be\nreplaced by an asterisk, or an asterisk may be prepended to the string. For example, the\nfollowing are all valid frequency descriptions:\n\n1:2:3:4:5:6:7\n1:2*3:4:5:6:7\n*1:2:3:4:5:6:7\n\nBut the following are NOT valid because they contain more than one asterisk:\n\n1:2*3:4:5*6:7\n*1:2:3:4:5:6*7\n\nWhen an asterisk is included, the portion to the left of it is called the interval, and refers\nto an approximate time interval between recurring events. For example, if the interval of the\nfrequency is:\n\n1:2*\n\nit means that the recurring event occurs approximately every 1 year and 2 months. The interval\nis approximate because elements to the right of the asterisk, as well as any modifiers included\nin the recurrence, will affect when the events actually occur.\n\nIf no asterisks are included, then the entire recurrence is an interval. For example,\n\n0:0:0:1:12:0:0\n\nrefers to an event that occurs every 1 day, 12 hours.\n\nThe format of the interval is very simple. It is colon separated digits only. No other\ncharacters are allowed.\n\nThe portion of the frequency that occur after an asterisk is called the recurrence time (or\nrtime), and refers to a specific value (or values) for that type of time element (i.e. exactly\nas it would appear on a calendar or a clock). For example, if the frequency ends with the rtime:\n\n*12:0:0\n\nthen the recurring event occurs at 12:00:00 (noon).\n\nFor example:\n\n0:0:0:2*12:30:0 every 2 days at 12:30 (each day)\n\nElements in the rtime can be listed as single values, ranges (2 numbers separated by a dash\n\"-\"), or a comma separated list of values or ranges. In some cases, negative values are\nappropriate for the week or day values. -1 stands for the last possible value, -2 for the second\nto the last, etc.\n\nIf multiple values are included in more than one field in the rtime, every possible combination\nwill be used. For example, if the frequency ends with the rtime:\n\n*12-13:0,30:0\n\nthe event will occur at 12:00, 12:30, 13:00, and 13:30.\n\nSome examples are:\n\n0:0:0:1*2,4,6:0:0 every day at at 02:00, 04:00, and 06:00\n0:0:0:2*12-13:0,30:0 every other day at 12:00, 12:30, 13:00,\nand 13:30\n0:1:0*-1:0:0:0 the last day of every month\n*1990-1995:12:0:1:0:0:0\nDec 1 in 1990 through 1995\n\nThere is no way to express the following with a single recurrence:\n\nevery day at 12:30 and 1:00\n\nYou have to use two recurrences to do this.\n\nYou can include negative numbers in ranges. For example, including the range -2--1 means to go\nfrom the 2nd to the last to the last occurrence. Negative values are only supported in the week\nand day fields, and only in some cases.\n\nYou can even use a range like 2--2 (which means to go from the 2nd to the 2nd to the last\noccurrence). However, this is STRONGLY discouraged since this leads to a date which produces a\nvariable number of events. As a result, the only way to determine the Nth date is to calculate\nevery date starting at the base date. If you know that every date produces exactly 4 recurring\nevents, you can calculate the Nth date without needing to determine every intermediate date.\n\nWhen specifying a range, the first value must be less than the second or else nothing will be\nreturned.\n\nWhen both the week and day elements are non-zero and the day is right of the asterisk, the day\nrefers to the day of week. The following examples illustrate these type of frequencies:\n\n0:1*4:2:0:0:0 4th Tuesday (day 2) of every month\n0:1*-1:2:0:0:0 last Tuesday of every month\n0:0:3*2:0:0:0 every 3rd Tuesday (every 3 weeks\non 2nd day of week)\n1:0*12:2:0:0:0 the 12th Tuesday of each year\n\nNOTE: The day of week refers to the numeric value of each day as specified by ISO 8601. In other\nwords, day 1 is ALWAYS Monday, day 7 is ALWAYS Sunday, etc., regardless of what day of the week\nthe week is defined to begin on (using the FirstDay config variable). So when the day field\nrefers to the day of week, it's value (or values if a range or comma separated list are used)\nmust be 1-7.\n\nWhen the week element is zero and the month element is non-zero and the day element is right of\nthe asterisk, the day value is the day of the month (it can be from 1 to 31 or -1 to -31\ncounting from the end of the month).\n\n3*1:0:2:12:0:0 every 3 years on Jan 2 at noon\n0:1*0:2:12,14:0:0 2nd of every month at 12:00 and 14:00\n0:1:0*-2:0:0:0 2nd to last day of every month\n\nNOTE: If the day given refers to the 29th, 30th, or 31st, in a month that does not have that\nnumber of days, it is ignored. For example, if you ask for the 31st of every month, it will\nreturn dates in Jan, Mar, May, Jul, etc. Months with fewer than 31 days will be ignored.\n\nIf both the month and week elements are zero, and the year element is non-zero, the day value is\nthe day of the year (1 to 365 or 366 -- or the negative numbers to count backwards from the end\nof the year).\n\n1:0:0*45:0:0:0 45th day of every year\n\nSpecifying a day that doesn't occur in that year silently ignores that year. The only result of\nthis is that specifying +366 or -366 will ignore all years except leap years.\n\nIf the week element is non-zero and to the right of the asterisk, and the day element is zero,\nthe frequency refers to the first day of the given week of the month or week of the year:\n\n0:1*2:0:0:0:0 the first day of the 2nd week of\nevery month\n1:0*2:0:0:0:0 the first day of the 2nd week of\nevery year\n\nAlthough the meaning of almost every recurrence can be deduced by the above rules, a set of\ntables describing every possible combination of Y/M/W/D meanings, and giving an example of each\nis included below in the section \"LIST OF Y/M/W/D FREQUENCY DEFINITIONS\". It also explains a\nsmall number of special cases.\n\nNOTE: If all fields left of the asterisk are zero, the last one is implied to be 1. In other\nwords, the following are equivalent:\n\n0:0:0*x:x:x:x\n0:0:1*x:x:x:x\n\nand can be thought of as every possible occurrence of the rtime.\n\nNOTE: When applying a frequency to get a list of dates on which a recurring event occurs, a\ndelta is created from the frequency which is applied to get dates referred to by the interval.\nThese are then operated on by the rtime and by modifiers to actually get the recurring events.\nThe deltas will always be exact or approximate. There is no support for business mode\nrecurrences. However, with the careful use of modifiers (discussed below), most recurring\nbusiness events can be determined too.\n", "subsections": [] }, "BASE DATES": { "content": "A recurrence of the form *Y:M:W:D:H:MN:S (which is technically speaking not a recurring event...\nit is just a date or dates specified using the frequency syntax) uses the first date which\nmatches the frequency as the base date. Any base date specified will be completely ignored. A\ndate range may be specified to work with a subset of the dates.\n\nAll other recurrences use a specified base date in order to determine when the 0th occurrence of\na recurring event happens. As mentioned above, the specified base date may be determined from\nthe start date, or specified explicitly.\n\nThe specified base date is used to provide the bare minimum information. For example, the\nrecurrence:\n\n0:0:3*4:0:0:0 every 3 weeks on Thursday\n\nrequires a base date to determine the week, but nothing else. Using the standard definition\n(Monday-Sunday) for a week, and given that one week in August 2009 is Aug 10 to Aug 16, any date\nin the range Aug 10 to Aug 16 will give the same results. The definition of the week defaults to\nMonday-Sunday, but may be modified using the FirstDay config variable.\n\nLikewise, the recurrence:\n\n1:3*0:4:0:0:0 every 1 year, 3 months on the 4th\nday of the month\n\nwould only use the year and month of the base date, so all dates in a given month would give the\nsame set of recurring dates.\n\nIt should also be noted that a date may actually produce multiple recurring events. For example,\nthe recurrence:\n\n0:0:2*4:12,14:0:0 every 2 weeks on Thursday at 12:00\nand 14:00\n\nproduces 2 events for every date. So in this case, the base date produces the 0th and 1st event,\nthe base date + an offset produces the 2nd and 3rd events, etc.\n\nIt must be noted that the base date refers ONLY to the interval part of the recurrence. The\nrtime and modifiers are NOT used in determining the base date.\n", "subsections": [] }, "INTERVAL": { "content": "The interval of a frequency (everything left of the asterisk) will be used to generate a list of\ndates (called interval dates). When rtime values and modifiers are applied to an interval date,\nit produces the actual recurring events.\n\nAs already noted, if the rtime values include multiple values for any field, more than one event\nare produced by a single interval date.\n\nIt is important to understand is how the interval dates are calculated. The interval is\ntrivially turned into a delta. For example, with the frequency 0:0:2*4:12:0:0, the interval is\n0:0:2 which produces the delta 0:0:2:0:0:0:0.\n\nIn order to get the Nth interval date, the delta is multiplied by N and added to the base date.\nIn other words:\n\nD(0) = Jan 31\nD(1) = Jan 31 + 1 month = Feb 28\nD(2) = Jan 31 + 2 month = Mar 31\n", "subsections": [] }, "DATE RANGE": { "content": "The start and end dates form the range in which recurring events can fall into.\n\nEvery recurring date will fall in the limit:\n\nstart <= date <= end\n\nWhen a recurrence is created, it may include a default range, and this is handled by the\nRecurRange config variable.\n\nBy default, the date range applies to the final dates once all modifiers have been applied.\n\nThis behavior can be changed by applying the range to the unmodified dates.\n\nAn example of how this applies might be in defining New Year's Day (observed). The most useful\ndefinition of this would be:\n\n1*1:0:1:0:0:0*DWD\n\nwhich means Jan 1 modified to the nearest working day.\n\nBut if you wanted to find New Year's for 2005 using this definition by passing in a start date\nof 2005-01-01-00:00:00 and an end date of 2005-12-31-23:59:59, you won't find anything because\nNew Year's day will actually be observed on 2004-12-31 (since Jan 1 is a Saturday).\n\nTo get around this, you can pass in a non-zero parameter with the recurrence which means that\nthis range will be applied to the unmodified dates.\n\nIn effect, this discards the modifier (DWD), gets the dates that fall in the range, and for all\nthat fall in the range, the modifiers are applied.\n\nSo:\n\n1*1:0:1:0:0:0*DWD2005-01-01-00:00:00*2005-12-31-23:59:59\n\nwill return no dates, but:\n\n1*1:0:1:0:0:0*DWD2005-01-01-00:00:00*2005-12-31-23:59:59*1\n\nwill return:\n\n2004-12-31-00:00:00\n", "subsections": [] }, "OTHER FREQUENCY FORMATS": { "content": "There are a small handful of English strings (or the equivalent in other languages) which can be\nparsed in place of a numerical frequency. These include:\n\nevery Tuesday in June [1997]\n2nd Tuesday in June [1997]\nlast Tuesday in June [1997]\n\nevery Tuesday of every month [in 1997]\n2nd Tuesday of every month [in 1997]\nlast Tuesday of every month [in 1997]\n\nevery day of every month [in 1997]\n2nd day of every month [in 1997]\nlast day of every month [in 1997]\n\nevery day [in 1997]\nevery 2nd day [in 1977]\nevery 2 days [in 1977]\n\nEach of these set the frequency. If the year is include in the string, it also sets the dates in\nthe range to be the first and last day of the year.\n\nIn each of these, the numerical part (i.e. 2nd in all of the examples above) can be any number\nfrom 1 to 31. To make a frequency with a larger number than that, you have to use the standard\nformat discussed above.\n\nDue to the complexity of writing out (and parsing) frequencies written out, I do not intend to\nadd additional frequency formats, and the use of these is discouraged. The frequency format\ndescribed above is preferred.\n", "subsections": [] }, "MODIFIERS": { "content": "Any number of modifiers may be added to a frequency to get the actual date of a recurring event.\nModifiers are case sensitive.\n\nModifiers to set the day-of-week\nThe following modifiers can be used to adjust a date to a specific day of the week.\n\nPDn Means the previous day n not counting today\nPTn Means the previous day n counting today\nNDn Means the next day n not counting today\nNTn Means the next day n counting today\nWDn Day n (1-7) of the current week\n\nIn each of these, 'n' is 1-7 (1 being Sunday, 7 being Saturday).\n\nFor example, PD2/ND2 returns the previous/next Tuesday. If the date that this is applied to\nis Tuesday, it modifies it to one week in the past/future.\n\nPT2/NT2 are similar, but will leave the date unmodified if it is a Tuesday.\n\nModifiers to move forward/backward a number of days\nThese modifiers can be used to add/subtract n days to a date.\n\nFDn Means step forward n days.\nBDn Means step backward n days.\n\nModifiers to force events to be on business days\nModifiers can also be used to force recurring events to occur on business days. These\nmodifiers include:\n\nFWn Means step forward n workdays.\nBWn Means step backward n workdays.\n\nCWD The closest work day (using the TomorrowFirst\nconfig variable).\nCWN The closest work day (looking forward first).\nCWP The closest work day (looking backward first).\n\nNWD The next work day counting today\nPWD The previous work day counting today\nDWD The closest work day (using the TomorrowFirst config\nvariable) counting today\n\nIBD This discards the date if it is not a business day.\nNBD This discards the date if it IS a business day.\n\nIWn This discards the date if it is not the n'th day\nof the week (n=1-7, 1 is Monday)\nNWn This discards the date if it IS the n'th day of the week\n\nThe CWD, CWN, and CWP modifiers will always change the date to the closest working day NOT\ncounting the current date.\n\nThe NWD, PWD, and DWD modifiers always change the date to the closest working day unless the\ncurrent date is a work day. In that case, it is left unmodified.\n\nCWD, CWN, and CWP will usually return the same value, but if you are starting at the middle\nday of a 3-day weekend (for example), it will return either the first work day of the\nfollowing week, or the last work day of the previous week depending on whether it looks\nforward or backward first.\n\nAll business day modifiers ignore the time, so if a date is initially calculated at Saturday\nat noon, and the FW1 is applied, the date is initially moved to the following Monday\n(assuming it is a work day) and the FW1 moves it to Tuesday. The final result will be\nTuesday at noon.\n\nThe IBD, NBD, IWn, and NWn modifiers eliminate dates from the list immediately. In other\nwords, if a recurrence has three modifiers:\n\nFD1,IBD,FD1\n\nthen as a date is being tested, first the FD1 modifier is applied. Then, it is tested to see\nif it is a business day. If it is, the second FD1 modifier will be applied. Otherwise, the\ndate will not be included in the list of recurring events.\n\nSpecial modifiers\nThe following modifiers do things that cannot be expressed using any other combination of\nfrequency and modifiers:\n\nEASTER Set the date to Easter for this year.\n", "subsections": [] }, "DETERMINING DATES": { "content": "In order to get a list of dates referred to by the recurrence, the following steps are taken.\n\nThe recurrence is tested for errors\nThe recurrence must be completely specified with a base date (either supplied explicitly, or\nderived from a start date) and date range when necessary. All dates must be valid.\n\nThe actual base date is determined\nUsing information from the interval and the specified base date, the actual base date is\ndetermined.\n\nThe Nth date is calculated\nBy applying the delta that corresponds to the interval, and then applying rtime and modifier\ninformation, the Nth date is determined.\n\nThis is repeated until all desired dates have been obtained.\n\nThe nth method described below has more details.\n\nThe range is tested\nAny date that fall outside the range is discarded.\n\nNOTE: when the recurrence contains no interval, it is not necessary to specify the range,\nand if it is not specified, all of the dates are used. The range MAY be specified to return\nonly a subset of the dates if desired.\n", "subsections": [] }, "LIST OF Y/M/W/D FREQUENCY DEFINITIONS": { "content": "Because the week and day values may have multiple meanings depending on where the asterisk is,\nand which of the fields have non-zero values, a list of every possible combination is included\nhere (though most can be determined using the rules above).\n\nWhen the asterisk occurs before the day element, and the day element is non-zero, the day\nelement can take on multiple meanings depending on where the asterisk occurs, and which leading\nelements (year, month, week) have non-zero values. It can refer to the day of the week, day of\nthe month, or day of the year.\n\nWhen the asterisk occurs before the week element, the week element of the frequency can also\ntake on multiple meanings as well. When the month field and day fields are zero, it refers to\nthe week of the year. Since the week of the year is well defined in the ISO 8601 spec, there is\nno ambiguity.\n\nWhen the month field is zero, but the day field is not, the week field refers to the nth\noccurrence of the day of week referred to by the day field in the year.\n\nWhen the month field is non-zero, the week field refers to the nth occurrence of the day of week\nin the month.\n\nIn the tables below only the first 4 elements of the frequency are shown. The actual frequency\nwill include the hour, minute, and second elements in addition to the ones shown.\n\nWhen all elements left of the asterisk are 0, the interval is such that it occurs the maximum\ntimes possible (without changing the type of elements to the right of the asterisk). Another way\nof looking at it is that the last 0 element of the interval is changed to 1. So, the interval:\n\n0:0*3:0\n\nis equivalent to\n\n0:1*3:0\n\nWhen the year field is zero, and is right of the asterisk, it means the current year.\n\nAll elements left of the asterisk\nWhen all of the month, week, and day elements are left of the asterisk, the simple\ndefinitions of the frequency are used:\n\nfrequency meaning\n\n1:2:3:4 every 1 year, 2 months, 3 weeks,\n4 days\n\nAny, or all of the fields can be zero.\n\nNon-zero day, non-zero week\nWhen both the day and week elements are non-zero, the day element always refers to the day\nof week. Values must be in the range (1 to 7) and no negative values are allowed.\n\nThe following tables shows all possible variations of the frequency where this can happen\n(where day 4 = Thursday).\n\nWhen the week is left of the asterisk, the interval is used to get the weeks on the calendar\ncontaining a recurring date, and the day is used to set the day of the week. The following\nare possible:\n\nfrequency meaning\n\n1:2:3*4 every 1 year, 2 months, 3 weeks\non Thur\n\n1:0:3*4 every 1 year, 3 weeks on Thur\n\n0:2:3*4 every 2 months, 3 weeks on Thur\n\n0:0:3*4 every 3 weeks on Thur\n\nWhen the week is right of the asterisk, and a non-zero month is left of the asterisk, the\nrecurrence refers to a specific occurrence of a day-of-week during a month. The following\nare possible:\n\nfrequency meaning\n\n1:2*3:4 every 1 year, 2 months on the\n3rd Thursday of the month\n\n0:2*3:4 every 2 months on the 3rd Thur\nof the month\n\nWhen the week and month are both non-zero and right of the asterisk, the recurrence refers\nto an occurrence of day-of-week during the given month. Possibilities are:\n\nfrequency meaning\n\n1*2:3:4 every 1 year in February on\nthe 3rd Thur\n\n0*2:3:4 same as 1*2:3:4\n\n*1:2:3:4 in Feb 0001 on the 3rd Thur\nof the month\n\n*0:2:3:4 on the 3rd Thur of Feb in the\ncurrent year\n\nWhen the week is right of the asterisk, and the month is zero, the recurrence refers to an\noccurrence of the day-of-week during the year. The following are possible:\n\nfrequency meaning\n\n1:0*3:4 every 1 year on the 3rd Thursday\n1*0:3:4 of the year\n\n*1:0:3:4 in 0001 on the 3rd Thur of\nthe year\n\n0*0:3:4 same as 1*0:3:4\n\n*0:0:3:4 on the 3rd Thur of the current\nyear\n\nThere is one special case:\n\nfrequency meaning\n\n0:0*3:4 same as 0:1*3:4 (every month on\nthe 3rd Thur of the month)\n\nNon-zero day, non-zero month\nWhen a non-zero day element occurs to the right of the asterisk and the week element is\nzero, but the month element is non-zero, the day elements always refers to a the day of\nmonth in the range (1 to 31) or (-1 to -31).\n\nThe following table shows all possible variations of the frequency where this can happen:\n\nfrequency meaning\n\n1:2:0*4 every 1 year, 2 months on the\n1:2*0:4 4th day of the month\n\n1*2:0:4 every year on Feb 4th\n\n*1:2:0:4 Feb 4th, 0001\n\n0:2:0*4 every 2 months on the 4th day\n0:2*0:4 of the month\n\n0*2:0:4 same as 1*2:0:4\n\n*0:2:0:4 Feb 4th of the current year\n\nZero day, non-zero week\nWhen a day is zero, and the week is non-zero, the recurrence refers to a specific occurrence\nof the first day of the week (as given by the FirstDay variable).\n\nThe frequency can refer to an occurrence of FirstDay in a specific week (if the week is left\nof the asterisk):\n\nfrequency meaning\n\n1:2:3*0 every 1 year, 2 months, 3 weeks on\nFirstDay\n\n1:0:3*0 every 1 year, 3 weeks on FirstDay\n\n0:2:3*0 every 2 months, 3 weeks on FirstDay\n\n0:0:3*0 every 3 weeks on FirstDay\n\nor to a week in the year (if the week is right of the asterisk, and the month is zero):\n\nfrequency meaning\n\n1:0*3:0 every 1 year on the first day of the\n1*0:3:0 3rd week of the year\n\n*1:0:3:0 the first day of the 3rd week of 0001\n\nor to an occurrence of FirstDay in a month (if the week is right of the asterisk and month\nis non-zero):\n\nfrequency meaning\n\n1:2*3:0 every 1 year, 2 months on the 3rd\noccurrence of FirstDay\n\n0:2*3:0 every 2 months on the 3rd occurrence\nof FirstDay\n\n1*2:3:0 every year on the 3rd occurrence\nof FirstDay in Feb\n\n0*2:3:0 same as 1*2:3:0\n\n*1:2:3:0 the 3rd occurrence of FirstDay\nFeb 0001\n\n*0:2:3:0 the 3rd occurrence of FirstDay\nin Feb of the current year\n\nNOTE: in the last group, a slightly more intuitive definition of these would have been to\nsay that the week field refers to the week of the month, but given the ISO 8601 manner of\ndefining when weeks start, this definition would have virtually no practical application. So\nthe definition of the week field referring to the Nth occurrence of FirstDay in a month was\nused instead.\n\nThere are a few special cases here:\n\nfrequency meaning\n\n0:0*3:0 same as 0:1*3:0 (every month on the 3rd\noccurrence of the first day of week)\n\n0*0:3:0 same as 1*0:3:0\n\n*0:0:3:0 the first day of the 3rd week of the\ncurrent year\n\nNon-zero day\nWhen a non-zero day element occurs and both the month and week elements are zero, the day\nelements always refers to a the day of year (1 to 366 or -1 to -366 to count from the end).\n\nThe following table shows all possible variations of the frequency where this can happen:\n\nfrequency meaning\n\n1:0:0*4 every year on the 4th day of\n1:0*0:4 the year\n1*0:0:4\n\n*1:0:0:4 the 4th day of 0001\n\nOther non-zero day variations have multiple meanings for the day element:\n\nfrequency meaning\n\n0:0:0*4 same as 0:0:1*4 (every week on Thur)\n\n0:0*0:4 same as 0:1*0:4 (every month on the 4th)\n\n0*0:0:4 same as 1*0:0:4\n\n*0:0:0:4 the 4th day of the current year\n\nAll other variations\nThe remaining variations have zero values for both week and day. They are:\n\nfrequency meaning\n\n1:2:0*0 every 1 year, 2 months on the first\n1:2*0:0 day of the month\n\n1*2:0:0 every year on Feb 1\n\n*1:2:0:0 Feb 1, 0001\n\n1:0:0*0 every 1 year on Jan 1\n1:0*0:0\n1*0:0:0\n\n*1:0:0:0 Jan 1, 0001\n\n0:2:0*0 every 2 months on the first day of\n0:2*0:0 the month\n\n0*2:0:0 same as 1*2:0:0\n\n*0:2:0:0 Feb 1 of the current year\n\n0:0:0*0 same as 0:0:1*0 (every week on\nthe first day of the week)\n\n0:0*0:0 same as 0:1*0:0 (every month\non the 1st)\n\n0*0:0:0 same as 1*0:0:0\n\n*0:0:0:0 Jan 1 of the current year\n", "subsections": [] }, "METHODS": { "content": "new\nnewconfig\nnewdate\nnewdelta\nnewrecur\nbase\ntz\nisdate\nisdelta\nisrecur\nconfig\nerr Please refer to the Date::Manip::Obj documentation for these methods.\n\nparse\n$err = $recur->parse($string [,$modifiers] [,$base,$start,$end,$unmod]);\n\nThis creates a new recurrence. A string containing a valid frequency is required. In\naddition, $start, $end, and $base dates can be passed in (either as Date::Manip::Date\nobjects, or as strings containing dates that can be parsed), and any number of the modifiers\nlisted above.\n\nIf the $start or $end dates are not included, they may be supplied automatically, based on\nthe value of the RecurRange variable. If any of the dates are passed in, they must be\nincluded in the order given (though it is safe to pass an empty string or undef in for any\nof them if you only want to set some, but not all of them). If $unmod is true, the range\nwill apply to unmodified dates rather than the modified dates.\n\nThe $modifiers argument must contain valid modifiers, or be left out of the argument list\nentirely. You cannot pass an empty string or undef in for it.\n\n$err = $recur->parse($string);\n\nThis creates a recurrence from a string which contains all of the necessary elements of the\nrecurrence. The string is of the format:\n\nFREQ*MODIFIERS*BASE*START*END*UNMOD\n\nwhere FREQ is a string containing a frequency, MODIFIERS is a string containing a comma\nseparated list of modifiers, BASE, START, and END are strings containing parseable dates.\n\nAll pieces are optional, but order must be maintained, so all of the following are valid:\n\nFREQ*MODIFIERS\nFREQBASE\nFREQBASE*START*END\nFREQ*START*END*UNMOD\n\nIf a part of the recurrence is passed in both as part of $string and as an argument, the\nargument overrides the string portion, with the possible exception of modifiers. The\nmodifiers in the argument override the string version unless the first one is a '+' in which\ncase they are appended. See the modifiers method below for more information.\n\nfrequency\nstart\nend\nbasedate\nmodifiers\nYou can also create a recurrency in steps (or replace parts of an existing recurrence) using\nthe following:\n\n$err = $recur->frequency($frequency);\n\n$err = $recur->start($start);\n$err = $recur->start($start,$unmod);\n$err = $recur->end($end);\n\n$err = $recur->basedate($base);\n\n$err = $recur->modifiers($modifiers);\n$err = $recur->modifiers(@modifiers);\n\nThese set the appropriate part of the recurrence.\n\nCalling the frequency method discards all information currently stored in the Recur object\n(including an existing start, end, and base date), so this method should be called first.\n\nIn the modifiers method, the modifiers can be passed in as a string containing a comma\nseparated list of modifiers, or as a list of modifiers. The modifiers passed in override all\npreviously set modifiers UNLESS the first one is the string \"+\", in which case the new\nmodifiers are appended to the list.\n\nIn the start, end, and base methods, the date passed in can be a Date::Manip::Date object,\nor a string that can be parsed to get a date. If $unmod is true, it will mean that the range\nwill apply to unmodified dates.\n\nNOTE: the parse method will overwrite all parts of the recurrence, so it is not appropriate\nto do:\n\n$recur->modifiers($modifiers);\n$recur->parse($string);\n\nThe modifiers passed in in the first call will be overwritten.\n\nThese functions can also be used to look up the values.\n\n$freq = $recur->frequency();\n$start = $recur->start();\n$end = $recur->end();\n@mods = $recur->modifiers();\n\n($base,$actual) = $recur->basedate();\n\nThe basedate function will return both the specified base and the actual base dates.\n\nIf any of the values are not yet determined, nothing will be returned.\n\ndates\n@dates = $recur->dates([$start,$end,$unmod]);\n\nReturns the list of dates defined by the full recurrence. If there is an error, or if there\nare no dates, an empty list will be returned.\n\n$start and $end are either \"undef,\" or dates which can be used to limit the set of dates\npassed back (they can be Date::Manip::Date objects or strings that can be parsed).\n\nIf the recurrence does not have a start and end date already, passing in $start and $end\nwill set the range (but they will NOT be stored in the recurrence).\n\nIf the recurrence does have a start and end date stored in it, the $start and $end arguments\ncan be used to temporarily override the limits. For example, if a recurrence has a start\ndate of Jan 1, 2006 00:00:00 and and end date of Dec 31, 2006 23:59:59 stored in the\nrecurrence, passing in $start of Jul 1, 2006 00:00:00 will limit the dates returned to the\nrange of Jul 1 to Dec 31.\n\nPassing in a start date of Jul 1, 2007 will mean that no dates are returned since the\nrecurrence limits the date to be in 2006.\n\nIf one or both of $start and $end are \"undef\", then the stored values will be used.\n\nnth\n($date,$err) = $recur->nth($n);\n\nThis returns the $nth recurring event ($n may be any integer). If an error occurs, it is\nreturned (but it is not set in $recur since it may be properly, though perhaps incompletely,\ndefined). The following errors may be returned:\n\nInvalid recurrence\nThe recurrence has an error flag set.\n\nIncomplete recurrence\nThe recurrence is incomplete. It needs either a\nbase date or a date range.\n\nRange invalid\nThe recurrence has an invalid date range (i.e.\nthe end date occurs before the start date).\n\nStart invalid\nEnd invalid\nBase invalid\nAn invalid date was entered for one of the dates.\n\nNot found\nIn some cases, a recurrence may appear valid, but\ndoes not refer to any actual occurrences. If no\ndates are found within a certain number of attempts\n(given by the MaxRecurAttempts config variable), this\nerror is returned.\n\nThere are a few special circumstances to be aware of.\n\n1) If the recurrence contains no interval (i.e. is of the form *Y:M:W:D:H:MN:S), the dates\ncome directly from the rtime values. In this case, the 0th event is the first date in the\nlist of dates specified by the rtime. As such, $n must be a positive integer. If $n is\nnegative, or outside the range of dates specified, the returned date will be \"undef\" (but\nthis is not an error).\n\n2) A very small number of recurrences have an unknown number of recurring events associated\nwith each date. This only happens if one of the values in the rtime is specified as a range\nincluding both a positive and negative index. For example, if the day field in an rtime\nrefers to the day of month, and is 15--15 (i.e. the 15th day to the 15th to the last day),\nthis may include 3 events (on a month with 31 days), 2 event (months with 30 days), 1 event\n(months with 29 days), or 0 events (months with 28 days). As such, in order to calculate the\nNth date, you have to start with the 0th (i.e. base) date and calculate every event until\nyou get the Nth one. For this reason, it is highly recommended that this type of frequency\nbe avoided as it will be quite slow.\n\n3) Most recurrences have a known number of events (equal to the number of combinations of\nvalues in the rtime) for each date. For these, calculating the Nth date is much faster.\nHowever, in this case, some of them may refer to an invalid date. For example, if the\nfrequency is 'the 31st of every month' and the base (0th) date is Jan 31, the 1st event\nwould refer to Feb 31. Since that isn't valid, \"undef\" would be returned for \"$n=1.\"\nObviously, it would be possible to actually determine the Nth valid event by calculating all\nN-1 dates, but in the interest of performance, this is not done.\n\n4) The way the Nth recurring event is calculated differs slightly for NE>0 and N<0 if the\ndelta referred to by the frequency is approximate. To calculate the Nth recurring event\n(where N>0), you take the base date and add N*DELTA (where DELTA is the delta determined by\nthe frequency). To get the Nth recurring event (where N<0), a date is determine which, if\nN*DELTA were added to it, would produce the base date. For more details, refer to the\nDate::Manip::Calc document. In the \"SUBTRACTION\" in Date::Manip::Calc section in the\ndiscussion of approximate date-delta calculations, calculations are done with $subtract = 2.\n\nnext\nprev\n($date,$err) = $recur->next();\n($date,$err) = $recur->prev();\n\nThese return the next/previous recurring event.\n\nThe first time next/prev is called, one of the recurring events will be selected and\nreturned (using the rules discussed below). Subsequent calls to next/prev will return the\nnext or previous event.\n\nUnlike the nth method which will return a specific event (or undef if the Nth even is not\ndefined), the next and prev methods will only work with defined events.\n\nSo, for the recurrence:\n\nthe 31st of every month\n\nnext might return the following sequence of events:\n\nJan 31 2000\nMar 31 2000\nMay 31 2000\n\nThe rules for determining what event to return the first time one of these is called are as\nfollows:\n\n1) If there is a range, next will return the first event that occurs after the start of the\nrange. prev will return the last event that occurs before the end of the range.\n\n2) If there is no range, next will return the first event on or after the base date. prev\nwill return the last event before the base date.\n\nThe error codes are the same as for the nth method.\n", "subsections": [] }, "HISTORY OF THE FREQUENCY NOTATION": { "content": "I realize that the frequency notation described above looks quite complicated at first glance,\nbut it is (IMO) the best notation for expressing recurring events in existence. I actually\nconsider it the single most important contribution to date/time handling in Date::Manip.\n\nWhen I first decided to add recurring events to Date::Manip, I first came up with a list of\ncommon ways of specifying recurring events, and then went looking for a notation that could be\nused to define them. I was hoping for a notation that would be similar to cron notation, but\nmore powerful.\n\nAfter looking in several specifications (including ISO 8601) and after a discussion on a mailing\nlist of calendar related topics, it appeared that there was no concise, flexible notation for\nhandling recurring events that would handle all of the common forms I'd come up with.\n\nSo, as a matter of necessity, I set about inventing my own notation. As I was looking at my\nlist, it struck me that all of the parts which specified a frequency were higher level (i.e.\nreferred to a larger unit of time) than those parts which specified a specific value (what I've\ncalled the rtime). In other words, when the terms were laid out from year down to seconds, the\nfrequency part was always left of specific values.\n\nThat led immediately to the notation described above, so I started analyzing it to figure out if\nit could express all of the recurring events I'd come up with. It succeeded on 100% of them. Not\nonly that, but by playing with different values (especially different combinations of m/w/d\nvalues), I found that it would define recurring events that I hadn't even thought of, but which\nseemed perfectly reasonable in hindsight.\n\nAfter a very short period, I realized just how powerful this notation was, and set about\nimplementing it, and as I said above, of all the contributions that Date::Manip has made, I\nconsider this to be the most important.\n", "subsections": [] }, "KNOWN BUGS": { "content": "If you specify a recurrence which cannot be satisfied for the base date, or for any time after\nthe base date, the recurrence will crash. This can only happen if you specify a recurrence that\nalways occurs in the spring DST transition using the current timezone rules.\n\nFor example, in a US timezone, the current timezone rules state that a DST transition occurs at\n02:00:00 on the 2nd Sunday in March and the clock jumps to 03:00. This started in 2006. As a\nresult, the recurrence\n\n1*3:2:7:2:0:0\n\nwith a base date of 2006 or later cannot be satisfied.\n", "subsections": [] }, "BUGS AND QUESTIONS": { "content": "Please refer to the Date::Manip::Problems documentation for information on submitting bug\nreports or questions to the author.\n", "subsections": [] }, "SEE ALSO": { "content": "Date::Manip - main module documentation\n", "subsections": [] }, "LICENSE": { "content": "This script is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n", "subsections": [] }, "AUTHOR": { "content": "Sullivan Beck (sbeck@cpan.org)\n", "subsections": [] } } } }