{ "mode": "perldoc", "parameter": "Date::Manip::DM5", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADM5/json", "generated": "2026-06-12T05:49:31Z", "synopsis": "use Date::Manip;\n$version = DateManipVersion;\nDateInit();\nDateInit(\"VAR=VAL\",\"VAR=VAL\",...);\n@list = DateInit();\n@list = DateInit(\"VAR=VAL\",\"VAR=VAL\",...);\n$date = ParseDate(\\@args);\n$date = ParseDate($string);\n$date = ParseDate(\\$string);\n@date = UnixDate($date,@format);\n$date = UnixDate($date,@format);\n$delta = ParseDateDelta(\\@args);\n$delta = ParseDateDelta($string);\n$delta = ParseDateDelta(\\$string);\n@str = DeltaFormat($delta,$dec,@format);\n$str = DeltaFormat($delta,$dec,@format);\n$recur = ParseRecur($string,$base,$date0,$date1,$flags);\n@dates = ParseRecur($string,$base,$date0,$date1,$flags);\n$flag = DateCmp($date1,$date2);\n$d = DateCalc($d1,$d2 [,$errref] [,$del]);\n$date = DateSetTime($date,$hr,$min,$sec);\n$date = DateSetTime($date,$time);\n$date = DateSetDateField($date,$field,$val [,$nocheck]);\n$date = DateGetPrev($date,$dow,$today,$hr,$min,$sec);\n$date = DateGetPrev($date,$dow,$today,$time);\n$date = DateGetNext($date,$dow,$today,$hr,$min,$sec);\n$date = DateGetNext($date,$dow,$today,$time);\n$name = DateIsHoliday($date);\n$listref = EventsList($date);\n$listref = EventsList($date0,$date1);\n$date = DateConvTZ($date);\n$date = DateConvTZ($date,$from);\n$date = DateConvTZ($date,\"\",$to);\n$date = DateConvTZ($date,$from,$to);\n$flag = DateIsWorkDay($date [,$flag]);\n$date = DateNextWorkDay($date,$off [,$flag]);\n$date = DatePrevWorkDay($date,$off [,$flag]);\n$date = DateNearestWorkDay($date [,$tomorrowfirst]);\nThe above routines all check to make sure that DateInit is called. If it hasn't been, they will\ncall it automatically. As a result, there is usually no need to call DateInit explicitly unless\nyou want to change some of the config variables (described below). They also do error checking\non the input.\nThe routines listed below are intended primarily for internal use by other Date::Manip routines.\nThey do little or no error checking, and do not explicitly call DateInit. Those functions are\nall done in the main Date::Manip routines above.\nBecause they are significantly faster than the full Date::Manip routines, they are available for\nuse with a few caveats. Since little or no error checking is done, it is the responsibility of\nthe programmer to ensure that valid data (AND valid dates) are passed to them. Passing invalid\ndata (such as a non-numeric month) or invalid dates (Feb 31) will fail in unpredictable ways\n(possibly returning erroneous results). Also, since DateInit is not called by these, it must be\ncalled explicitly by the programmer before using these routines.\nIn the following routines, $y may be entered as either a 2 or 4 digit year (it will be converted\nto a 4 digit year based on the variable YYtoYYYY described below). Month and day should be\nnumeric in all cases. Most (if not all) of the information below can be gotten from UnixDate\nwhich is really the way I intended it to be gotten, but there are reasons to use these (these\nare significantly faster).\n$day = DateDayOfWeek($m,$d,$y);\n$secs = DateSecsSince1970($m,$d,$y,$h,$mn,$s);\n$secs = DateSecsSince1970GMT($m,$d,$y,$h,$mn,$s);\n$days = DateDaysSince1BC($m,$d,$y);\n$day = DateDayOfYear($m,$d,$y);\n($y,$m,$d,$h,$mn,$s) = DateNthDayOfYear($y,$n);\n$days = DateDaysInYear($y);\n$days = DateDaysInMonth($m,$y);\n$wkno = DateWeekOfYear($m,$d,$y,$first);\n$flag = DateLeapYear($y);\n$day = DateDaySuffix($d);\n$tz = DateTimeZone();", "sections": { "NAME": { "content": "Date::Manip::DM5 - Date manipulation routines\n", "subsections": [] }, "SYNOPSIS": { "content": "use Date::Manip;\n\n$version = DateManipVersion;\n\nDateInit();\nDateInit(\"VAR=VAL\",\"VAR=VAL\",...);\n@list = DateInit();\n@list = DateInit(\"VAR=VAL\",\"VAR=VAL\",...);\n\n$date = ParseDate(\\@args);\n$date = ParseDate($string);\n$date = ParseDate(\\$string);\n\n@date = UnixDate($date,@format);\n$date = UnixDate($date,@format);\n\n$delta = ParseDateDelta(\\@args);\n$delta = ParseDateDelta($string);\n$delta = ParseDateDelta(\\$string);\n\n@str = DeltaFormat($delta,$dec,@format);\n$str = DeltaFormat($delta,$dec,@format);\n\n$recur = ParseRecur($string,$base,$date0,$date1,$flags);\n@dates = ParseRecur($string,$base,$date0,$date1,$flags);\n\n$flag = DateCmp($date1,$date2);\n\n$d = DateCalc($d1,$d2 [,$errref] [,$del]);\n\n$date = DateSetTime($date,$hr,$min,$sec);\n$date = DateSetTime($date,$time);\n\n$date = DateSetDateField($date,$field,$val [,$nocheck]);\n\n$date = DateGetPrev($date,$dow,$today,$hr,$min,$sec);\n$date = DateGetPrev($date,$dow,$today,$time);\n\n$date = DateGetNext($date,$dow,$today,$hr,$min,$sec);\n$date = DateGetNext($date,$dow,$today,$time);\n\n$name = DateIsHoliday($date);\n\n$listref = EventsList($date);\n$listref = EventsList($date0,$date1);\n\n$date = DateConvTZ($date);\n$date = DateConvTZ($date,$from);\n$date = DateConvTZ($date,\"\",$to);\n$date = DateConvTZ($date,$from,$to);\n\n$flag = DateIsWorkDay($date [,$flag]);\n\n$date = DateNextWorkDay($date,$off [,$flag]);\n\n$date = DatePrevWorkDay($date,$off [,$flag]);\n\n$date = DateNearestWorkDay($date [,$tomorrowfirst]);\n\nThe above routines all check to make sure that DateInit is called. If it hasn't been, they will\ncall it automatically. As a result, there is usually no need to call DateInit explicitly unless\nyou want to change some of the config variables (described below). They also do error checking\non the input.\n\nThe routines listed below are intended primarily for internal use by other Date::Manip routines.\nThey do little or no error checking, and do not explicitly call DateInit. Those functions are\nall done in the main Date::Manip routines above.\n\nBecause they are significantly faster than the full Date::Manip routines, they are available for\nuse with a few caveats. Since little or no error checking is done, it is the responsibility of\nthe programmer to ensure that valid data (AND valid dates) are passed to them. Passing invalid\ndata (such as a non-numeric month) or invalid dates (Feb 31) will fail in unpredictable ways\n(possibly returning erroneous results). Also, since DateInit is not called by these, it must be\ncalled explicitly by the programmer before using these routines.\n\nIn the following routines, $y may be entered as either a 2 or 4 digit year (it will be converted\nto a 4 digit year based on the variable YYtoYYYY described below). Month and day should be\nnumeric in all cases. Most (if not all) of the information below can be gotten from UnixDate\nwhich is really the way I intended it to be gotten, but there are reasons to use these (these\nare significantly faster).\n\n$day = DateDayOfWeek($m,$d,$y);\n$secs = DateSecsSince1970($m,$d,$y,$h,$mn,$s);\n$secs = DateSecsSince1970GMT($m,$d,$y,$h,$mn,$s);\n$days = DateDaysSince1BC($m,$d,$y);\n$day = DateDayOfYear($m,$d,$y);\n($y,$m,$d,$h,$mn,$s) = DateNthDayOfYear($y,$n);\n$days = DateDaysInYear($y);\n$days = DateDaysInMonth($m,$y);\n$wkno = DateWeekOfYear($m,$d,$y,$first);\n$flag = DateLeapYear($y);\n$day = DateDaySuffix($d);\n$tz = DateTimeZone();\n", "subsections": [] }, "ROUTINES": { "content": "DateInit\nDateInit();\nDateInit(\"VAR=VAL\",\"VAR=VAL\",...);\n@list = DateInit();\n@list = DateInit(\"VAR=VAL\",\"VAR=VAL\",...);\n\nNormally, it is not necessary to explicitly call DateInit. The first time any of the other\nroutines are called, DateInit will be called to set everything up. If for some reason you\nwant to change the configuration of Date::Manip, you can pass the appropriate string or\nstrings into DateInit to reinitialize things.\n\nThe strings to pass in are of the form \"VAR=VAL\". Any number may be included and they can\ncome in any order. VAR may be any configuration variable. A list of all configuration\nvariables is given in the section CUSTOMIZING DATE::MANIP below. VAL is any allowed value\nfor that variable. For example, to switch from English to French and use non-US format (so\nthat 12/10 is Oct 12), do the following:\n\nDateInit(\"Language=French\",\"DateFormat=non-US\");\n\nIf DateInit is called in list context, it will return a list of all config variables and\ntheir values suitable for passing in to DateInit to return Date::Manip to the current\nstate. The only possible problem is that by default, holidays will not be erased, so you may\nneed to prepend the \"EraseHolidays=1\" element to the list.\n\nParseDate\n$date = ParseDate(\\@args);\n$date = ParseDate($string);\n$date = ParseDate(\\$string);\n\nThis takes an array or a string containing a date and parses it. When the date is included\nas an array (for example, the arguments to a program) the array should contain a valid date\nin the first one or more elements (elements after a valid date are ignored). Elements\ncontaining a valid date are shifted from the array. The largest possible number of elements\nwhich can be correctly interpreted as a valid date are always used. If a string is entered\nrather than an array, that string is tested for a valid date. The string is unmodified, even\nif passed in by reference.\n\nThe real work is done in the ParseDateString routine.\n\nThe ParseDate routine is primarily used to handle command line arguments. If you have a\ncommand where you want to enter a date as a command line argument, you can use Date::Manip\nto make something like the following work:\n\nmycommand -date Dec 10 1997 -arg -arg2\n\nNo more reading man pages to find out what date format is required in a man page.\n\nHistorical note: this is originally why the Date::Manip routines were written (though long\nbefore they were released as the Date::Manip module). I was using a bunch of programs\n(primarily batch queue managers) where dates and times were entered as command line options\nand I was getting highly annoyed at the many different (but not compatible) ways that they\nhad to be entered. Date::Manip originally consisted of basically 1 routine which I could\npass \"@ARGV\" to and have it remove a date from the beginning.\n\nParseDateString\n$date = ParseDateString($string);\n\nThis routine is called by ParseDate, but it may also be called directly to save some time (a\nnegligible amount).\n\nNOTE: One of the most frequently asked questions that I have gotten is how to parse seconds\nsince the epoch. ParseDateString cannot simply parse a number as the seconds since the epoch\n(it conflicts with some ISO-8601 date formats). There are two ways to get this information.\nFirst, you can do the following:\n\n$secs = ... # seconds since Jan 1, 1970 00:00:00 GMT\n$date = DateCalc(\"Jan 1, 1970 00:00:00 GMT\",\"+ $secs\");\n\nSecond, you can call it directly as:\n\n$date = ParseDateString(\"epoch $secs\");\n\nTo go backwards, just use the \"%s\" format of UnixDate:\n\n$secs = UnixDate($date,\"%s\");\n\nA full date actually includes 2 parts: date and time. A time must include hours and minutes\nand can optionally include seconds, fractional seconds, an am/pm type string, and a time\nzone. For example:\n\n[at] HH:MN [Zone]\n[at] HH:MN [am] [Zone]\n[at] HH:MN:SS [am] [Zone]\n[at] HH:MN:SS.SSSS [am] [Zone]\n[at] HH am [Zone]\n\nHours can be written using 1 or 2 digits, but the single digit form may only be used when no\nambiguity is introduced (i.e. when it is not immediately preceded by a digit).\n\nA time is usually entered in 24 hour mode, but 12 hour mode can be used as well if AM/PM are\nentered (AM can be entered as AM or A.M. or other variations depending on the language).\n\nFractional seconds are also supported in parsing but the fractional part is discarded (with\nNO rounding occurring).\n\nTime zones always appear immediately after the time. A number of different forms are\nsupported (see the section TIME ZONES below).\n\nIncidentally, the time is removed from the date before the date is parsed, so the time may\nappear before or after the date, or between any two parts of the date.\n\nValid date formats include the ISO 8601 formats:\n\nYYYYMMDDHHMNSSF...\nYYYYMMDDHHMNSS\nYYYYMMDDHHMN\nYYYYMMDDHH\nYY-MMDDHHMNSSF...\nYY-MMDDHHMNSS\nYY-MMDDHHMN\nYY-MMDDHH\nYYYYMMDD\nYYYYMM\nYYYY\nYY-MMDD\nYY-MM\nYY\nYYYYwWWD ex. 1965-W02-2\nYYwWWD\nYYYYDOY ex. 1965-045\nYYDOY\n\nIn the above list, YYYY and YY signify 4 or 2 digit years, MM, DD, HH, MN, SS refer to two\ndigit month, day, hour, minute, and second respectively. F... refers to fractional seconds\n(any number of digits) which will be ignored. In all cases, the date and time parts may be\nseparated by the letter \"T\" (but this is optional), so 2002-12-10-12:00:00\n2002-12-10T12:00:00 are identical.\n\nThe last 4 formats can be explained by example: 1965-w02-2 refers to Tuesday (day 2) of the\n2nd week of 1965. 1965-045 refers to the 45th day of 1965.\n\nIn all cases, parts of the date may be separated by dashes \"-\". If this is done, 1 or 2\ndigit forms of MM, DD, etc. may be used. All dashes are optional except for those given in\nthe table above (which MUST be included for that format to be correctly parsed). So\n19980820, 1998-0820, 1998-08-20, 1998-8-20, and 199808-20 are all equivalent, but that date\nmay NOT be written as 980820 (it must be written as 98-0820).\n\nNOTE: Even though not allowed in the standard, the time zone for an ISO-8601 date is\nflexible and may be any of the time zones understood by Date::Manip.\n\nAdditional date formats are available which may or may not be common including:\n\nMM/DD\nMM/DD/YY\nMM/DD/YYYY\n\nmmmDD DDmmm mmmYYYY/DD mmmYYYY\nmmmDD/YY DDmmmYY DD/YYmmm YYYYmmmDD YYYYmmm\nmmmDDYYYY DDmmmYYYY DDYYYYmmm YYYY/DDmmm\n\nWhere mmm refers to the name of a month. All parts of the date can be separated by valid\nseparators (space, \"/\", or \".\"). The separator \"-\" may be used as long as it doesn't\nconflict with an ISO 8601 format, but this is discouraged since it is easy to overlook\nconflicts. For example, the format MM/DD/YY is just fine, but MM-DD-YY does not work since\nit conflicts with YY-MM-DD. To be safe, if \"-\" is used as a separator in a non-ISO format,\nthey should be turned into \"/\" before calling the Date::Manip routines. As with ISO 8601\nformats, all separators are optional except for those given as a \"/\" in the list above.\n\nNote that with these formats, Americans tend to write month first, but many other\ncountries tend to write day first. The latter behavior can be obtained by setting the config\nvariable DateFormat to something other than \"US\" (see CUSTOMIZING DATE::MANIP below).\n\nDate separators are treated very flexibly (they are converted to spaces), so the following\ndates are all equivalent:\n\n12/10/1965\n12-10 / 1965\n12 // 10 -. 1965\n\nIn some cases, this may actually be TOO flexible, but no attempt is made to trap this.\n\nYears can be entered as 2 or 4 digits, days and months as 1 or 2 digits. Both days and\nmonths must include 2 digits whenever they are immediately adjacent to another numeric part\nof the date or time. Date separators are required if single digit forms of DD or MM are\nused. If separators are not used, the date will either be unparsable or will get parsed\nincorrectly.\n\nMiscellaneous other allowed formats are: which dofw in mmm in YY \"first Sunday in June 1996\nat 14:00\" dofw week num YY \"Sunday week 22 1995\" which dofw YY \"22nd Sunday at noon\"\ndofw which week YY \"Sunday 22nd week in 1996\" next/last dofw \"next Friday at noon\"\nnext/last week/month \"next month\" in num days/weeks/months \"in 3 weeks at 12:00\" num\ndays/weeks/months later \"3 weeks later\" num days/weeks/months ago \"3 weeks ago\" dofw in num\nweek \"Friday in 2 weeks\" in num weeks dofw \"in 2 weeks on Friday\" dofw num week ago \"Friday\n2 weeks ago\" num week ago dofw \"2 weeks ago Friday\" last day in mmm in YY \"last day of\nOctober\" dofw \"Friday\" (Friday of current week) Nth \"12th\", \"1st\" (day of current month)\nepoch SECS seconds since the epoch (negative values are supported)\n\nNote that the formats \"Sunday week 22\" and \"22nd Sunday\" give very different behaviors.\n\"Sunday week 22\" returns the Sunday of the 22nd week of the year based on how week 1 is\ndefined. ISO 8601 defines week one to contain Jan 4, so \"Sunday week 1\" might be the first\nor second Sunday of the current year, or the last Sunday of the previous year. \"22nd Sunday\"\ngives the actual 22nd time Sunday occurs in a given year, regardless of the definition of a\nweek.\n\nNote that certain words such as \"in\", \"at\", \"of\", etc. which commonly appear in a date or\ntime are ignored. Also, the year is always optional.\n\nIn addition, the following strings are recognized: today (exactly now OR today at a given\ntime if a time is specified) now (synonym for today) yesterday (exactly 24 hours ago unless\na time is specified) tomorrow (exactly 24 hours from now unless a time is specified) noon\n(12:00:00) midnight (00:00:00) Other languages have similar (and in some cases additional)\nstrings.\n\nSome things to note:\n\nAll strings are case insensitive. \"December\" and \"DEceMBer\" both work.\n\nWhen a part of the date is not given, defaults are used: year defaults to current year;\nhours, minutes, seconds to 00.\n\nThe year may be entered as 2 or 4 digits. If entered as 2 digits, it will be converted to a\n4 digit year. There are several ways to do this based on the value of the YYtoYYYY variable\n(described below). The default behavior it to force the 2 digit year to be in the 100 year\nperiod CurrYear-89 to CurrYear+10. So in 1996, the range is [1907 to 2006], and the 2 digit\nyear 05 would refer to 2005 but 07 would refer to 1907. See CUSTOMIZING DATE::MANIP below\nfor information on YYtoYYYY for other methods.\n\nDates are always checked to make sure they are valid.\n\nIn all of the formats, the day of week (\"Friday\") can be entered anywhere in the date and it\nwill be checked for accuracy. In other words, \"Tue Jul 16 1996 13:17:00\" will work but \"Jul\n16 1996 Wednesday 13:17:00\" will not (because Jul 16, 1996 is Tuesday, not Wednesday). Note\nthat depending on where the weekday comes, it may give unexpected results when used in array\ncontext (with ParseDate). For example, the date (\"Jun\",\"25\",\"Sun\",\"1990\") would return June\n25 of the current year since Jun 25, 1990 is not Sunday.\n\nThe times \"12:00 am\", \"12:00 pm\", and \"midnight\" are not well defined. For good or bad, I\nuse the following convention in Date::Manip: midnight = 12:00am = 00:00:00 noon = 12:00pm =\n12:00:00 and the day goes from 00:00:00 to 23:59:59. In other words, midnight is the\nbeginning of a day rather than the end of one. The time 24:00:00 is also allowed (though it\nis automatically transformed to 00:00:00 of the following day).\n\nThe format of the date returned is YYYYMMDDHH:MM:SS. The advantage of this time format is\nthat two times can be compared using simple string comparisons to find out which is later.\nAlso, it is readily understood by a human. Alternate forms can be used if that is more\nconvenient. See DateInit below and the config variable Internal.\n\nNOTE: The format for the date is going to change at some point in the future to\nYYYYMMDDHH:MN:SS+HHMN*FLAGS. In order to maintain compatibility, you should use UnixDate to\nextract information from a date, and DateCmp to compare two dates. The simple string\ncomparison will only work for dates in the same time zone.\n\nUnixDate\n@date = UnixDate($date,@format);\n$date = UnixDate($date,@format);\n\nThis takes a date and a list of strings containing formats roughly identical to the format\nstrings used by the UNIX date(1) command. Each format is parsed and an array of strings\ncorresponding to each format is returned.\n\n$date may be any string that can be parsed by ParseDateString.\n\nThe format options are:\n\nYear\n%y year - 00 to 99\n%Y year - 0001 to 9999\nMonth, Week\n%m month of year - 01 to 12\n%f month of year - \" 1\" to \"12\"\n%b,%h month abbreviation - Jan to Dec\n%B month name - January to December\nDay\n%j day of the year - 001 to 366\n%d day of month - 01 to 31\n\n%e day of month - \" 1\" to \"31\"\n%v weekday abbreviation - \" S\",\" M\",\" T\",\" W\",\"Th\",\" F\",\"Sa\"\n%a weekday abbreviation - Sun to Sat\n%A weekday name - Sunday to Saturday\n%w day of week - 1 (Monday) to 7 (Sunday)\n%E day of month with suffix - 1st, 2nd, 3rd...\nHour\n%H hour - 00 to 23\n%k hour - \" 0\" to \"23\"\n%i hour - \" 1\" to \"12\"\n%I hour - 01 to 12\n%p AM or PM\nMinute, Second, Time zone\n%M minute - 00 to 59\n%S second - 00 to 59\n%Z time zone - \"EDT\"\n%z time zone as GMT offset - \"+0100\"\nEpoch (see NOTE 3 below)\n%s seconds from 1/1/1970 GMT- negative if before 1/1/1970\n%o seconds from Jan 1, 1970\nin the current time zone\nDate, Time\n%c %a %b %e %H:%M:%S %Y - Fri Apr 28 17:23:15 1995\n%C,%u %a %b %e %H:%M:%S %z %Y - Fri Apr 28 17:25:57 EDT 1995\n%g %a, %d %b %Y %H:%M:%S %z - Fri, 28 Apr 1995 17:23:15 EDT\n%D %m/%d/%y - 04/28/95\n%x %m/%d/%y or %d/%m/%y - 04/28/95 or 28/04/28\n(Depends on DateFormat variable)\n%l date in ls(1) format (see NOTE 1 below)\n%b %e $H:$M - Apr 28 17:23 (if within 6 months)\n%b %e %Y - Apr 28 1993 (otherwise)\n%r %I:%M:%S %p - 05:39:55 PM\n%R %H:%M - 17:40\n%T,%X %H:%M:%S - 17:40:58\n%V %m%d%H%M%y - 0428174095\n%Q %Y%m%d - 19961025\n%q %Y%m%d%H%M%S - 19961025174058\n%P %Y%m%d%H%M%S - 1996102517:40:58\n%O %Y-%m-%dT%H:%M:%S - 1996-10-25T17:40:58\n%F %A, %B %e, %Y - Sunday, January 1, 1996\n%K %Y-%j - 1997-045\nSpecial Year/Week formats (see NOTE 2 below)\n%G year, Monday as first\nday of week - 0001 to 9999\n%W week of year, Monday\nas first day of week - 01 to 53\n%L year, Sunday as first\nday of week - 0001 to 9999\n%U week of year, Sunday\nas first day of week - 01 to 53\n%J %G-W%W-%w - 1997-W02-2\nOther formats\n%n insert a newline character\n%t insert a tab character\n%% insert a `%' character\n%+ insert a `+' character\nThe following formats are currently unused but may be used in the future:\nN 1234567890 !@#$^&*()|-=\\`[];',./~{}:<>?\nThey currently insert the character following the %, but may (and probably\nwill) change in the future as new formats are added.\n\nIf a lone percent is the final character in a format, it is ignored.\n\nThe formats used in this routine were originally based on date.pl (version 3.2) by Terry\nMcGonigal, as well as a couple taken from different versions of the Solaris date(1) command.\nAlso, several have been added which are unique to Date::Manip.\n\nNOTE 1:\n\nThe ls format (%l) applies to date within the past OR future 6 months!\n\nNOTE 2:\n\nThe %U, %W, %L, %G, and %J formats are used to support the ISO-8601 format: YYYY-wWW-D. In\nthis format, a date is written as a year, the week of the year, and the day of the week.\nTechnically, the week may be considered to start on any day of the week, but Sunday and\nMonday are the both common choices, so both are supported.\n\nThe %W and %G formats return the week-of-year and the year treating weeks as starting on\nMonday.\n\nThe %U and %L formats return the week-of-year and the year treating weeks as starting on\nSunday.\n\nMost of the time, the %L and %G formats returns the same value as the %Y format, but there\nis a problem with days occurring in the first or last week of the year.\n\nThe ISO-8601 representation of Jan 1, 1993 written in the YYYY-wWW-D format is actually\n1992-W53-5. In other words, Jan 1 is treated as being in the last week of the preceding\nyear. Depending on the year, days in the first week of a year may belong to the previous\nyear, and days in the final week of a year may belong to the next year. The week is assigned\nto the year which has most of the days. For example, if the week starts on Sunday, then the\nlast week of 2003 is 2003-12-28 to 2004-01-03. This week is assigned to 2003 since 4 of the\ndays in it are in 2003 and only 3 of them are in 2004. The first week of 2004 starts on\n2004-01-04.\n\nThe %U and %W formats return a week-of-year number from 01 to 53. %L and %G return the\ncorresponding year, and to get this type of information, you should always use the (%W,%G)\ncombination or (%U,%L) combination. %Y should not be used as it will yield incorrect\nresults.\n\n%J returns the full ISO-8601 format (%G-W%W-%w).\n\nNOTE 3:\n\nThe %s and %o formats return negative values if the date is before the start of the epoch.\nOther Unix utilities would return an error, or a zero, so if you are going to use\nDate::Manip in conjunction with these, be sure to check for a negative value.\n\nParseDateDelta\n$delta = ParseDateDelta(\\@args);\n$delta = ParseDateDelta($string);\n$delta = ParseDateDelta(\\$string);\n\nThis takes an array and shifts a valid delta date (an amount of time) from the array.\nRecognized deltas are of the form: +Yy +Mm +Ww +Dd +Hh +MNmn +Ss examples: +4 hours +3mn\n-2second + 4 hr 3 minutes -2 4 hour + 3 min -2 s +Y:+M:+W:+D:+H:+MN:+S examples:\n0:0:0:0:4:3:-2 +4:3:-2 mixed format examples: 4 hour 3:-2\n\nA field in the format +Yy is a sign, a number, and a string specifying the type of field.\nThe sign is \"+\", \"-\", or absent (defaults to the next larger element). The valid strings\nspecifying the field type are: y: y, yr, year, years m: m, mon, month, months w: w, wk, ws,\nwks, week, weeks d: d, day, days h: h, hr, hour, hours mn: mn, min, minute, minutes s: s,\nsec, second, seconds\n\nAlso, the \"s\" string may be omitted. The sign, number, and string may all be separated from\neach other by any number of whitespace.\n\nIn the date, all fields must be given in the order: Y M W D H MN S. Any number of them may\nbe omitted provided the rest remain in the correct order. In the 2nd (colon) format, from 2\nto 7 of the fields may be given. For example +D:+H:+MN:+S may be given to specify only four\nof the fields. In any case, both the MN and S field may be present. No spaces may be present\nin the colon format.\n\nDeltas may also be given as a combination of the two formats. For example, the following is\nvalid: +Yy +D:+H:+MN:+S. Again, all fields must be given in the correct order.\n\nThe word \"in\" may be given (prepended in English) to the delta (\"in 5 years\") and the word\n\"ago\" may be given (appended in English) (\"6 months ago\"). The \"in\" is completely ignored.\nThe \"ago\" has the affect of reversing all signs that appear in front of the components of\nthe delta. I.e. \"-12 yr 6 mon ago\" is identical to \"+12yr +6mon\" (don't forget that there is\nan implied minus sign in front of the 6 because when no sign is explicitly given, it carries\nthe previously entered sign).\n\nOne thing is worth noting. The year/month and day/hour/min/sec parts are returned in a\n\"normalized\" form. That is, the signs are adjusted so as to be all positive or all negative.\nFor example, \"+ 2 day - 2hour\" does not return \"0:0:0:2:-2:0:0\". It returns\n\"+0:0:0:1:22:0:0\" (1 day 22 hours which is equivalent). I find (and I think most others\nagree) that this is a more useful form.\n\nSince the year/month and day/hour/min/sec parts must be normalized separately there is the\npossibility that the sign of the two parts will be different. So, the delta \"+ 2years -10\nmonths - 2 days + 2 hours\" produces the delta \"+1:2:-0:1:22:0:0\".\n\nIt is possible to include a sign for all elements that is output. See the configuration\nvariable DeltaSigns below.\n\nNOTE: The internal format of the delta changed in version 5.30 from Y:M:D:H:MN:S to\nY:M:W:D:H:MN:S . Also, it is going to change again at some point in the future to\nY:M:W:D:H:MN:S*FLAGS . Use the routine DeltaFormat to extract information rather than\nparsing it yourself.\n\nDeltaFormat\n@str = DeltaFormat($delta [,$mode], $dec,@format);\n$str = DeltaFormat($delta [,$mode], $dec,@format);\n\nThis is similar to the UnixDate routine except that it extracts information from a delta.\nUnlike the UnixDate routine, most of the formats are 2 characters instead of 1.\n\nFormats currently understood are:\n\n%Xv : the value of the field named X\n%Xd : the value of the field X, and all smaller fields, expressed in\nunits of X\n%Xh : the value of field X, and all larger fields, expressed in units\nof X\n%Xt : the value of all fields expressed in units of X\n\nX is one of y,M,w,d,h,m,s (case sensitive).\n\n%% : returns a \"%\"\n\nSo, the format \"%hd\" means the values of H, MN, and S expressed in hours. So for the delta\n\"0:0:0:0:2:30:0\", this format returns 2.5.\n\nDeltaFormat can operate in two modes: exact and approximate. The exact mode is done by\ndefault. Approximate mode can be done by passing in the string \"approx\" as the 2nd argument.\n\nIn exact mode, DeltaFormat only understands \"exact\" relationships. This means that there\ncan be no mixing of the Y/M and W/D/H/MN/S segments because the relationship because,\ndepending on when the delta occurs, there is no exact relation between the number of years\nor months and the number of days.\n\nThe two sections are treated completely separate from each other. So, the delta\n\"1:6:1:2:12:0:0\" would return the following values:\n\n%yt = 1.5 (1 year, 6 months)\n%Mt = 18\n\n%dt = 9.5 (1 week, 2 days, 12 hours)\n\nIn approximate mode, the relationship of 1 year = 365.25 days is applied (with 1 month equal\nto 1/12 of a year exactly). So the delta \"1:6:1:2:12:0:0\" would return the following values:\n\n%dt = 557.375 (1.5 years of 365.25 days + 9.5 days)\n\nIf $dec is non-zero, the %Xd and %Xt values are formatted to contain $dec decimal places.\n\nParseRecur\n$recur = ParseRecur($string [,$base,$date0,$date1,$flags]);\n@dates = ParseRecur($string [,$base,$date0,$date1,$flags]);\n\nA recurrence refers to a recurring event, and more specifically, an event which occurs on a\nregular basis. A fully specified recurring event may requires up to four pieces of\ninformation.\n\nFirst, it requires a description of the frequency of the event. Examples include \"the first\nof every month\", \"every other day\", \"the 4th Thursday of each month at 2:00 PM\", and \"every\n2 hours and 30 minutes\".\n\nSecond, it may require a base date to work from. This piece of information is not required\nfor every type of recurrence. For example, if the frequency is \"the first of every month\",\nno base date is required. All the information about when the event occurs is included in the\nfrequency description. If the frequency were \"every other day\" though, you need to know at\nleast one day on which the event occurred.\n\nThird, the recurring event may have a range (a starting and ending date).\n\nFourth, there may be some flags included which modify the behavior of the above information.\n\nThe fully specified recurrence is written as these 5 pieces of information (both a start and\nend date) as an asterisk separated list:\n\nfreq*flags*base*date0*date1\n\nHere, base, date0, and date1 are any strings (which must not contain any asterisks) which\ncan be parsed by ParseDate. flags is a comma separated list of flags (described below), and\nfreq is a string describing the frequency of the recurring event.\n\nThe syntax of the frequency description is a colon separated list of the format\nY:M:W:D:H:MN:S (which stand for year, month, week, etc.). One (and only one) of the colons\nmay optionally be replaced by an asterisk, or an asterisk may be prepended to the string.\nFor example, the following 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 2 or more asterisks:\n\n1:2*3:4:5*6:7\n1*2*3:4:5*6:7\n*1:2:3:4:5:6*7\n\nIf an asterisk is included, values to the left of it refer to the number of times that time\ninterval occurs between recurring events. For example, if the first part of the recurrence\nis:\n\n1:2*\n\nthis says that the recurring event occurs approximately every 1 year and 2 months. I say\napproximately, because elements to the right of the asterisk, as well as any flags included\nin the recurrence will affect when the actual events occur.\n\nIf no asterisks are included, then the entire recurrence is of this form. For example,\n\n0:0:0:1:12:0:0\n\nrefers to an event that occurs every 1 day, 12 hours.\n\nValues that occur after an asterisk refer to a specific value for that type of time element\n(i.e. exactly as it would appear on a calendar or a clock). For example, if the recurrence\nends with:\n\n*12:0:0\n\nthen the recurring event occurs at 12:00:00 (noon).\n\nFor example:\n\n0:0:2:1:0:0:0 every 2 weeks and 1 day\n0:0:0:0:5:30:0 every 5 hours and 30 minutes\n0:0:0:2*12:30:0 every 2 days at 12:30 (each day)\n\nValues to the right of the asterisk can be listed a single values, ranges (2 numbers\nseparated by a dash \"-\"), or a comma separated list of values or ranges. In most cases,\nnegative values are appropriate for the week or day values. -1 stands for the last possible\nvalue, -2 for the second to the last, etc.\n\nSome examples are:\n\n0:0:0:1*2,4,6:0:0 every day at at 2:00, 4:00, and 6: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\nWhen a non-zero day element occurs to the right of the asterisk, it can take on multiple\nmeanings, depending on the value of the month and week elements. It can refer to the day of\nthe week, day of the month, or day of the year. Similarly, if a non-zero week element occurs\nto the right of the asterisk, it actually refers to the nth time a certain day of the week\noccurs, either in the month or in the year.\n\nIf the week element is non-zero and the day element is non-zero (and to the right of the\nasterisk), the day element refers to the day of the week. It can be any value from 1 to 7\n(negative values -1 to -7 are also allowed). If you use the ISO 8601 convention, the first\nday of the week is Monday (though Date::Manip can use any day as the start of the week by\nsetting the FirstDay config variable). So, assuming that you are using the ISO 8601\nconvention, the following examples illustrate day-of-week recurrences:\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\nIf the week element is non-zero, and the day element is zero, the day defaults to 1 (i.e.\nthe first day of the week).\n\n0:1*2:0:0:0:0 the 2nd occurrence of FirstDay\nin the year (typically Monday)\n0:1*2:1:0:0:0 the same\n\nIf the week element is zero and the month element is non-zero, the day value is the day of\nthe month (it can be from 1 to 31 or -1 to -31 counting from the end of the month). If a\nvalue of 0 is given, it defaults to 1.\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\nIf 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\nvalue is the day of the year (1 to 365 or 366 -- or the negative numbers to count backwards\nfrom the end of 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\nof this is that specifying +366 or -366 will ignore all years except leap years.\n\nI realize that this looks a bit cryptic, but after a discussion on the CALENDAR mailing\nlist, it appeared like there was no concise, flexible notation for handling recurring\nevents. ISO 8601 notations were very bulky and lacked the flexibility I wanted. As a result,\nI developed this notation (based on crontab formats, but with much more flexibility) which\nfits in well with this module. Even better, it is able to express every type of recurring\nevent I could think of that is used in common life in (what I believe to be) a very concise\nand elegant way.\n\nIf ParseRecur is called in scalar context, it returns a string containing a fully specified\nrecurrence (or as much of it as can be determined with unspecified fields left blank). In\nlist context, it returns a list of all dates referred to by a recurrence if enough\ninformation is given in the recurrence. All dates returned are in the range:\n\ndate0 <= date < date1\n\nThe argument $string can contain any of the parts of a full recurrence. For example:\n\nfreq\nfreq*flags\nfreqbase*date0*date1\n\nThe only part which is required is the frequency description. Any values contained in\n$string are overridden or modified by values passed in as parameters to ParseRecur.\n\nNOTE: If a recurrence has a date0 and date1 in it AND a date0 and date1 are passed in to the\nfunction, both sets of criteria apply. If flags are passed in, they override any flags in\nthe recurrence UNLESS the flags passed in start with a plus (+) character in which case they\nare appended to the flags in the recurrence.\n\nNOTE: Base dates are only used with some types of recurrences. For example,\n\n0:0:3*2:0:0:0 every 3rd Tuesday\n\nrequires a base date. If a base date is specified which doesn't match the criteria (for\nexample, if a base date falling on Monday were passed in with this recurrence), the base\ndate is moved forward to the first relevant date.\n\nOther dates do not require a base date. For example:\n\n0:0*3:2:0:0:0 third Tuesday of every month\n\nA recurrence written in the above format does NOT provide default values for base, date0, or\ndate1. They must be specified in order to get a list of dates.\n\nA base date is not used entirely. It is only used to provide the parts necessary for the\nleft part of a recurrence. For example, the recurrence:\n\n1:3*0:4:0:0:0 every 1 year, 3 months on the 4th day of the month\n\nwould only use the year and month of the base date.\n\nThere are a small handful of English strings which can be parsed in place of a numerical\nrecur description. These include:\n\nevery 2nd day [in 1997]\nevery 2nd day in June [1997]\n2nd day of every month [in 1997]\n2nd Tuesday of every month [in 1997]\nlast Tuesday of every month [in 1997]\nevery Tuesday [in 1997]\nevery 2nd Tuesday [in 1997]\nevery 2nd Tuesday in June [1997]\n\nEach of these set base, date0, and date1 to a default value (the current year with Jan 1\nbeing the base date is the default if the year and month are missing).\n\nThe following flags (case insensitive) are understood:\n\nPDn : n is 1-7. Means the previous day n not counting today\nPTn : n is 1-7. Means the previous day n counting today\nNDn : n is 1-7. Means the next day n not counting today\nNTn : n is 1-7. Means the next day n counting today\n\nFDn : n is any number. Means step forward n days.\nBDn : n is any number. Means step backward n days.\nFWn : n is any number. Means step forward n workdays.\nBWn : n is any number. Means step backward n workdays.\n\nCWD : the closest work day (using the TomorrowFirst config variable).\nCWN : the closest work day (looking forward first).\nCWP : the closest work day (looking backward first).\n\nNWD : next work day counting today\nPWD : previous work day counting today\nDWD : next/previous work day (TomorrowFirst config) counting today\n\nEASTER: select easter for this year (the M, W, D fields are ignored\nin the recur).\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 flags are applied AFTER the recurrence dates are calculated, and they may move a date\noutside of the date0 to date1 range. No check is made for this.\n\nThe workday flags do not act exactly the same as a business mode calculation. For example, a\ndate that is Saturday with a FW1 steps forward to the first workday (i.e. Monday).\n\nDateCmp\n$flag = DateCmp($date1,$date2);\n\nThis takes two dates and compares them. Almost all dates can be compared using the Perl\n\"cmp\" command. The only time this will not work is when comparing dates in different time\nzones. This routine will take that into account.\n\nNOTE: This routine currently does little more than use \"cmp\", but once the internal format\nfor storing dates is in place (where time zone information is kept as part of the date),\nthis routine will become more important. You should use this routine in preparation for that\nversion.\n\nDateCalc\n$d = DateCalc($d1,$d2 [,\\$err] [,$mode]);\n\nThis takes two dates, deltas, or one of each and performs the appropriate calculation with\nthem. Dates must be a string that can be parsed by ParseDateString. Deltas must be a string\nthat can be parsed by ParseDateDelta. Two deltas add together to form a third delta. A date\nand a delta returns a 2nd date. Two dates return a delta (the difference between the two\ndates).\n\nSince the two items can be interpreted as either dates or deltas, and since many types of\ndates can be interpreted as deltas (and vice versa), it is a good idea to pass the input\nthrough ParseDate or ParseDateDelta as appropriate. For example, the string \"09:00:00\" can\nbe interpreted either as a date (today at 9:00:00) or a delta (9 hours). To avoid unexpected\nresults, avoid calling DateCalc as:\n\n$d = DateCalc(\"09:00:00\",$someothervalue);\n\nInstead, call it as:\n\n$d = DateCalc(ParseDate(\"09:00:00\"),$someothervalue);\n\nto force it to be a date, or:\n\n$d = DateCalc(ParseDateDelta(\"09:00:00\"),$someothervalue);\n\nto force it to be a delta. This will avoid unexpected results.\n\nNote that in many cases, it is somewhat ambiguous what the delta actually refers to.\nAlthough it is ALWAYS known how many months in a year, hours in a day, etc., it is NOT known\n(in the generals case) how many days are in a month. As a result, the part of the delta\ncontaining month/year and the part with sec/min/hr/day must be treated separately. For\nexample, \"Mar 31, 12:00:00\" plus a delta of 1month 2days would yield \"May 2 12:00:00\". The\nyear/month is first handled while keeping the same date. Mar 31 plus one month is Apr 31\n(but since Apr only has 30 days, it becomes Apr 30). Apr 30 + 2 days is May 2. As a result,\nin the case where two dates are entered, the resulting delta can take on two different\nforms. By default ($mode=0), an absolutely correct delta (ignoring daylight saving time) is\nreturned in weeks, days, hours, minutes, and seconds.\n\nIf $mode is 1, the math is done using an approximate mode where a delta is returned using\nyears and months as well. The year and month part is calculated first followed by the rest.\nFor example, the two dates \"Mar 12 1995\" and \"Apr 13 1995\" would have an exact delta of \"31\ndays\" but in the approximate mode, it would be returned as \"1 month 1 day\". Also, \"Mar 31\"\nand \"Apr 30\" would have deltas of \"30 days\" or \"1 month\" (since Apr 31 doesn't exist, it\ndrops down to Apr 30). Approximate mode is a more human way of looking at things (you'd say\n1 month and 2 days more often then 33 days), but it is less meaningful in terms of absolute\ntime. In approximate mode $d1 and $d2 must be dates. If either or both is a delta, the\ncalculation is done in exact mode.\n\nIf $mode is 2, a business mode is used. That is, the calculation is done using business\ndays, ignoring holidays, weekends, etc. In order to correctly use this mode, a config file\nmust exist which contains the section defining holidays (see documentation on the config\nfile below). The config file can also define the work week and the hours of the work day, so\nit is possible to have different config files for different businesses.\n\nFor example, if a config file defines the workday as 08:00 to 18:00, a work week consisting\nof Mon-Sat, and the standard (American) holidays, then from Tuesday at 12:00 to the\nfollowing Monday at 14:00 is 5 days and 2 hours. If the \"end\" of the day is reached in a\ncalculation, it automatically switches to the next day. So, Tuesday at 12:00 plus 6 hours is\nWednesday at 08:00 (provided Wed is not a holiday). Also, a date that is not during a\nworkday automatically becomes the start of the next workday. So, Sunday 12:00 and Monday at\n03:00 both automatically becomes Monday at 08:00 (provided Monday is not a holiday). In\nbusiness mode, any combination of date and delta may be entered, but a delta should not\ncontain a year or month field (weeks are fine though).\n\nSee Date::Manip::Calc for some additional comments about business mode calculations.\n\nNote that a business week is treated the same as an exact week (i.e. from Tuesday to\nTuesday, regardless of holidays). Because this means that the relationship between days and\nweeks is NOT unambiguous, when a delta is produced from two dates, it will be in terms of\nd/h/mn/s (i.e. no week field).\n\nIf $mode is 3 (which only applies when two dates are passed in), an exact business mode is\nused. In this case, it returns a delta as an exact number of business days/hours/etc.\nbetween the two. Weeks, months, and years are ignored.\n\nAny other non-nil value of $mode is treated as $mode=1 (approximate mode).\n\nThe mode can be automatically set in the dates/deltas passed by including a key word\nsomewhere in it. For example, in English, if the word \"approximately\" is found in either of\nthe date/delta arguments, approximate mode is forced. Likewise, if the word \"business\" or\n\"exactly\" appears, business/exact mode is forced (and $mode is ignored). So, the two\nfollowing are equivalent:\n\n$date = DateCalc(\"today\",\"+ 2 business days\",\\$err);\n$date = DateCalc(\"today\",\"+ 2 days\",\\$err,2);\n\nNote that if the keyword method is used instead of passing in $mode, it is important that\nthe keyword actually appear in the argument passed in to DateCalc. The following will NOT\nwork:\n\n$delta = ParseDateDelta(\"+ 2 business days\");\n$today = ParseDate(\"today\");\n$date = DateCalc($today,$delta,\\$err);\n\nbecause the mode keyword is removed from a date/delta by the parse routines, and the mode is\nreset each time a parse routine is called. Since DateCalc parses both of its arguments,\nwhatever mode was previously set is ignored.\n\nIf \\$err is passed in, it is set to: 1 is returned if $d1 is not a delta or date 2 is\nreturned if $d2 is not a delta or date 3 is returned if the date is outside the years 1000\nto 9999 This argument is optional, but if included, it must come before $mode.\n\nNothing is returned if an error occurs.\n\nWhen a delta is returned, the signs such that it is strictly positive or strictly negative\n(\"1 day - 2 hours\" would never be returned for example). The only time when this cannot be\nenforced is when two deltas with a year/month component are entered. In this case, only the\nsigns on the day/hour/min/sec part are standardized.\n\nDateSetTime\n$date = DateSetTime($date,$hr,$min,$sec);\n$date = DateSetTime($date,$time);\n\nThis takes a date (any string that may be parsed by ParseDateString) and sets the time in\nthat date. For example, one way to get the time for 7:30 tomorrow would be to use the lines:\n\n$date = ParseDate(\"tomorrow\");\n$date = DateSetTime($date,\"7:30\");\n\nNote that in this routine (as well as the other routines below which use a time argument),\nno real parsing is done on the times. As a result,\n\n$date = DateSetTime($date,\"13:30\");\n\nworks, but\n\n$date = DateSetTime($date,\"1:30 PM\");\n\ndoesn't.\n\nDateSetDateField\n$date = DateSetDateField($date,$field,$val [,$nocheck]);\n\nThis takes a date and sets one of its fields to a new value. $field is any of the strings\n\"y\", \"m\", \"d\", \"h\", \"mn\", \"s\" (case insensitive) and $val is the new value.\n\nIf $nocheck is non-zero, no check is made as to the validity of the date.\n\nDateGetPrev\n$date = DateGetPrev($date,$dow, $curr [,$hr,$min,$sec]);\n$date = DateGetPrev($date,$dow, $curr [,$time]);\n$date = DateGetPrev($date,undef,$curr,$hr,$min,$sec);\n$date = DateGetPrev($date,undef,$curr,$time);\n\nThis takes a date (any string that may be parsed by ParseDateString) and finds the previous\noccurrence of either a day of the week, or a certain time of day.\n\nIf $dow is defined, the previous occurrence of the day of week is returned. $dow may either\nbe a string (such as \"Fri\" or \"Friday\") or a number (between 1 and 7). The date of the\nprevious $dow is returned.\n\nIf $date falls on the day of week given by $dow, the date returned depends on $curr. If\n$curr is 0, the date returned is a week before $date. If $curr is 1, the date returned is\nthe same as $date. If $curr is 2, the date returned (including the time information) is\nrequired to be before $date.\n\nIf a time is passed in (either as separate hours, minutes, seconds or as a time in HH:MM:SS\nor HH:MM format), the time on this date is set to it. The following examples should\nillustrate the use of DateGetPrev:\n\ndate dow curr time returns\nFri Nov 22 18:15:00 Thu any 12:30 Thu Nov 21 12:30:00\nFri Nov 22 18:15:00 Fri 0 12:30 Fri Nov 15 12:30:00\nFri Nov 22 18:15:00 Fri 1/2 12:30 Fri Nov 22 12:30:00\n\nFri Nov 22 18:15:00 Fri 1 18:30 Fri Nov 22 18:30:00\nFri Nov 22 18:15:00 Fri 2 18:30 Fri Nov 15 18:30:00\n\nIf $dow is undefined, then a time must be entered, and the date returned is the previous\noccurrence of this time. If $curr is non-zero, the current time is returned if it matches\nthe criteria passed in. In other words, the time returned is the last time that a digital\nclock (in 24 hour mode) would have displayed the time you passed in. If you define hours,\nminutes and seconds default to 0 and you might jump back as much as an entire day. If hours\nare undefined, you are looking for the last time the minutes/seconds appeared on the digital\nclock, so at most, the time will jump back one hour.\n\ndate curr hr min sec returns\nNov 22 18:15:00 0/1 18 undef undef Nov 22 18:00:00\nNov 22 18:15:00 0/1 18 30 0 Nov 21 18:30:00\nNov 22 18:15:00 0 18 15 undef Nov 21 18:15:00\nNov 22 18:15:00 1 18 15 undef Nov 22 18:15:00\nNov 22 18:15:00 0 undef 15 undef Nov 22 17:15:00\nNov 22 18:15:00 1 undef 15 undef Nov 22 18:15:00\n\nDateGetNext\n$date = DateGetNext($date,$dow, $curr [,$hr,$min,$sec]);\n$date = DateGetNext($date,$dow, $curr [,$time]);\n$date = DateGetNext($date,undef,$curr,$hr,$min,$sec);\n$date = DateGetNext($date,undef,$curr,$time);\n\nSimilar to DateGetPrev.\n\nDateIsHoliday\n$name = DateIsHoliday($date);\n\nThis returns undef if $date is not a holiday, or a string containing the name of the holiday\notherwise. An empty string is returned for an unnamed holiday.\n\nEventsList\n$ref = EventsList($date);\n$ref = EventsList($date ,0 [,$flag]);\n$ref = EventsList($date0,$date1 [,$flag]);\n\nThis returns a list of events. Events are defined in the Events section of the config file\n(discussed below).\n\nIn the first form (a single argument), $date is any string containing a date. A list of\nevents active at that precise time will be returned. The format is similar to when $flag=0,\nexcept only a single time will be returned.\n\nIn all other cases, a range of times will be used. If the 2nd argument evaluates to 0, the\nrange of times will be the 24 hour period from midnight to midnight containing $date.\nOtherwise, the range is given by the two dates.\n\nThe value of $flag determines the format of the information that is returned.\n\nWith $flag=0, the events are returned as a reference to a list of the form:\n\n[ date, [ listofevents ], date, [ listofevents ], ... ]\n\nFor example, if the following events are defined (using the syntax discussed below in the\ndescription of the Event section of the config file):\n\n2000-01-01 ; 2000-03-21 = Winter\n2000-03-22 ; 2000-06-21 = Spring\n2000-02-01 = Event1\n2000-05-01 = Event2\n2000-04-01-12:00:00 = Event3\n\nmight result in the following output:\n\nEventsList(\"2000-04-01\")\n=> [ 2000040100:00:00, [ Spring ] ]\n\nEventsList(\"2000-04-01 12:30\");\n=> [ 2000040112:30:00, [ Spring, Event3 ] ]\n\nEventsList(\"2000-04-01\",0);\n=> [ 2000040100:00:00, [ Spring ],\n2000040112:00:00, [ Spring, Event3 ],\n2000040113:00:00, [ Spring ] ]\n\nEventsList(\"2000-03-15\",\"2000-04-10\");\n=> [ 2000031500:00:00, [ Winter ],\n2000032200:00:00, [ Spring ]\n2000040112:00:00, [ Spring, Event3 ]\n2000040113:00:00, [ Spring ] ]\n\nMuch more complicated events can be defined using recurrences.\n\nWhen $flag is non-zero, the format of the output is changed. If $flag is 1, then a tally of\nthe amount of time given to each event is returned. Time for which two or more events apply\nis counted for both.\n\nEventsList(\"2000-03-15\",\"2000-04-10\",1);\n=> { Winter => +0:0:1:0:0:0:0,\nSpring => +0:0:2:5:0:0:0,\nEvent3 => +0:0:0:0:1:0:0 }\n\nWhen $flag is 2, a more complex tally with no event counted twice is returned.\n\nEventsList(\"2000-03-15\",\"2000-04-10\",2);\n=> { Winter => +0:0:1:0:0:0:0,\nSpring => +0:0:2:4:23:0:0,\nEvent3+Spring => +0:0:0:0:1:0:0 }\n\nThe hash contains one element for each combination of events.\n\nDateDayOfWeek\n$day = DateDayOfWeek($m,$d,$y);\n\nReturns the day of the week (1 for Monday, 7 for Sunday).\n\nAll arguments must be numeric.\n\nDateSecsSince1970\n$secs = DateSecsSince1970($m,$d,$y,$h,$mn,$s);\n\nReturns the number of seconds since Jan 1, 1970 00:00 (negative if date is earlier).\n\nAll arguments must be numeric.\n\nDateSecsSince1970GMT\n$secs = DateSecsSince1970GMT($m,$d,$y,$h,$mn,$s);\n\nReturns the number of seconds since Jan 1, 1970 00:00 GMT (negative if date is earlier). If\nCurrTZ is \"IGNORE\", the number will be identical to DateSecsSince1970 (i.e. the date given\nwill be treated as being in GMT).\n\nAll arguments must be numeric.\n\nDateDaysSince1BC\n$days = DateDaysSince1BC($m,$d,$y);\n\nReturns the number of days since Dec 31, 1BC. This includes the year 0000.\n\nAll arguments must be numeric.\n\nDateDayOfYear\n$day = DateDayOfYear($m,$d,$y);\n\nReturns the day of the year (001 to 366)\n\nAll arguments must be numeric.\n\nDateNthDayOfYear\n($y,$m,$d,$h,$mn,$s) = DateNthDayOfYear($y,$n);\n\nReturns the year, month, day, hour, minutes, and decimal seconds given a floating point day\nof the year.\n\nAll arguments must be numeric. $n must be greater than or equal to 1 and less than 366 on\nnon-leap years and 367 on leap years.\n\nNOTE: When $n is a decimal number, the results are non-intuitive perhaps. Day 1 is Jan 01\n00:00. Day 2 is Jan 02 00:00. Intuitively, you might think of day 1.5 as being 1.5 days\nafter Jan 01 00:00, but this would mean that Day 1.5 was Jan 02 12:00 (which is later than\nDay 2). The best way to think of this function is a time line starting at 1 and ending at\n366 (in a non-leap year). In terms of a delta, think of $n as the number of days after Dec\n31 00:00 of the previous year.\n\nDateDaysInYear\n$days = DateDaysInYear($y);\n\nReturns the number of days in the year (365 or 366)\n\nDateDaysInMonth\n$days = DateDaysInMonth($m,$y);\n\nReturns the number of days in the month.\n\nDateWeekOfYear\n$wkno = DateWeekOfYear($m,$d,$y,$first);\n\nFigure out week number. $first is the first day of the week which is usually 1 (Monday) or 7\n(Sunday), but could be any number between 1 and 7 in practice.\n\nAll arguments must be numeric.\n\nNOTE: This routine should only be called in rare cases. Use UnixDate with the %W, %U, %J, %L\nformats instead. This routine returns a week between 0 and 53 which must then be \"fixed\" to\nget into the ISO-8601 weeks from 1 to 53. A date which returns a week of 0 actually belongs\nto the last week of the previous year. A date which returns a week of 53 may belong to the\nfirst week of the next year.\n\nDateLeapYear\n$flag = DateLeapYear($y);\n\nReturns 1 if the argument is a leap year Written by David Muir Sharnoff \n\nDateDaySuffix\n$day = DateDaySuffix($d);\n\nAdd `st', `nd', `rd', `th' to a date (i.e. 1st, 22nd, 29th). Works for international dates.\n\nDateTimeZone\n$tz = DateTimeZone;\n\nThis determines and returns the local time zone. If it is unable to determine the local time\nzone, the following error occurs:\n\nERROR: Date::Manip unable to determine Time Zone.\n\nSee The TIME ZONES section below for more information.\n\nDateConvTZ\n$date = DateConvTZ($date);\n$date = DateConvTZ($date,$from);\n$date = DateConvTZ($date,\"\",$to [,$errlev]);\n$date = DateConvTZ($date,$from,$to [,$errlev]);\n\nThis converts a date (which MUST be in the format returned by ParseDate) from one time zone\nto another.\n\nIf it is called with no arguments, the date is converted from the local time zone to the\ntime zone specified by the config variable ConvTZ (see documentation on ConvTZ below). If\nConvTZ is set to \"IGNORE\", no conversion is done.\n\nIf called with $from but no $to, the time zone is converted from the time zone in $from to\nConvTZ (of TZ if ConvTZ is not set). Again, no conversion is done if ConvTZ is set to\n\"IGNORE\".\n\nIf called with $to but no $from, $from defaults to ConvTZ (if set) or the local time zone\notherwise. Although this does not seem immediately obvious, it actually makes sense. By\ndefault, all dates that are parsed are converted to ConvTZ, so most of the dates being\nworked with will be stored in that time zone.\n\nIf DateConvTZ is called with both $from and $to, the date is converted from the time zone\n$from to $to.\n\nNOTE: As in all other cases, the $date returned from DateConvTZ has no time zone\ninformation included as part of it, so calling UnixDate with the \"%z\" format will return the\ntime zone that Date::Manip is working in (usually the local time zone).\n\nExample: To convert 2/2/96 noon PST to CST (regardless of what time zone you are in, do the\nfollowing:\n\n$date = ParseDate(\"2/2/96 noon\");\n$date = DateConvTZ($date,\"PST\",\"CST\");\n\nBoth time zones MUST be in one of the formats listed below in the section TIME ZONES.\n\nIf an error occurs, $errlev determines what happens:\n\n0 : the program dies\n1 : a warning is produced and nothing is returned\n2 : the function silently returns nothing\n\nDateIsWorkDay\n$flag = DateIsWorkDay($date [,$flag]);\n\nThis returns 1 if $date is a work day. If $flag is non-zero, the time is checked to see if\nit falls within work hours. It returns an empty string if $date is not valid.\n\nDateNextWorkDay\n$date = DateNextWorkDay($date,$off [,$flag]);\n\nFinds the day $off work days from now. If $flag is non-zero, we must also take into account\nthe time of day.\n\nIf $flag is zero, day 0 is today (if today is a workday) or the next work day if it isn't.\nIn any case, the time of day is unaffected.\n\nIf $flag is non-zero, day 0 is now (if now is part of a workday) or the start of the very\nnext work day.\n\nDatePrevWorkDay\n$date = DatePrevWorkDay($date,$off [,$flag]);\n\nSimilar to DateNextWorkDay.\n\nDateNearestWorkDay\n$date = DateNearestWorkDay($date [,$tomorrowfirst]);\n\nThis looks for the work day nearest to $date. If $date is a work day, it is returned.\nOtherwise, it will look forward or backwards in time 1 day at a time until a work day is\nfound. If $tomorrowfirst is non-zero (or if it is omitted and the config variable\nTomorrowFirst is non-zero), we look to the future first. Otherwise, we look in the past\nfirst. In other words, in a normal week, if $date is Wednesday, $date is returned. If $date\nis Saturday, Friday is returned. If $date is Sunday, Monday is returned. If Wednesday is a\nholiday, Thursday is returned if $tomorrowfirst is non-nil or Tuesday otherwise.\n\nDateManipVersion\n$version = DateManipVersion;\n\nReturns the version of Date::Manip.\n", "subsections": [] }, "TIME ZONES": { "content": "With the release of Date::Manip 6.00, time zones and daylight saving time are now fully\nsupported in Date::Manip. 6.00 uses information from several standards (most importantly the\nOlson zoneinfo database) to get a list of all known time zones.\n\nUnfortunately, 6.00 requires a newer version of perl, so I will continue to support the 5.xx\nrelease for a while. However, the way I will support time zones in 5.xx has changed. Previously,\nnew time zones would be added on request. That is no longer the case. Time zones for 5.xx are\nnow generated automatically from those available in 6.00.\n\nThe following time zone names are currently understood (and can be used in parsing dates). These\nare zones defined in RFC 822.\n\nUniversal: GMT, UT\nUS zones : EST, EDT, CST, CDT, MST, MDT, PST, PDT\nMilitary : A to Z (except J)\nOther : +HHMM or -HHMM\nISO 8601 : +HH:MM, +HH, -HH:MM, -HH\n\nIn addition, the following time zone abbreviations are also accepted. These do not come from a\nstandard, but were included in previous releases of Date::Manip 5.xx and are preserved here for\nbackward compatibility:\n\nIDLW -1200 International Date Line West\nNT -1100 Nome\nSAT -0400 Chile\nCLDT -0300 Chile Daylight\nAT -0200 Azores\nMEWT +0100 Middle European Winter\nMEZ +0100 Middle European\nFWT +0100 French Winter\nGB +0100 GMT with daylight savings\nSWT +0100 Swedish Winter\nMESZ +0200 Middle European Summer\nFST +0200 French Summer\nMETDST +0200 An alias for MEST used by HP-UX\nEETDST +0300 An alias for eest used by HP-UX\nEETEDT +0300 Eastern Europe, USSR Zone 1\nBT +0300 Baghdad, USSR Zone 2\nIT +0330 Iran\nZP4 +0400 USSR Zone 3\nZP5 +0500 USSR Zone 4\nIST +0530 Indian Standard\nZP6 +0600 USSR Zone 5\nAWST +0800 Australian Western Standard\nROK +0900 Republic of Korea\nAEST +1000 Australian Eastern Standard\nACDT +1030 Australian Central Daylight\nCADT +1030 Central Australian Daylight\nAEDT +1100 Australian Eastern Daylight\nEADT +1100 Eastern Australian Daylight\nNZT +1200 New Zealand\nIDLE +1200 International Date Line East\n\nAll other time zone abbreviations come from the standards. In many cases, an abbreviation may be\nused for multiple time zones. For example, NST stands for Newfoundland Standard -0330 and North\nSumatra +0630. In these cases, only 1 of the two is available. I have tried to use the most\nrecent definition, and of those (if multiple time zones use the abbreviation), the most commonly\nused. I don't claim that I'm correct in all cases, but I've done the best I could.\n\nThe list of abbreviations available is documented in the Date::Manip::DM5abbrevs document.\n\nDate::Manip must be able to determine the time zone the user is in. It does this by looking in\nthe following places:\n\n$Date::Manip::TZ (set with DateInit or in Manip.pm)\n$ENV{TZ}\nthe Unix `date` command (if available)\n$main::TZ\n/etc/TIMEZONE\n/etc/time zone\n\nAt least one of these should contain a time zone in one of the supported forms. If none do by\ndefault, the TZ variable must be set with DateInit.\n\nThe time zone may be in the STD#DST format (in which case both abbreviations must be in the\ntable above) or any of the formats described above. The STD#DST format is NOT available when\nparsing a date however. The following forms are also available and are treated similar to the\nSTD#DST forms:\n\nUS/Pacific\nUS/Mountain\nUS/Central\nUS/Eastern\nCanada/Pacific\nCanada/Mountain\nCanada/Central\nCanada/Eastern\n\nCUSTOMIZING DATE::MANIP\nThere are a number of variables which can be used to customize the way Date::Manip behaves.\nThere are also several ways to set these variables.\n\nAt the top of the Manip.pm file, there is a section which contains all customization variables.\nThese provide the default values.\n\nThese can be overridden in a global config file if one is present (this file is optional). If\nthe GlobalCnf variable is set in the Manip.pm file, it contains the full path to a config file.\nIf the file exists, its values will override those set in the Manip.pm file. A sample config\nfile is included with the Date::Manip distribution. Modify it as appropriate and copy it to some\nappropriate directory and set the GlobalCnf variable in the Manip.pm file.\n\nEach user can have a personal config file which is of the same form as the global config file.\nThe variables PersonalCnf and PersonalCnfPath set the name and search path for the personal\nconfig file. This file is also optional. If present, it overrides any values set in the global\nfile.\n\nNOTE: if you use business mode calculations, you must have a config file (either global or\npersonal) since this is the only place where you can define holidays.\n\nFinally, any variables passed in through DateInit override all other values.\n\nA config file can be composed of several sections. The first section sets configuration\nvariables. Lines in this section are of the form:\n\nVARIABLE = VALUE\n\nFor example, to make the default language French, include the line:\n\nLanguage = French\n\nOnly variables described below may be used. Blank lines and lines beginning with a pound sign\n(#) are ignored. All spaces are optional and strings are case insensitive.\n\nA line which starts with an asterisk (*) designates a new section. For example, the HOLIDAY\nsection starts with a line:\n\n*Holiday\n\nThe various sections are defined below.\n\nDATE::MANIP VARIABLES\nAll Date::Manip variables which can be used are described in the following section.\n\nIgnoreGlobalCnf\nIf this variable is used (any value is ignored), the global config file is not read. It must\nbe present in the initial call to DateInit or the global config file will be read.\n\nEraseHolidays\nIf this variable is used (any value is ignored), the current list of defined holidays is\nerased. A new set will be set the next time a config file is read in. This can be set in\neither the global config file or as a DateInit argument (in which case holidays can be read\nin from both the global and personal config files) or in the personal config file (in which\ncase, only holidays in the personal config file are counted).\n\nPathSep\nThis is a regular expression used to separate multiple paths. For example, on Unix, it\ndefaults to a colon (:) so that multiple paths can be written PATH1:PATH2 . For Win32\nplatforms, it defaults to a semicolon (;) so that paths such as \"c:\\;d:\\\" will work.\n\nGlobalCnf\nThis variable can be passed into DateInit to point to a global configuration file. The\nvalue must be the complete path to a config file.\n\nBy default, no global config file is read. Any time a global config file is read, the\nholidays are erased.\n\nPaths may have a tilde (~) expansion on platforms where this is supported (currently Unix\nand VMS).\n\nPersonalCnf\nThis variable can be passed into DateInit or set in a global config file to set the name of\nthe personal configuration file.\n\nThe default name for the config file is .DateManip.cnf on all Unix platforms and Manip.cnf\non all non-Unix platforms (because some of them insist on 8.3 character filenames :-).\n\nPersonalCnfPath\nThis is a list of paths separated by the separator specified by the PathSep variable. These\npaths are each checked for the PersonalCnf config file.\n\nPaths may have a tilde (~) expansion on platforms where this is supported (currently Unix\nand VMS).\n\nLanguage\nDate::Manip can be used to parse dates in many different languages. Currently, it is\nconfigured to read the following languages (the version in which they added is included for\nhistorical interest):\n\nEnglish (default)\nFrench (5.02)\nSwedish (5.05)\nGerman (5.31)\nDutch (5.32) aka Nederlands\nPolish (5.32)\nSpanish (5.33)\nPortuguese (5.34)\nRomanian (5.35)\nItalian (5.35)\nRussian (5.41)\nTurkish (5.41)\nDanish (5.41)\n\nOthers can be added easily. Language is set to the language used to parse dates. If you are\ninterested in providing a translation for a new language, email me (see the AUTHOR section\nbelow) and I'll send you a list of things that I need.\n\nDateFormat\nDifferent countries look at the date 12/10 as Dec 10 or Oct 12. In the United States, the\nfirst is most common, but this certainly doesn't hold true for other countries. Setting\nDateFormat to \"US\" forces the first behavior (Dec 10). Setting DateFormat to anything else\nforces the second behavior (Oct 12).\n\nTZ If set, this defines the local time zone. See the TIME ZONES section above for information\non its format.\n\nConvTZ\nAll date comparisons and calculations must be done in a single time zone in order for them\nto work correctly. So, when a date is parsed, it should be converted to a specific time\nzone. This allows dates to easily be compared and manipulated as if they are all in a single\ntime zone.\n\nThe ConvTZ variable determines which time zone should be used to store dates in. If it is\nleft blank, all dates are converted to the local time zone (see the TZ variable above). If\nit is set to one of the time zones listed above, all dates are converted to this time zone.\nFinally, if it is set to the string \"IGNORE\", all time zone information is ignored as the\ndates are read in (in this case, the two dates \"1/1/96 12:00 GMT\" and \"1/1/96 12:00 EST\"\nwould be treated as identical).\n\nInternal\nWhen a date is parsed using ParseDate, that date is stored in an internal format which is\nunderstood by the Date::Manip routines UnixDate and DateCalc. Originally, the format used to\nstore the date internally was:\n\nYYYYMMDDHH:MN:SS\n\nIt has been suggested that I remove the colons (:) to shorten this to:\n\nYYYYMMDDHHMNSS\n\nThe main advantage of this is that some databases are colon delimited which makes storing a\ndate from Date::Manip tedious.\n\nIn order to maintain backwards compatibility, the Internal variable was introduced. Set it\nto 0 (to use the old format) or 1 (to use the new format).\n\nFirstDay\nIt is sometimes necessary to know what day of week is regarded as first. By default, this is\nset to Monday, but many countries and people will prefer Sunday (and in a few cases, a\ndifferent day may be desired). Set the FirstDay variable to be the first day of the week\n(1=Monday, 7=Sunday) Monday should be chosen to to comply with ISO 8601.\n\nWorkWeekBeg, WorkWeekEnd\nThe first and last days of the work week. By default, Monday and Friday. WorkWeekBeg must\ncome before WorkWeekEnd numerically. The days are numbered from 1 (Monday) to 7 (Sunday).\n\nThere is no way to handle an odd work week of Thu to Mon for example or 10 days on, 4 days\noff.\n\nWorkDay24Hr\nIf this is non-nil, a work day is treated as being 24 hours long. The WorkDayBeg and\nWorkDayEnd variables are ignored in this case.\n\nWorkDayBeg, WorkDayEnd\nThe times when the work day starts and ends. WorkDayBeg must come before WorkDayEnd (i.e.\nthere is no way to handle the night shift where the work day starts one day and ends\nanother). Also, the workday MUST be more than one hour long (of course, if this isn't the\ncase, let me know... I want a job there!).\n\nThe time in both can be in any valid time format (including international formats), but\nseconds will be ignored.\n\nTomorrowFirst\nPeriodically, if a day is not a business day, we need to find the nearest business day to\nit. By default, we'll look to \"tomorrow\" first, but if this variable is set to 0, we'll look\nto \"yesterday\" first. This is only used in the DateNearestWorkDay and is easily overridden\n(see documentation for that function).\n\nDeltaSigns\nPrior to Date::Manip version 5.07, a negative delta would put negative signs in front of\nevery component (i.e. \"0:0:-1:-3:0:-4\"). By default, 5.07 changes this behavior to print\nonly 1 or two signs in front of the year and day elements (even if these elements might be\nzero) and the sign for year/month and day/hour/minute/second are the same. Setting this\nvariable to non-zero forces deltas to be stored with a sign in front of every element\n(including elements equal to 0).\n\nJan1Week1\nISO 8601 states that the first week of the year is the one which contains Jan 4 (i.e. it is\nthe first week in which most of the days in that week fall in that year). This means that\nthe first 3 days of the year may be treated as belonging to the last week of the previous\nyear. If this is set to non-nil, the ISO 8601 standard will be ignored and the first week of\nthe year contains Jan 1.\n\nYYtoYYYY\nBy default, a 2 digit year is treated as falling in the 100 year period of CURR-89 to\nCURR+10. YYtoYYYY may be set to any integer N to force a 2 digit year into the period CURR-N\nto CURR+(99-N). A value of 0 forces the year to be the current year or later. A value of 99\nforces the year to be the current year or earlier. Since I do no checking on the value of\nYYtoYYYY, you can actually have it any positive or negative value to force it into any\ncentury you want.\n\nYYtoYYYY can also be set to \"C\" to force it into the current century, or to \"C##\" to force\nit into a specific century. So, in 1998, \"C\" forces 2 digit years to be 1900-1999 and \"C18\"\nwould force it to be 1800-1899.\n\nIt can also be set to the form \"C####\" to force it into a specific 100 year period. C1950\nrefers to 1950-2049.\n\nUpdateCurrTZ\nIf a script is running over a long period of time, the time zone may change during the\ncourse of running it (i.e. when daylight saving time starts or ends). As a result, parsing\ndates may start putting them in the wrong time zone. Since a lot of overhead can be saved if\nwe don't have to check the current time zone every time a date is parsed, by default\nchecking is turned off. Setting this to non-nil will force time zone checking to be done\nevery time a date is parsed... but this will result in a considerable performance penalty.\n\nA better solution would be to restart the process on the two days per year where the time\nzone switch occurs.\n\nIntCharSet\nIf set to 0, use the US character set (7-bit ASCII) to return strings such as the month\nname. If set to 1, use the appropriate international character set. For example, If you want\nyour French representation of December to have the accent over the first \"e\", you'll want to\nset this to 1.\n\nForceDate\nThis variable can be set to a date in the format: YYYY-MM-DD-HH:MN:SS to force the current\ndate to be interpreted as this date. Since the current date is used in parsing, this string\nwill not be parsed and MUST be in the format given above.\n\nTodayIsMidnight\nIf set to a true value (e.g. 1), then \"today\" will mean the same as \"midnight today\";\notherwise it will mean the same as \"now\".\n", "subsections": [] }, "HOLIDAY SECTION": { "content": "The holiday section of the config file is used to define holidays. Each line is of the form:\n\nDATE = HOLIDAY\n\nHOLIDAY is the name of the holiday (or it can be blank in which case the day will still be\ntreated as a holiday... for example the day after Thanksgiving or Christmas is often a work\nholiday though neither are named).\n\nDATE is a string which can be parsed to give a valid date in any year. It can be of the form\n\nDate\nDate + Delta\nDate - Delta\nRecur\n\nA valid holiday section would be:\n\n*Holiday\n\n1/1 = New Year's Day\nthird Monday in Feb = Presidents' Day\nfourth Thu in Nov = Thanksgiving\n\n# The Friday after Thanksgiving is an unnamed holiday most places\nfourth Thu in Nov + 1 day =\n\n1*0:0:0:0:0:0*EASTER = Easter\n1*11:0:11:0:0:0*DWD = Veteran's Day (observed)\n1*0:0:0:0:0:0*EASTER,PD5 = Good Friday\n\nIn a Date + Delta or Date - Delta string, you can use business mode by including the appropriate\nstring (see documentation on DateCalc) in the Date or Delta. So (in English), the first workday\nbefore Christmas could be defined as:\n\n12/25 - 1 business day =\n\nThe dates may optionally contain the year. For example, the dates\n\n1/1\n1/1/1999\n\nrefers to Jan 1 in any year or in only 1999 respectively. For dates that refer to any year, the\ndate must be written such that by simply appending the year (separated by spaces) it can be\ncorrectly interpreted. This will work for everything except ISO 8601 dates, so ISO 8601 dates\nmay not be used in this case.\n\nNote that the dates are specified in whatever format is set using the DateInit options, so if\nthe standard parsing is D/M/YYYY, you would need to specify it as:\n\n25/12/2002 = Christmas\n\nIn cases where you are interested in business type calculations, you'll want to define most\nholidays using recurrences, since they can define when a holiday is celebrated in the financial\nworld. For example, Christmas should be defined as:\n\n1*12:0:24:0:0:0*FW1 = Christmas\n\nNOTE: It was pointed out to me that using a similar type recurrence to define New Years does not\nwork. The recurrence:\n\n1*12:0:31:0:0:0*FW1\n\nfails (worse, it goes into an infinite loop). The problem is that each holiday definition is\napplied to a specific year and it expects to find the holiday for that year. When this\nrecurrence is applied to the year 1995, it returns the holiday for 1996 and fails.\n\nUse the recurrence:\n\n1*1:0:1:0:0:0*NWD\n\ninstead.\n\nIf you wanted to define both Christmas and Boxing days (Boxing is the day after Christmas, and\nis celebrated in some parts of the world), you could do it in one of the following ways:\n\n1*12:0:24:0:0:0*FW1 = Christmas\n1*12:0:25:0:0:0*FW1 = Boxing\n\n1*12:0:24:0:0:0*FW1 = Christmas\n01*12:0:24:0:0:0*FW1 = Boxing\n\n1*12:0:24:0:0:0*FW1 = Christmas\n1*12:0:25:0:0:0*FW1,a = Boxing\n\nThe following examples will NOT work:\n\n1*12:0:24:0:0:0*FW1 = Christmas\n1*12:0:24:0:0:0*FW2 = Boxing\n\n1*12:0:24:0:0:0*FW1 = Christmas\n1*12:0:24:0:0:0*FW1 = Boxing\n\nThe reasoning behind all this is as follows:\n\nHolidays go into affect the minute they are parsed. So, in the case of:\n\n1*12:0:24:0:0:0*FW1 = Christmas\n1*12:0:24:0:0:0*FW2 = Boxing\n\nthe minute the first line is parsed, Christmas is defined as a holiday. The second line then\nsteps forward 2 work days (skipping Christmas since that's no longer a work day) and define the\nwork day two days after Christmas, NOT the day after Christmas.\n\nAn good alternative would appear to be:\n\n1*12:0:24:0:0:0*FW1 = Christmas\n1*12:0:24:0:0:0*FW1 = Boxing\n\nThis unfortunately fails because the recurrences are currently stored in a hash. Since these two\nrecurrences are identical, they fail (the first one is overwritten by the second and in essence,\nChristmas is never defined).\n\nTo fix this, make them unique with either a fake flag (which is ignored):\n\n1*12:0:24:0:0:0*FW1,a = Boxing\n\nor adding an innocuous 0 somewhere:\n\n01*12:0:24:0:0:0*FW1 = Boxing\n\nThe other good alternative would be to make two completely different recurrences such as:\n\n1*12:0:24:0:0:0*FW1 = Christmas\n1*12:0:25:0:0:0*FW1 = Boxing\n\nAt times, you may want to switch back and forth between two holiday files. This can be done by\ncalling the following:\n\nDateInit(\"EraseHolidays=1\",\"PersonalCnf=FILE1\");\n...\nDateInit(\"EraseHolidays=1\",\"PersonalCnf=FILE2\");\n...\n", "subsections": [] }, "EVENTS SECTION": { "content": "The Events section of the config file is similar to the Holiday section. It is used to name\ncertain days or times, but there are a few important differences:\n\nEvents can be assigned to any time and duration\nAll holidays are exactly 1 day long. They are assigned to a period of time from midnight to\nmidnight.\n\nEvents can be based at any time of the day, and may be of any duration.\n\nEvents don't affect business mode calculations\nUnlike holidays, events are completely ignored when doing business mode calculations.\n\nWhereas holidays were added with business mode math in mind, events were added with calendar and\nscheduling applications in mind.\n\nEvery line in the events section is of the form:\n\nEVENT = NAME\n\nwhere NAME is the name of the event, and EVENT defines when it occurs and its duration. An EVENT\ncan be defined in the following ways:\n\nDate\nDate*\n\nDate ; Date\nDate ; Delta\n\nHere, Date* refers to a string containing a Date with NO TIME fields (Jan 12, 1/1/2000,\n2010-01-01) while Date does contain time fields. Similarly, Recur* stands for a recurrence with\nthe time fields all equal to 0) while Recur stands for a recurrence with at least one non-zero\ntime field.\n\nBoth Date* and Recur* refer to an event very similar to a holiday which goes from midnight to\nmidnight.\n\nDate and Recur refer to events which occur at the time given and with a duration of 1 hour.\n\nEvents given by \"Date ; Date\", \"Date ; Delta\", and \"Recur ; Delta\" contain both the starting\ndate and either ending date or duration.\n\nEvents given as three elements \"Date ; Delta ; Delta\" or \"Recur ; Delta ; Delta\" take a date and\nadd both deltas to it to give the starting and ending time of the event. The order and sign of\nthe deltas is unimportant (and both can be the same sign to give a range of times which does not\ncontain the base date).\n", "subsections": [] }, "KNOWN PROBLEMS": { "content": "The following are not bugs in Date::Manip, but they may give some people problems.\n\nUnable to determine Time Zone\nPerhaps the most common problem occurs when you get the error:\n\nError: Date::Manip unable to determine Time Zone.\n\nDate::Manip tries hard to determine the local time zone, but on some machines, it cannot do\nthis (especially non-Unix systems). To fix this, just set the TZ variable, either at the top\nof the Manip.pm file, in the DateManip.cnf file, or in a call to DateInit. I suggest using\nthe form \"EST5EDT\" so you don't have to change it every 6 months when going to or from\ndaylight saving time.\n\nWindows NT does not seem to set the time zone by default. From the Perl-Win32-Users mailing\nlist:\n\n> How do I get the TimeZone on my NT?\n>\n> $timezone = $ENV{'TZ'};\n>\nYou have to set the variable before, WinNT doesn't set it by\ndefault. Open the properties of \"My Computer\" and set a SYSTEM\nvariable TZ to your time zone. Jenda@Krynicky.cz\n\nThis might help out some NT users.\n\nA minor (false) assumption that some users might make is that since Date::Manip passed all\nof its tests at install time, this should not occur and are surprised when it does.\n\nSome of the tests are time zone dependent. Since the tests all include input and expected\noutput, I needed to know in advance what time zone they would be run in. So, the tests all\nexplicitly set the time zone using the TZ configuration variable passed into DateInit.\nSince this overrides any other method of determining the time zone, Date::Manip uses this\nand doesn't have to look elsewhere for the time zone.\n\nWhen running outside the tests, Date::Manip has to rely on its other methods for determining\nthe time zone.\n\nMissing date formats\nPlease see the Date::Manip::Problems document for a discussion.\n\nComplaining about getpwnam/getpwuid\nAnother problem is when running on Micro$oft OS's. I have added many tests to catch them,\nbut they still slip through occasionally. If any ever complain about getpwnam/getpwuid,\nsimply add one of the lines:\n\n$ENV{OS} = WindowsNT\n$ENV{OS} = Windows95\n\nto your script before\n\nuse Date::Manip\n\nDate::Manip is slow\nThe reasons for this are covered in the SHOULD I USE DATE::MANIP section above.\n\nSome things that will definitely help:\n\nVersion 5.21 does run noticeably faster than earlier versions due to rethinking some of the\ninitialization, so at the very least, make sure you are running this version or later.\n\nISO-8601 dates are parsed first and fastest. Use them whenever possible.\n\nAvoid parsing dates that are referenced against the current time (in 2 days, today at noon,\netc.). These take a lot longer to parse.\n\nExample: parsing 1065 dates with version 5.11 took 48.6 seconds, 36.2\nseconds with version 5.21, and parsing 1065 ISO-8601 dates with version\n5.21 took 29.1 seconds (these were run on a slow, overloaded computer with\nlittle memory... but the ratios should be reliable on a faster computer).\n\nBusiness date calculations are extremely slow. You should consider alternatives if possible\n(i.e. doing the calculation in exact mode and then multiplying by 5/7). Who needs a business\ndate more accurate than \"6 to 8 weeks\" anyway, right :-)\n\nNever call DateInit more than once. Unless you're doing something very strange, there\nshould never be a reason to anyway.\n\nSorting Problems\nIf you use Date::Manip to sort a number of dates, you must call DateInit either explicitly,\nor by way of some other Date::Manip routine before it is used in the sort. For example, the\nfollowing code fails:\n\nuse Date::Manip;\n# DateInit;\nsub sortDate {\nmy($date1, $date2);\n$date1 = ParseDate($a);\n$date2 = ParseDate($b);\nreturn (DateCmp($date1,$date2));\n}\n@dates = (\"Fri 16 Aug 96\",\n\"Mon 19 Aug 96\",\n\"Thu 15 Aug 96\");\n@i=sort sortDate @dates;\n\nbut if you uncomment the DateInit line, it works. The reason for this is that the first\ntime you call DateInit, it initializes a number of items used by Date::Manip. Some of these\nhave to be sorted (regular expressions sorted by length to ensure the longest match). It\nturns out that Perl has a bug in it which does not allow a sort within a sort. At some\npoint, this should be fixed, but for now, the best thing to do is to call DateInit\nexplicitly. The bug exists in all versions up to 5.005 (I haven't tested 5.6.0 yet).\n\nNOTE: This is an EXTREMELY inefficient way to sort data (but read the 2nd note below for an\neasy way to correct this). Instead, you should parse the dates with ParseDate, sort them\nusing a normal string comparison, and then convert them back to the format desired using\nUnixDate.\n\nNOTE: It has been reported to me that you can still use ParseDate to sort dates in this way,\nand be quite efficient through the use of Memoize. Just add the following lines to your\ncode:\n\nuse Date::Manip;\nuse Memoize;\nmemoize('ParseDate');\n...\n@i=sort sortDate @dates;\n\nSince sortDate would call ParseDate with the same data over and over, this is a perfect\napplication for the Memoize module. So, sorting with ParseDate is no longer slow for\nsorting.\n\nRCS Control\nIf you try to put Date::Manip under RCS control, you are going to have problems. Apparently,\nRCS replaces strings of the form \"$Date...$\" with the current date. This form occurs all\nover in Date::Manip. To prevent the RCS keyword expansion, checkout files using \"co -ko\".\nSince very few people will ever have a desire to do this (and I don't use RCS), I have not\nworried about it.\n", "subsections": [] }, "KNOWN BUGS": { "content": "Daylight Saving Times\nDate::Manip does not handle daylight saving time, though it does handle time zones to a\ncertain extent. Converting from EST to PST works fine. Going from EST to PDT is unreliable.\n\nThe following examples are run in the winter of the US East coast (i.e. in the EST time\nzone).\n\nprint UnixDate(ParseDate(\"6/1/97 noon\"),\"%u\"),\"\\n\";\n=> Sun Jun 1 12:00:00 EST 1997\n\nJune 1 EST does not exist. June 1st is during EDT. It should print:\n\n=> Sun Jun 1 00:00:00 EDT 1997\n\nEven explicitly adding the time zone doesn't fix things (if anything, it makes them worse):\n\nprint UnixDate(ParseDate(\"6/1/97 noon EDT\"),\"%u\"),\"\\n\";\n=> Sun Jun 1 11:00:00 EST 1997\n\nDate::Manip converts everything to the current time zone (EST in this case).\n\nRelated problems occur when trying to do date calculations over a time zone change. These\ncalculations may be off by an hour.\n\nAlso, if you are running a script which uses Date::Manip over a period of time which starts\nin one time zone and ends in another (i.e. it switches form Daylight Saving Time to Standard\nTime or vice versa), many things may be wrong (especially elapsed time).\n\nThese problems will not be fixed in Date::Manip 5.xx. Date::Manip 6.xx has full support for\ntime zones and daylight saving time.\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": [] } }, "summary": "Date::Manip::DM5 - Date manipulation routines", "flags": [], "examples": [], "see_also": [] }