--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/dummy_foundation/lib/Date/Manip.pod Thu May 28 10:10:03 2009 +0100
@@ -0,0 +1,2755 @@
+# Copyright (c) 1995-2003 Sullivan Beck. All rights reserved.
+# This program is free software; you can redistribute it and/or modify it
+# under the same terms as Perl itself.
+
+=head1 NAME
+
+Date::Manip - date manipulation routines
+
+=head1 SYNOPSIS
+
+ use Date::Manip;
+
+ $date = ParseDate(\@args);
+ $date = ParseDate($string);
+ $date = ParseDate(\$string);
+
+ @date = UnixDate($date,@format);
+ $date = UnixDate($date,@format);
+
+ $delta = ParseDateDelta(\@args);
+ $delta = ParseDateDelta($string);
+ $delta = ParseDateDelta(\$string);
+
+ @str = Delta_Format($delta,$dec,@format);
+ $str = Delta_Format($delta,$dec,@format);
+
+ $recur = ParseRecur($string,$base,$date0,$date1,$flags);
+ @dates = ParseRecur($string,$base,$date0,$date1,$flags);
+
+ $flag = Date_Cmp($date1,$date2);
+
+ $d = DateCalc($d1,$d2 [,$errref] [,$del]);
+
+ $date = Date_SetTime($date,$hr,$min,$sec);
+ $date = Date_SetTime($date,$time);
+
+ $date = Date_SetDateField($date,$field,$val [,$nocheck]);
+
+ $date = Date_GetPrev($date,$dow,$today,$hr,$min,$sec);
+ $date = Date_GetPrev($date,$dow,$today,$time);
+
+ $date = Date_GetNext($date,$dow,$today,$hr,$min,$sec);
+ $date = Date_GetNext($date,$dow,$today,$time);
+
+ $version = DateManipVersion;
+
+ $flag = Date_IsWorkDay($date [,$flag]);
+
+ $date = Date_NextWorkDay($date,$off [,$time]);
+ $date = Date_PrevWorkDay($date,$off [,$time]);
+
+ $name = Date_IsHoliday($date);
+
+ $listref = Events_List($date);
+ $listref = Events_List($date0,$date1);
+
+ &Date_Init();
+ &Date_Init("VAR=VAL","VAR=VAL",...);
+ @list = Date_Init();
+ @list = Date_Init("VAR=VAL","VAR=VAL",...);
+
+The above routines all check to make sure that Date_Init is called. If it
+hasn't been, they will call it automatically. As a result, there is usually
+no need to call Date_Init explicitely unless you want to change some of the
+config variables (described below).
+
+The following routines are used by the above routines (though they can also
+be called directly). $y may be entered as either a 2 or 4 digit year (it
+will be converted to a 4 digit year based on the variable YYtoYYYY
+described below). Month and day should be numeric in all cases. Most (if
+not all) of the information below can be gotten from UnixDate which is
+really the way I intended it to be gotten, but there are reasons to use
+these (these are significantly faster).
+
+***NOTE*** Unlike the routines listed above, the following routines do NOT
+explicitely call Date_Init. You must make sure that Date_Init has been
+called, either by you explicitely, or by one of the above routines before you
+use these routines.
+
+ $day = Date_DayOfWeek($m,$d,$y);
+ $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
+ $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
+ $days = Date_DaysSince1BC($m,$d,$y);
+ $day = Date_DayOfYear($m,$d,$y);
+ $days = Date_DaysInYear($y);
+ $wkno = Date_WeekOfYear($m,$d,$y,$first);
+ $flag = Date_LeapYear($y);
+ $day = Date_DaySuffix($d);
+ $tz = Date_TimeZone();
+ ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
+
+=head1 DESCRIPTION
+
+This is a set of routines designed to make any common date/time
+manipulation easy to do. Operations such as comparing two times,
+calculating a time a given amount of time from another, or parsing
+international times are all easily done. From the very beginning, the main
+focus of Date::Manip has been to be able to do ANY desired date/time
+operation easily, not necessarily quickly. Also, it is definitely oriented
+towards the type of operations we (as people) tend to think of rather than
+those operations used routinely by computers. There are other modules that
+can do a subset of the operations available in Date::Manip much quicker
+than those presented here, so be sure to read the section SHOULD I USE
+DATE::MANIP below before deciding which of the Date and Time modules from
+CPAN is for you.
+
+Date::Manip deals with time as it is presented the Gregorian calendar (the
+one currently in use). The Julian calendar defined leap years as every 4th
+year. The Gregorian calendar improved this by making every 100th year NOT
+a leap year, unless it was also the 400th year. The Gregorian calendar has
+been extrapolated back to the year 0000 AD and forward to the year 9999 AD.
+Note that in historical context, the Julian calendar was in use until 1582
+when the Gregorian calendar was adopted by the Catholic church. Protestant
+countries did not accept it until later; Germany and Netherlands in 1698,
+British Empire in 1752, Russia in 1918. Note that the Gregorian calendar
+is itself imperfect and at some point will need to be corrected. No attempt
+is made to correct for that, and my great great great grandchildren will be
+long dead before this even occurs, so it's not an immediate concern. Yes,
+this is the same type of attitute that caused the great Y2K problem... but
+I have an excuse: I don't know what the correction will be, so I can't
+possible implement it. Nobody doubted that the year after 1999 would be
+known as 2000 :-).
+
+Date::Manip is therefore not equipped to truly deal with historical dates,
+but should be able to perform (virtually) any operation dealing with a
+modern time and date.
+
+Date::Manip has (or will have) functionality to work with several fundamental
+types of data.
+
+=over 4
+
+=item DATE
+
+Although the word date is used extensively here, it is actually somewhat
+misleading. Date::Manip works with the full date AND time (year, month,
+day, hour, minute, second and weeks when appropriate). It doesn't work
+with fractional seconds. Timezones are also supported to some extent.
+
+NOTE: Much better support for timezones (including Daylight Savings Time)
+is planned for the future.
+
+=item DELTA
+
+This refers to a duration or elapsed time. One thing to note is that, as
+used in this module, a delta refers only to the amount of time elapsed. It
+includes no information about a starting or ending time.
+
+=item RECURRENCE
+
+A recurrence is simply a notation for defining when a recurring event
+occurs. For example, if an event occurs every other Friday or every
+4 hours, this can be defined as a recurrence. With a recurrence and a
+starting and ending date, you can get a list of dates in that period when
+a recurring event occurs.
+
+=item GRAIN
+
+The granularity of a time basically refers to how accurate you wish to
+treat a date. For example, if you want to compare two dates to see if
+they are identical at a granularity of days, then they only have to occur
+on the same day. At a granularity of an hour, they have to occur within
+an hour of each other, etc.
+
+NOTE: Support for this will be added in the future.
+
+=item HOLIDAYS and EVENTS
+
+These are basically a named time. Holidays are used in business mode
+calculations. Events allow things like calendar and scheduling
+applications to be designed much more easily.
+
+=back
+
+Among other things, Date::Manip allow you to:
+
+1. Enter a date and be able to choose any format convenient
+
+2. Compare two dates, entered in widely different formats
+ to determine which is earlier
+
+3. Extract any information you want from ANY date using a
+ format string similar to the Unix date command
+
+4. Determine the amount of time between two dates
+
+5. Add a time offset to a date to get a second date (i.e.
+ determine the date 132 days ago or 2 years and 3 months
+ after Jan 2, 1992)
+
+6. Work with dates with dates using international formats
+ (foreign month names, 12/10/95 referring to October
+ rather than December, etc.).
+
+7. To find a list of dates where a recurring event happens.
+
+Each of these tasks is trivial (one or two lines at most) with this package.
+
+=head1 EXAMPLES
+
+In the documentation below, US formats are used, but in most (if not all)
+cases, a non-English equivalent will work equally well.
+
+1. Parsing a date from any convenient format
+
+ $date = ParseDate("today");
+ $date = ParseDate("1st thursday in June 1992");
+ $date = ParseDate("05/10/93");
+ $date = ParseDate("12:30 Dec 12th 1880");
+ $date = ParseDate("8:00pm december tenth");
+ if (! $date) {
+ # Error in the date
+ }
+
+2. Compare two dates
+
+ $date1 = ParseDate($string1);
+ $date2 = ParseDate($string2);
+ $flag = Date_Cmp($date1,$date2);
+ if ($flag<0) {
+ # date1 is earlier
+ } elsif ($flag==0) {
+ # the two dates are identical
+ } else {
+ # date2 is earlier
+ }
+
+3. Extract information from a date.
+
+ print &UnixDate("today","It is now %T on %b %e, %Y.");
+ => "It is now 13:24:08 on Feb 3, 1996."
+
+4. The amount of time between two dates.
+
+ $date1 = ParseDate($string1);
+ $date2 = ParseDate($string2);
+ $delta = DateCalc($date1,$date2,\$err);
+ => 0:0:WK:DD:HH:MM:SS the weeks, days, hours, minutes,
+ and seconds between the two
+ $delta = DateCalc($date1,$date2,\$err,1);
+ => YY:MM:WK:DD:HH:MM:SS the years, months, etc. between
+ the two
+
+ Read the documentation below for an explanation of the
+ difference.
+
+5. To determine a date a given offset from another.
+
+ $date = DateCalc("today","+ 3hours 12minutes 6 seconds",\$err);
+ $date = DateCalc("12 hours ago","12:30 6Jan90",\$err);
+
+ It even works with business days:
+
+ $date = DateCalc("today","+ 3 business days",\$err);
+
+6. To work with dates in another language.
+
+ &Date_Init("Language=French","DateFormat=non-US");
+ $date = ParseDate("1er decembre 1990");
+
+7. To find a list of dates where a recurring event happens
+ (including quite complex ones).
+
+ # To find the 2nd tuesday of every month
+ @date = ParseRecur("0:1*2:2:0:0:0",$base,$start,$stop);
+
+ # To find the Monday after easter in 1997-1999.
+ @date = ParseRecur("*1997-1999:0:0:0:0:0:0*EASTER,ND1");
+
+NOTE: Some date forms do not work as well in languages other than English,
+but this is not because Date::Manip is incapable of doing so (almost nothing
+in this module is language dependent). It is simply that I do not have the
+correct translation available for some words. If there is a date form that
+works in English but does not work in a language you need, let me know and
+if you can provide me the translation, I will fix Date::Manip.
+
+=head1 SHOULD I USE DATE::MANIP
+
+If you look in CPAN, you'll find that there are a number of Date and Time
+packages. Is Date::Manip the one you should be using? In my opinion, the
+answer is no most of the time. This sounds odd coming from the author of
+the software, but read on.
+
+Date::Manip is written entirely in perl. It's the most powerful of the
+date modules. It's also the biggest and slowest.
+
+Since Date::Manip is written entirely in perl, and depends on no other
+module not in a standard perl distribution, Date::Manip has no dependancies
+to meet. Other modules have dependancies on a C compiler or other perl
+modules. Since it is fairly easy to satisfy these dependancies for
+anyone who is reasonably familiar with perl modules, this is not a
+huge advantage that Date::Manip has.
+
+On the other hand, simpler perl modules tend to be faster than Date::Manip,
+and modules written in C are significantly faster than their perl
+counterparts (at least if they're done right). The TimeDate and
+Time-modules modules are written in perl, but are much simpler (and
+hence, faster) than Date::Manip. The Date::Calc module is written in C
+and is a good module for doing many date calculations much faster than
+Date::Manip. Between these three, most of your common date operations
+can be done.
+
+Date::Manip is certainly the most powerful of the Date modules. To the
+best of my knowledge, it will do everything that any other date module will
+do (not just the ones I listed above), and there are a number of features
+that Date::Manip has that none of the other modules have. Date::Manip is
+the "Swiss Army Knife" of Date modules. I'm trying to build a library
+which can do _EVERY_ conceivable date/time manipulation that you'll run
+into in everyday life.
+
+Although I am working on making Date::Manip faster, it will never be as
+fast as other modules. And before anyone asks, Date::Manip will never
+be translated to C (at least by me). I write C because I have to. I
+write perl because I like to. Date::Manip is something I do because it
+interests me, not something I'm paid for.
+
+Date::Manip is also big. The last time I looked, it's one of the largest
+CPAN modules there is. If you ignore modules like Tk, LWP, etc. which are
+actually packages of modules, it may be the largest. It's true that
+Date::Manip will do almost every date operation you could imagine... but
+you rarely need all that power. I'm working on reducing the footprint of
+Date::Manip, but even at it's slimmest, it'll outweigh the other modules by
+a good bit.
+
+If you are going to be using the module in cases where performance is an
+important factor (started up in a CGI program being run by your web server
+5,000 times a second), you should check out one of the other Date or Time
+modules in CPAN. If you're only doing fairly simple date operations
+(parsing common date formats, finding the difference between two dates,
+etc.), the other modules will almost certainly suffice. If you're doing
+one operation very repetitively (parsing 10,000 dates from a database), you
+are probably better off writing your own functions (perhaps bypassing all
+date modules entirely) designed specifically for your needs.
+
+On the other hand, if you want one solution for all your date needs, don't
+need peak speed, or are trying to do more exotic date operations,
+Date::Manip is for you. Operations on things like business dates, foreign
+language dates, holidays and other recurring events, etc. are available
+more-or-less exclusively in Date::Manip.
+
+=head1 ROUTINES
+
+=over 4
+
+=item ParseDate
+
+ $date = ParseDate(\@args);
+ $date = ParseDate($string);
+ $date = ParseDate(\$string);
+
+This takes an array or a string containing a date and parses it. When the
+date is included as an array (for example, the arguments to a program) the
+array should contain a valid date in the first one or more elements
+(elements after a valid date are ignored). Elements containing a valid
+date are shifted from the array. The largest possible number of elements
+which can be correctly interpreted as a valid date are always used. If a
+string is entered rather than an array, that string is tested for a valid
+date. The string is unmodified, even if passed in by reference.
+
+The real work is done in the ParseDateString routine.
+
+The ParseDate routine is primarily used to handle command line arguments.
+If you have a command where you want to enter a date as a command line
+argument, you can use Date::Manip to make something like the following
+work:
+
+ mycommand -date Dec 10 1997 -arg -arg2
+
+No more reading man pages to find out what date format is required in a
+man page.
+
+Historical note: this is originally why the Date::Manip routines were
+written (though long before they were released as the Date::Manip module).
+I was using a bunch of programs (primarily batch queue managers) where
+dates and times were entered as command line options and I was getting
+highly annoyed at the many different (but not compatible) ways that they
+had to be entered. Date::Manip originally consisted of basically 1 routine
+which I could pass "@ARGV" to and have it remove a date from the beginning.
+
+=item ParseDateString
+
+ $date = ParseDateString($string);
+
+This routine is called by ParseDate, but it may also be called directly
+to save some time (a negligable amount).
+
+NOTE: One of the most frequently asked questions that I have gotten
+is how to parse seconds since the epoch. ParseDateString cannot simply
+parse a number as the seconds since the epoch (it conflicts with some
+ISO-8601 date formats). There are two ways to get this information.
+First, you can do the following:
+
+ $secs = ... # seconds since Jan 1, 1970 00:00:00 GMT
+ $date = &DateCalc("Jan 1, 1970 00:00:00 GMT",$secs);
+
+Second, you can call it directly as:
+
+ $date = &ParseDateString("epoch $secs");
+
+To go backwards, just use the "%s" format of UnixDate:
+
+ $secs = &UnixDate($date,"%s");
+
+A full date actually includes 2 parts: date and time. A time must include
+hours and minutes and can optionally include seconds, fractional seconds,
+an am/pm type string, and a timezone. For example:
+
+ [at] HH:MN [Zone]
+ [at] HH:MN [am] [Zone]
+ [at] HH:MN:SS [am] [Zone]
+ [at] HH:MN:SS.SSSS [am] [Zone]
+ [at] HH am [Zone]
+
+Hours can be written using 1 or 2 digits, but the single digit form may
+only be used when no ambiguity is introduced (i.e. when it is not
+immediately preceded by a digit).
+
+A time is usually entered in 24 hour mode, but 12 hour mode can be used
+as well if AM/PM are entered (AM can be entered as AM or A.M. or other
+variations depending on the language).
+
+Fractional seconds are also supported in parsing but the fractional part is
+discarded (with NO rounding ocurring).
+
+Timezones always appear immediately after the time. A number of different
+forms are supported (see the section TIMEZONEs below).
+
+Incidentally, the time is removed from the date before the date is parsed,
+so the time may appear before or after the date, or between any two parts
+of the date.
+
+Valid date formats include the ISO 8601 formats:
+
+ YYYYMMDDHHMNSSF...
+ YYYYMMDDHHMNSS
+ YYYYMMDDHHMN
+ YYYYMMDDHH
+ YY-MMDDHHMNSSF...
+ YY-MMDDHHMNSS
+ YY-MMDDHHMN
+ YY-MMDDHH
+ YYYYMMDD
+ YYYYMM
+ YYYY
+ YY-MMDD
+ YY-MM
+ YY
+ YYYYwWWD ex. 1965-W02-2
+ YYwWWD
+ YYYYDOY ex. 1965-045
+ YYDOY
+
+In the above list, YYYY and YY signify 4 or 2 digit years, MM, DD, HH, MN, SS
+refer to two digit month, day, hour, minute, and second respectively. F...
+refers to fractional seconds (any number of digits) which will be ignored.
+The last 4 formats can be explained by example: 1965-w02-2 refers to Tuesday
+(day 2) of the 2nd week of 1965. 1965-045 refers to the 45th day of 1965.
+
+In all cases, parts of the date may be separated by dashes "-". If this is
+done, 1 or 2 digit forms of MM, DD, etc. may be used. All dashes are
+optional except for those given in the table above (which MUST be included
+for that format to be correctly parsed). So 19980820, 1998-0820,
+1998-08-20, 1998-8-20, and 199808-20 are all equivalent, but that date may
+NOT be written as 980820 (it must be written as 98-0820).
+
+NOTE: Even though not allowed in the standard, the timezone for an ISO-8601
+date is flexible and may be any of the timezones understood by Date::Manip.
+
+Additional date formats are available which may or may not be common including:
+
+ MM/DD **
+ MM/DD/YY **
+ MM/DD/YYYY **
+
+ mmmDD DDmmm mmmYYYY/DD mmmYYYY
+ mmmDD/YY DDmmmYY DD/YYmmm YYYYmmmDD YYYYmmm
+ mmmDDYYYY DDmmmYYYY DDYYYYmmm YYYY/DDmmm
+
+Where mmm refers to the name of a month. All parts of the date can be
+separated by valid separators (space, "/", or "."). The separator "-" may
+be used as long as it doesn't conflict with an ISO 8601 format, but this
+is discouraged since it is easy to overlook conflicts. For example, the
+format MM/DD/YY is just fine, but MM-DD-YY does not work since it conflicts
+with YY-MM-DD. To be safe, if "-" is used as a separator in a non-ISO
+format, they should be turned into "/" before calling the Date::Manip
+routines. As with ISO 8601 formats, all separators are optional except for
+those given as a "/" in the list above.
+
+** Note that with these formats, Americans tend to write month first, but
+many other countries tend to write day first. The latter behavior can be
+obtained by setting the config variable DateFormat to something other than
+"US" (see CUSTOMIZING DATE::MANIP below).
+
+Date separators are treated very flexibly (they are converted to spaces),
+so the following dates are all equivalent:
+
+ 12/10/1965
+ 12-10 / 1965
+ 12 // 10 -. 1965
+
+In some cases, this may actually be TOO flexible, but no attempt is made to
+trap this.
+
+Years can be entered as 2 or 4 digits, days and months as 1 or 2 digits.
+Both days and months must include 2 digits whenever they are immediately
+adjacent to another numeric part of the date or time. Date separators
+are required if single digit forms of DD or MM are used. If separators
+are not used, the date will either be unparsable or will get parsed
+incorrectly.
+
+Miscellaneous other allowed formats are:
+ which dofw in mmm in YY "first sunday in june 1996 at 14:00" **
+ dofw week num YY "sunday week 22 1995" **
+ which dofw YY "22nd sunday at noon" **
+ dofw which week YY "sunday 22nd week in 1996" **
+ next/last dofw "next friday at noon"
+ next/last week/month "next month"
+ in num days/weeks/months "in 3 weeks at 12:00"
+ num days/weeks/months later "3 weeks later"
+ num days/weeks/months ago "3 weeks ago"
+ dofw in num week "Friday in 2 weeks"
+ in num weeks dofw "in 2 weeks on friday"
+ dofw num week ago "Friday 2 weeks ago"
+ num week ago dofw "2 weeks ago friday"
+ last day in mmm in YY "last day of October"
+ dofw "Friday" (Friday of current week)
+ Nth "12th", "1st" (day of current month)
+ epoch SECS seconds since the epoch (negative values
+ are supported)
+
+** Note that the formats "sunday week 22" and "22nd sunday" give very
+different bahaviors. "sunday week 22" returns the sunday of the 22nd week
+of the year based on how week 1 is defined. ISO 8601 defines week one to
+contain Jan 4, so "sunday week 1" might be the first or second sunday of
+the current year, or the last sunday of the previous year. "22nd sunday"
+gives the actual 22nd time sunday occurs in a given year, regardless of the
+definition of a week.
+
+Note that certain words such as "in", "at", "of", etc. which commonly appear
+in a date or time are ignored. Also, the year is always optional.
+
+In addition, the following strings are recognized:
+ today (exactly now OR today at a given time if a time is specified)
+ now (synonym for today)
+ yesterday (exactly 24 hours ago unless a time is specified)
+ tomorrow (exactly 24 hours from now unless a time is specifed)
+ noon (12:00:00)
+ midnight (00:00:00)
+Other languages have similar (and in some cases additional) strings.
+
+Some things to note:
+
+All strings are case insensitive. "December" and "DEceMBer" both work.
+
+When a part of the date is not given, defaults are used: year defaults
+to current year; hours, minutes, seconds to 00.
+
+The year may be entered as 2 or 4 digits. If entered as 2 digits, it will
+be converted to a 4 digit year. There are several ways to do this based on
+the value of the YYtoYYYY variable (described below). The default behavior
+it to force the 2 digit year to be in the 100 year period CurrYear-89 to
+CurrYear+10. So in 1996, the range is [1907 to 2006], and the 2 digit year
+05 would refer to 2005 but 07 would refer to 1907. See CUSTOMIZING
+DATE::MANIP below for information on YYtoYYYY for other methods.
+
+Dates are always checked to make sure they are valid.
+
+In all of the formats, the day of week ("Friday") can be entered anywhere
+in the date and it will be checked for accuracy. In other words,
+ "Tue Jul 16 1996 13:17:00"
+will work but
+ "Jul 16 1996 Wednesday 13:17:00"
+will not (because Jul 16, 1996 is Tuesday, not Wednesday). Note that
+depending on where the weekday comes, it may give unexpected results when
+used in array context (with ParseDate). For example, the date
+("Jun","25","Sun","1990") would return June 25 of the current year since
+Jun 25, 1990 is not Sunday.
+
+The times "12:00 am", "12:00 pm", and "midnight" are not well defined. For
+good or bad, I use the following convention in Date::Manip:
+ midnight = 12:00am = 00:00:00
+ noon = 12:00pm = 12:00:00
+and the day goes from 00:00:00 to 23:59:59. In other words, midnight is the
+beginning of a day rather than the end of one. The time 24:00:00 is also
+allowed (though it is automatically transformed to 00:00:00 of the following
+day).
+
+The format of the date returned is YYYYMMDDHH:MM:SS. The advantage of this
+time format is that two times can be compared using simple string comparisons
+to find out which is later. Also, it is readily understood by a human.
+Alternate forms can be used if that is more convenient. See Date_Init below
+and the config variable Internal.
+
+NOTE: The format for the date is going to change at some point in the future
+to YYYYMMDDHH:MN:SS+HHMN*FLAGS. In order to maintain compatibility, you
+should use UnixDate to extract information from a date, and Date_Cmp to compare
+two dates. The simple string comparison will only work for dates in the same
+timezone.
+
+=item UnixDate
+
+ @date = UnixDate($date,@format);
+ $date = UnixDate($date,@format);
+
+This takes a date and a list of strings containing formats roughly
+identical to the format strings used by the UNIX date(1) command. Each
+format is parsed and an array of strings corresponding to each format is
+returned.
+
+$date may be any string that can be parsed by ParseDateString.
+
+The format options are:
+
+ Year
+ %y year - 00 to 99
+ %Y year - 0001 to 9999
+ %G year - 0001 to 9999 (see below)
+ %L year - 0001 to 9999 (see below)
+ Month, Week
+ %m month of year - 01 to 12
+ %f month of year - " 1" to "12"
+ %b,%h month abbreviation - Jan to Dec
+ %B month name - January to December
+ %U week of year, Sunday
+ as first day of week - 01 to 53
+ %W week of year, Monday
+ as first day of week - 01 to 53
+ Day
+ %j day of the year - 001 to 366
+ %d day of month - 01 to 31
+
+ %e day of month - " 1" to "31"
+ %v weekday abbreviation - " S"," M"," T"," W","Th"," F","Sa"
+ %a weekday abbreviation - Sun to Sat
+ %A weekday name - Sunday to Saturday
+ %w day of week - 1 (Monday) to 7 (Sunday)
+ %E day of month with suffix - 1st, 2nd, 3rd...
+ Hour
+ %H hour - 00 to 23
+ %k hour - " 0" to "23"
+ %i hour - " 1" to "12"
+ %I hour - 01 to 12
+ %p AM or PM
+ Minute, Second, Timezone
+ %M minute - 00 to 59
+ %S second - 00 to 59
+ %s seconds from 1/1/1970 GMT- negative if before 1/1/1970
+ %o seconds from Jan 1, 1970
+ in the current time zone
+ %Z timezone - "EDT"
+ %z timezone as GMT offset - "+0100"
+ Date, Time
+ %c %a %b %e %H:%M:%S %Y - Fri Apr 28 17:23:15 1995
+ %C,%u %a %b %e %H:%M:%S %z %Y - Fri Apr 28 17:25:57 EDT 1995
+ %g %a, %d %b %Y %H:%M:%S %z - Fri, 28 Apr 1995 17:23:15 EDT
+ %D,%x %m/%d/%y - 04/28/95
+ %l date in ls(1) format
+ %b %e $H:$M - Apr 28 17:23 (if within 6 months)
+ %b %e %Y - Apr 28 1993 (otherwise)
+ %r %I:%M:%S %p - 05:39:55 PM
+ %R %H:%M - 17:40
+ %T,%X %H:%M:%S - 17:40:58
+ %V %m%d%H%M%y - 0428174095
+ %Q %Y%m%d - 19961025
+ %q %Y%m%d%H%M%S - 19961025174058
+ %P %Y%m%d%H%M%S - 1996102517:40:58
+ %F %A, %B %e, %Y - Sunday, January 1, 1996
+ %J %G-W%W-%w - 1997-W02-2
+ %K %Y-%j - 1997-045
+ Other formats
+ %n insert a newline character
+ %t insert a tab character
+ %% insert a `%' character
+ %+ insert a `+' character
+ The following formats are currently unused but may be used in the future:
+ NO 1234567890 !@#$^&*()_|-=\`[];',./~{}:<>?
+ They currently insert the character following the %, but may (and probably
+ will) change in the future as new formats are added.
+
+If a lone percent is the final character in a format, it is ignored.
+
+Note that the ls format (%l) applies to date within the past OR future 6
+months!
+
+The %U, %W, %L, and %G formats are used to support the ISO-8601 format:
+YYYY-wWW-D. In this format, a date is written as a year, the week of
+the year, and the day of the week. Technically, the week may be considered
+to start on any day of the week, but Sunday and Monday are the two most
+common choices, so both are supported.
+
+The %U and %W formats return a week-of-year number from 01 to 53, and
+%L and %G return a 4-digit year corresponding to the week. Most of the
+time, the %L and %G formats returns the same value as the %Y format,
+but there is a problem with days occuring in the first or last week of
+the year.
+
+The ISO-8601 representation of Jan 1, 1993 written in the YYYY-wWWW-D
+format is actually 1992-W53-5. In other words, Jan 1 is treates as being
+in the last week of the preceding year. Depending on the year, days in
+the first week of a year may belong to the previous year, and days in the
+final week of a year may belong to the next year.
+
+The %L and %U formats contains the year and week-of-year values treating
+weeks as starting on Sunday. The %G and %W formats are the year and
+week-of-year values treating weeks as starting on Monday.
+
+%J returns the full ISO-8601 format (%G-W%W-%w).
+
+The formats used in this routine were originally based on date.pl (version
+3.2) by Terry McGonigal, as well as a couple taken from different versions
+of the Solaris date(1) command. Also, several have been added which are
+unique to Date::Manip.
+
+=item ParseDateDelta
+
+ $delta = ParseDateDelta(\@args);
+ $delta = ParseDateDelta($string);
+ $delta = ParseDateDelta(\$string);
+
+This takes an array and shifts a valid delta date (an amount of time)
+from the array. Recognized deltas are of the form:
+ +Yy +Mm +Ww +Dd +Hh +MNmn +Ss
+ examples:
+ +4 hours +3mn -2second
+ + 4 hr 3 minutes -2
+ 4 hour + 3 min -2 s
+ +Y:+M:+W:+D:+H:+MN:+S
+ examples:
+ 0:0:0:0:4:3:-2
+ +4:3:-2
+ mixed format
+ examples:
+ 4 hour 3:-2
+
+A field in the format +Yy is a sign, a number, and a string specifying
+the type of field. The sign is "+", "-", or absent (defaults to the
+next larger element). The valid strings specifying the field type
+are:
+ y: y, yr, year, years
+ m: m, mon, month, months
+ w: w, wk, ws, wks, week, weeks
+ d: d, day, days
+ h: h, hr, hour, hours
+ mn: mn, min, minute, minutes
+ s: s, sec, second, seconds
+
+Also, the "s" string may be omitted. The sign, number, and string may
+all be separated from each other by any number of whitespaces.
+
+In the date, all fields must be given in the order: Y M W D H MN S. Any
+number of them may be omitted provided the rest remain in the correct
+order. In the 2nd (colon) format, from 2 to 7 of the fields may be given.
+For example +D:+H:+MN:+S may be given to specify only four of the fields.
+In any case, both the MN and S field may be present. No spaces may be
+present in the colon format.
+
+Deltas may also be given as a combination of the two formats. For example,
+the following is valid: +Yy +D:+H:+MN:+S. Again, all fields must be given
+in the correct order.
+
+The word "in" may be given (prepended in English) to the delta ("in 5 years")
+and the word "ago" may be given (appended in English) ("6 months ago"). The
+"in" is completely ignored. The "ago" has the affect of reversing all signs
+that appear in front of the components of the delta. I.e. "-12 yr 6 mon ago"
+is identical to "+12yr +6mon" (don't forget that there is an implied minus
+sign in front of the 6 because when no sign is explicitly given, it carries
+the previously entered sign).
+
+One thing is worth noting. The year/month and day/hour/min/sec parts are
+returned in a "normalized" form. That is, the signs are adjusted so as to
+be all positive or all negative. For example, "+ 2 day - 2hour" does not
+return "0:0:0:2:-2:0:0". It returns "+0:0:0:1:22:0:0" (1 day 22 hours
+which is equivalent). I find (and I think most others agree) that this is
+a more useful form.
+
+Since the year/month and day/hour/min/sec parts must be normalized
+separately there is the possibility that the sign of the two parts will be
+different. So, the delta "+ 2years -10 months - 2 days + 2 hours" produces
+the delta "+1:2:-0:1:22:0:0".
+
+It is possible to include a sign for all elements that is output. See the
+configuration variable DeltaSigns below.
+
+NOTE: The internal format of the delta changed in version 5.30 from
+Y:M:D:H:MN:S to Y:M:W:D:H:MN:S . Also, it is going to change again at some
+point in the future to Y:M:W:D:H:MN:S*FLAGS . Use the routine Delta_Format
+to extract information rather than parsing it yourself.
+
+=item Delta_Format
+
+ @str = Delta_Format($delta,$dec,@format);
+ $str = Delta_Format($delta,$dec,@format);
+
+This is similar to the UnixDate routine except that it extracts information
+from a delta. Unlike the UnixDate routine, most of the formats are 2
+characters instead of 1.
+
+Formats currently understood are:
+
+ %Xv : the value of the field named X
+ %Xd : the value of the field X, and all smaller fields, expressed in
+ units of X
+ %Xh : the value of field X, and all larger fields, expressed in units
+ of X
+ %Xt : the value of all fields expressed in units of X
+
+ X is one of y,M,w,d,h,m,s (case sensitive).
+
+ %% : returns a "%"
+
+NOTE: Delta_Format only understands "exact" relationships, so for any delta
+that has a month component, there can be no mixing of the Y/M and
+W/D/H/MN/S segments. In other words, the delta 1:6:1:1:1:1:1 has a month
+component, so asking for the total number of years (using the %yd format)
+will return 1.5 (which is what 1 year 6 months is). For deltas which have
+NO month component, the relationship between years and days is known
+(365.25 is used) and all formats work as expected (except that formats with
+X equal to "M" are not allowed).
+
+So, the format "%hd" means the values of H, MN, and S expressed in hours.
+So for the delta "0:0:0:0:2:30:0", this format returns 2.5. Similarly, the
+format "%yd" means the value (in years) of both the Y and M fields, or,
+if the month component is 0, it uses Y, W, D, H, MN, S.
+
+The format "%hh" returns the value of W, D, and H expressed in hours if
+the month component is non-zero, or Y, W, D, H if the month component is 0.
+
+If $dec is non-zero, the %Xd and %Xt values are formatted to contain $dec
+decimal places.
+
+=item ParseRecur
+
+ $recur = ParseRecur($string [,$base,$date0,$date1,$flags]);
+ @dates = ParseRecur($string [,$base,$date0,$date1,$flags]);
+
+A recurrence refers to a recurring event. A fully specified recurrence
+requires (in most cases) 4 items: a recur description (describing the
+frequency of the event), a base date (a date when the event occurred and
+which other occurrences are based on), and a start and end date. There may
+be one or more flags included which modify the behavior of the recur
+description. The fully specified recurrence is written as:
+
+ recur*flags*base*date0*date1
+
+Here, base, date0, and date1 are any strings (which must not contain any
+asterixes) which can be parsed by ParseDate. flags is a comma separated
+list of flags (described below), and recur is a string describing a
+recurring event.
+
+If called in scalar context, it returns a string containing a fully
+specified recurrence (or as much of it as can be determined with
+unspecified fields left blank). In list context, it returns a list of all
+dates referred to by a recurrence if enough information is given in the
+recurrence. All dates returned are in the range:
+
+ date0 <= date < date1
+
+The argument $string can contain any of the parts of a full recurrence.
+For example:
+
+ recur
+ recur*flags
+ recur**base*date0*date1
+
+The only part which is required is the recur description. Any values
+contained in $string are overridden or modified by values passed in as
+parameters to ParseRecur.
+
+A recur description is a string of the format Y:M:W:D:H:MN:S . Exactly one
+of the colons may optionally be replaced by an asterisk, or an asterisk may
+be prepended to the string.
+
+Any value "N" to the left of the asterisk refers to the "Nth" one. Any
+value to the right of the asterisk refers to a value as it appears on a
+calendar/clock. Values to the right can be listed a single values, ranges
+(2 numbers separated by a dash "-"), or a comma separated list of values
+or ranges. In a few cases, negative values are appropriate.
+
+This is best illustrated by example.
+
+ 0:0:2:1:0:0:0 every 2 weeks and 1 day
+ 0:0:0:0:5:30:0 every 5 hours and 30 minutes
+ 0:0:0:2*12:30:0 every 2 days at 12:30 (each day)
+ 3*1:0:2:12:0:0 every 3 years on Jan 2 at noon
+ 0:1*0:2:12,14:0:0 2nd of every month at 12:00 and 14:00
+ 1:0:0*45:0:0:0 45th day of every year
+ 0:1*4:2:0:0:0 4th tuesday (day 2) of every month
+ 0:1*-1:2:0:0:0 last tuesday of every month
+ 0:1:0*-2:0:0:0 2nd to last day of every month
+ 0:0:3*2:0:0:0 every 3rd tuesday (every 3 weeks on 2nd day of week)
+ 1:0*12:2:0:0:0 tuesday of the 12th week of each year
+ *1990-1995:12:0:1:0:0:0
+ Dec 1 in 1990 through 1995
+
+ 0:1*2:0:0:0:0 the start of the 2nd week of every month (see Note 2)
+ 1*1:2:0:0:0:0 the start of the 2nd week in January each year (Note 2)
+
+I realize that this looks a bit cryptic, but after a discussion on the
+CALENDAR mailing list, it looked like there was no concise, flexible
+notation for handling recurring events. ISO 8601 notations were very bulky
+and lacked the flexibility I wanted. As a result, I developed this
+notation (based on crontab formats, but with much more flexibility) which
+fits in well with this module, and which is able to express every type of
+recurring event I could think of.
+
+NOTE: If a recurrence has a date0 and date1 in it AND a date0 and date1
+are passed in to the function, both sets of criteria apply. If flags are
+passed in, they override any flags in the recurrence UNLESS the flags
+passed in start with a plus (+) character in which case they are appended
+to the flags in the recurrence.
+
+NOTE: There is no way to express the following with a single recurrence:
+
+ every day at 12:30 and 1:00
+
+You have to use two recurrences to do this.
+
+NOTE: A recurrence specifying the week of a month is NOT clearly defined
+in common usage. What is the 1st week in a month? The behavior (with
+respect to this module) is well defined (using the FDn and FIn flags
+below), but in common usage, this is so ambiguous that this form should
+probably never be used. It is included here solely for the sake of
+completeness.
+
+NOTE: Depending on whether M and W are 0 or nonzero, D means different
+things. This is given in the following table.
+
+ M W D (when right of an asterisk) refers to
+ - - -------------------------------------------
+ 0 0 day of year (1-366)
+ M 0 day of month (1-31)
+ 0 W day of week (1-7), W refers to the week of year
+ M W the Wth (1-5 or -1 to -5) occurrence of Dth (1-7) day of week in month
+
+NOTE: Base dates are only used with some types of recurrences. For example,
+
+ 0:0:3*2:0:0:0 every 3rd tuesday
+
+requires a base date. If a base date is specified which doesn't match the
+criteria (for example, if a base date falling on Monday were passed in with
+this recurrence), the base date is moved forward to the first relevant date.
+
+Other dates do not require a base date. For example:
+
+ 0:0*3:2:0:0:0 third tuesday of every month
+
+A recurrence written in the above format does NOT provide default values
+for base, date0, or date1. They must be specified in order to get a list
+of dates.
+
+A base date is not used entirely. It is only used to provide the parts
+necessary for the left part of a recurrence. For example, the recurrence:
+
+ 1:3*0:4:0:0:0 every 1 year, 3 months on the 4th day of the month
+
+would only use the year and month of the base date.
+
+
+There are a small handful of English strings which can be parsed in place
+of a numerical recur description. These include:
+
+ every 2nd day [in 1997]
+ every 2nd day in June [1997]
+ 2nd day of every month [in 1997]
+ 2nd tuesday of every month [in 1997]
+ last tuesday of every month [in 1997]
+ every tuesday [in 1997]
+ every 2nd tuesday [in 1997]
+ every 2nd tuesday in June [1997]
+
+Each of these set base, date0, and date1 to a default value (the current
+year with Jan 1 being the base date is the default if the year and month
+are missing).
+
+The following flags (case insensitive) are understood:
+
+ MWn : n is 1-7. The first week of the month is the week
+ which contains the first occurrence of day n (1=Monday).
+ MW2 means that the first week contains the first Tuesday
+ of the month.
+ MDn : n is 1-7. The first week of the month contains the
+ actual date (1st through 7th). MD4 means that the first
+ week of the month contains the 4th of that month.
+
+ PDn : n is 1-7. Means the previous day n not counting today
+ PTn : n is 1-7. Means the previous day n counting today
+ NDn : n is 1-7. Means the next day n not counting today
+ NTn : n is 1-7. Means the next day n counting today
+
+ FDn : n is any number. Means step forward n days.
+ BDn : n is any number. Means step backward n days.
+ FWn : n is any number. Means step forward n workdays.
+ BWn : n is any number. Means step backward n workdays.
+
+ CWD : the closest work day (using the TomorrowFirst config variable).
+ CWN : the closest work day (looking forward first).
+ CWP : the closest work day (looking backward first).
+
+ NWD : next work day counting today
+ PWD : previous work day counting today
+ DWD : next/previous work day (TomorrowFirst config) counting today
+
+ EASTER: select easter for this year (the M, W, D fields are ignored
+ in the recur).
+
+NOTE: only one of MWn and MDn can be set. If both are set, only the
+last one is used. The default is MW7 (i.e. the first week contains
+the first Sunday).
+
+CWD, CWN, and CWP will usually return the same value, but if you are
+starting at the middle day of a 3-day weekend (for example), it will return
+either the first work day of the following week, or the last work day of
+the previous week depending on whether it looks forward or backward first.
+
+All flags are applied AFTER the recurrence dates are calculated, and they
+may move a date outside of the date0 to date1 range. No check is made for
+this.
+
+The workday flags do not act exactly the same as a business mode calculation.
+For example, a date that is Saturday with a FW1 steps forward to the first
+workday (i.e. Monday).
+
+=item Date_Cmp
+
+ $flag = Date_Cmp($date1,$date2);
+
+This takes two dates and compares them. Almost all dates can be compared
+using the perl "cmp" command. The only time this will not work is when
+comparing dates in different timezones. This routine will take that into
+account.
+
+NOTE: This routine currently does little more than use "cmp", but once
+the internal format for storing dates is in place (where timezone information
+is kept as part of the date), this routine will become more important. You
+should use this routine in prepartation for that version.
+
+=item DateCalc
+
+ $d = DateCalc($d1,$d2 [,\$err] [,$mode]);
+
+This takes two dates, deltas, or one of each and performs the appropriate
+calculation with them. Dates must be a string that can be parsed by
+&ParseDateString. Deltas must be a string that can be parsed by
+&ParseDateDelta. Two deltas add together to form a third delta. A date
+and a delta returns a 2nd date. Two dates return a delta (the difference
+between the two dates).
+
+Note that in many cases, it is somewhat ambiguous what the delta actually
+refers to. Although it is ALWAYS known how many months in a year, hours in
+a day, etc., it is NOT known how many days form a month. As a result, the
+part of the delta containing month/year and the part with sec/min/hr/day
+must be treated separately. For example, "Mar 31, 12:00:00" plus a delta
+of 1month 2days would yield "May 2 12:00:00". The year/month is first
+handled while keeping the same date. Mar 31 plus one month is Apr 31 (but
+since Apr only has 30 days, it becomes Apr 30). Apr 30 + 2 days is May 2.
+As a result, in the case where two dates are entered, the resulting delta
+can take on two different forms. By default ($mode=0), an absolutely
+correct delta (ignoring daylight savings time) is returned in days, hours,
+minutes, and seconds.
+
+If $mode is 1, the math is done using an approximate mode where a delta is
+returned using years and months as well. The year and month part is
+calculated first followed by the rest. For example, the two dates "Mar 12
+1995" and "Apr 13 1995" would have an exact delta of "31 days" but in the
+approximate mode, it would be returned as "1 month 1 day". Also, "Mar 31"
+and "Apr 30" would have deltas of "30 days" or "1 month" (since Apr 31
+doesn't exist, it drops down to Apr 30). Approximate mode is a more human
+way of looking at things (you'd say 1 month and 2 days more often then 33
+days), but it is less meaningful in terms of absolute time. In approximate
+mode $d1 and $d2 must be dates. If either or both is a delta, the
+calculation is done in exact mode.
+
+If $mode is 2, a business mode is used. That is, the calculation is done
+using business days, ignoring holidays, weekends, etc. In order to
+correctly use this mode, a config file must exist which contains the
+section defining holidays (see documentation on the config file below).
+The config file can also define the work week and the hours of the work
+day, so it is possible to have different config files for different
+businesses.
+
+For example, if a config file defines the workday as 08:00 to 18:00, a
+work week consisting of Mon-Sat, and the standard (American) holidays, then
+from Tuesday at 12:00 to the following Monday at 14:00 is 5 days and 2
+hours. If the "end" of the day is reached in a calculation, it
+automatically switches to the next day. So, Tuesday at 12:00 plus 6 hours
+is Wednesday at 08:00 (provided Wed is not a holiday). Also, a date that
+is not during a workday automatically becomes the start of the next
+workday. So, Sunday 12:00 and Monday at 03:00 both automatically becomes
+Monday at 08:00 (provided Monday is not a holiday). In business mode, any
+combination of date and delta may be entered, but a delta should not
+contain a year or month field (weeks are fine though).
+
+See below for some additional comments about business mode calculations.
+
+Note that a business week is treated the same as an exact week (i.e. from
+Tuesday to Tuesday, regardless of holidays). Because this means that the
+relationship between days and weeks is NOT unambiguous, when a delta is
+produced from two dates, it will be in terms of d/h/mn/s (i.e. no week
+field).
+
+If $mode is 3 (which only applies when two dates are passed in), an exact
+business mode is used. In this case, it returns a delta as an exact number
+of business days/hours/etc. between the two. Weeks, months, and years are
+ignored.
+
+Any other non-nil value of $mode is treated as $mode=1 (approximate mode).
+
+The mode can be automatically set in the dates/deltas passed by including a
+key word somewhere in it. For example, in English, if the word
+"approximately" is found in either of the date/delta arguments, approximate
+mode is forced. Likewise, if the word "business" or "exactly" appears,
+business/exact mode is forced (and $mode is ignored). So, the two
+following are equivalent:
+
+ $date = DateCalc("today","+ 2 business days",\$err);
+ $date = DateCalc("today","+ 2 days",\$err,2);
+
+Note that if the keyword method is used instead of passing in $mode, it is
+important that the keyword actually appear in the argument passed in to
+DateCalc. The following will NOT work:
+
+ $delta = ParseDateDelta("+ 2 business days");
+ $today = ParseDate("today");
+ $date = DateCalc($today,$delta,\$err);
+
+because the mode keyword is removed from a date/delta by the parse routines,
+and the mode is reset each time a parse routine is called. Since DateCalc
+parses both of its arguments, whatever mode was previously set is ignored.
+
+If \$err is passed in, it is set to:
+ 1 is returned if $d1 is not a delta or date
+ 2 is returned if $d2 is not a delta or date
+ 3 is returned if the date is outside the years 1000 to 9999
+This argument is optional, but if included, it must come before $mode.
+
+Nothing is returned if an error occurs.
+
+When a delta is returned, the signs such that it is strictly positive or
+strictly negative ("1 day - 2 hours" would never be returned for example).
+The only time when this cannot be enforced is when two deltas with a
+year/month component are entered. In this case, only the signs on the
+day/hour/min/sec part are standardized.
+
+=item Date_SetTime
+
+ $date = Date_SetTime($date,$hr,$min,$sec);
+ $date = Date_SetTime($date,$time);
+
+This takes a date (any string that may be parsed by ParseDateString) and
+sets the time in that date. For example, one way to get the time for 7:30
+tomorrow would be to use the lines:
+
+ $date = ParseDate("tomorrow");
+ $date = Date_SetTime($date,"7:30");
+
+Note that in this routine (as well as the other routines below which use
+a time argument), no real parsing is done on the times. As a result,
+
+ $date = Date_SetTime($date,"13:30");
+
+works, but
+
+ $date = Date_SetTime($date,"1:30 PM");
+
+doesn't.
+
+=item Date_SetDateField
+
+ $date = Date_SetDateField($date,$field,$val [,$nocheck]);
+
+This takes a date and sets one of it's fields to a new value. $field is
+any of the strings "y", "m", "d", "h", "mn", "s" (case insensitive) and
+$val is the new value.
+
+If $nocheck is non-zero, no check is made as to the validity of the date.
+
+=item Date_GetPrev
+
+ $date = Date_GetPrev($date,$dow, $curr [,$hr,$min,$sec]);
+ $date = Date_GetPrev($date,$dow, $curr [,$time]);
+ $date = Date_GetPrev($date,undef,$curr,$hr,$min,$sec);
+ $date = Date_GetPrev($date,undef,$curr,$time);
+
+This takes a date (any string that may be parsed by ParseDateString) and finds
+the previous occurrence of either a day of the week, or a certain time of day.
+
+If $dow is defined, the previous occurrence of the day of week is returned.
+$dow may either be a string (such as "Fri" or "Friday") or a number
+(between 1 and 7). The date of the previous $dow is returned.
+
+If $date falls on the day of week given by $dow, the date returned depends
+on $curr. If $curr is 0, the date returned is a week before $date. If
+$curr is 1, the date returned is the same as $date. If $curr is 2, the date
+returned (including the time information) is required to be before $date.
+
+If a time is passed in (either as separate hours, minutes, seconds or as a
+time in HH:MM:SS or HH:MM format), the time on this date is set to it. The
+following examples should illustrate the use of Date_GetPrev:
+
+ date dow curr time returns
+ Fri Nov 22 18:15:00 Thu any 12:30 Thu Nov 21 12:30:00
+ Fri Nov 22 18:15:00 Fri 0 12:30 Fri Nov 15 12:30:00
+ Fri Nov 22 18:15:00 Fri 1/2 12:30 Fri Nov 22 12:30:00
+
+ Fri Nov 22 18:15:00 Fri 1 18:30 Fri Nov 22 18:30:00
+ Fri Nov 22 18:15:00 Fri 2 18:30 Fri Nov 15 18:30:00
+
+If $dow is undefined, then a time must be entered, and the date returned is
+the previous occurrence of this time. If $curr is non-zero, the current
+time is returned if it matches the criteria passed in. In other words, the
+time returned is the last time that a digital clock (in 24 hour mode) would
+have displayed the time you passed in. If you define hours, minutes and
+seconds default to 0 and you might jump back as much as an entire day. If
+hours are undefined, you are looking for the last time the minutes/seconds
+appeared on the digital clock, so at most, the time will jump back one hour.
+
+ date curr hr min sec returns
+ Nov 22 18:15:00 0/1 18 undef undef Nov 22 18:00:00
+ Nov 22 18:15:00 0/1 18 30 0 Nov 21 18:30:00
+ Nov 22 18:15:00 0 18 15 undef Nov 21 18:15:00
+ Nov 22 18:15:00 1 18 15 undef Nov 22 18:15:00
+ Nov 22 18:15:00 0 undef 15 undef Nov 22 17:15:00
+ Nov 22 18:15:00 1 undef 15 undef Nov 22 18:15:00
+
+=item Date_GetNext
+
+ $date = Date_GetNext($date,$dow, $curr [,$hr,$min,$sec]);
+ $date = Date_GetNext($date,$dow, $curr [,$time]);
+ $date = Date_GetNext($date,undef,$curr,$hr,$min,$sec);
+ $date = Date_GetNext($date,undef,$curr,$time);
+
+Similar to Date_GetPrev.
+
+=item Date_IsHoliday
+
+ $name = Date_IsHoliday($date);
+
+This returns undef if $date is not a holiday, or a string containing the
+name of the holiday otherwise. An empty string is returned for an unnamed
+holiday.
+
+=item Events_List
+
+ $ref = Events_List($date);
+ $ref = Events_List($date ,0 [,$flag]);
+ $ref = Events_List($date0,$date1 [,$flag]);
+
+This returns a list of events. Events are defined in the Events section
+of the config file (discussed below).
+
+In the first form (a single argument), $date is any string containing a
+date. A list of events active at that precise time will be returned.
+The format is similar to when $flag=0, except only a single time will
+be returned.
+
+In all other cases, a range of times will be used. If the 2nd argument
+evaluates to 0, the range of times will be the 24 hour period from
+midnight to midnight containing $date. Otherwise, the range is given
+by the two dates.
+
+The value of $flag determines the format of the information that is
+returned.
+
+With $flag=0, the events are returned as a reference to a list of the form:
+
+ [ date, [ list_of_events ], date, [ list_of_events ], ... ]
+
+For example, if the following events are defined (using the syntax
+discussed below in the description of the Event section of the config
+file):
+
+ 2000-01-01 ; 2000-03-21 = Winter
+ 2000-03-22 ; 2000-06-21 = Spring
+ 2000-02-01 = Event1
+ 2000-05-01 = Event2
+ 2000-04-01-12:00:00 = Event3
+
+might result in the following output:
+
+ &Events_List("2000-04-01")
+ => [ 2000040100:00:00, [ Spring ] ]
+
+ &Events_List("2000-04-01 12:30");
+ => [ 2000040112:30:00, [ Spring, Event3 ] ]
+
+ &Events_List("2000-04-01",0);
+ => [ 2000040100:00:00, [ Spring ],
+ 2000040112:00:00, [ Spring, Event3 ],
+ 2000040113:00:00, [ Spring ] ]
+
+ &Events_List("2000-03-15","2000-04-10");
+ => [ 2000031500:00:00, [ Winter ],
+ 2000032200:00:00, [ Spring ]
+ 2000040112:00:00, [ Spring, Event3 ]
+ 2000040113:00:00, [ Spring ] ]
+
+Much more complicated events can be defined using recurrences.
+
+When $flag is non-zero, the format of the output is changed. If $flag
+is 1, then a tally of the amount of time given to each event is returned.
+Time for which two or more events apply is counted for both.
+
+ &Events_List("2000-03-15","2000-04-10",1);
+ => { Winter => +0:0:1:0:0:0:0,
+ Spring => +0:0:2:5:0:0:0,
+ Event3 => +0:0:0:0:1:0:0 }
+
+When $flag is 2, a more complex tally with no event counted twice is
+returned.
+
+ &Events_List("2000-03-15","2000-04-10",2);
+ => { Winter => +0:0:1:0:0:0:0,
+ Spring => +0:0:2:4:23:0:0,
+ Event3+Spring => +0:0:0:0:1:0:0 }
+
+The hash contains one element for each combination of events.
+
+=item Date_DayOfWeek
+
+ $day = Date_DayOfWeek($m,$d,$y);
+
+Returns the day of the week (1 for Monday, 7 for Sunday).
+
+All arguments must be numeric.
+
+=item Date_SecsSince1970
+
+ $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
+
+Returns the number of seconds since Jan 1, 1970 00:00 (negative if date is
+earlier).
+
+All arguments must be numeric.
+
+=item Date_SecsSince1970GMT
+
+ $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
+
+Returns the number of seconds since Jan 1, 1970 00:00 GMT (negative if date
+is earlier). If CurrTZ is "IGNORE", the number will be identical to
+Date_SecsSince1970 (i.e. the date given will be treated as being in GMT).
+
+All arguments must be numeric.
+
+=item Date_DaysSince1BC
+
+ $days = Date_DaysSince1BC($m,$d,$y);
+
+Returns the number of days since Dec 31, 1BC. This includes the year 0000.
+
+All arguments must be numeric.
+
+=item Date_DayOfYear
+
+ $day = Date_DayOfYear($m,$d,$y);
+
+Returns the day of the year (001 to 366)
+
+All arguments must be numeric.
+
+=item Date_NthDayOfYear
+
+ ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
+
+Returns the year, month, day, hour, minutes, and decimal seconds given
+a floating point day of the year.
+
+All arguments must be numeric. $n must be greater than or equal to 1
+and less than 366 on non-leap years and 367 on leap years.
+
+NOTE: When $n is a decimal number, the results are non-intuitive perhaps.
+Day 1 is Jan 01 00:00. Day 2 is Jan 02 00:00. Intuitively, you
+might think of day 1.5 as being 1.5 days after Jan 01 00:00, but this
+would mean that Day 1.5 was Jan 02 12:00 (which is later than Day 2).
+The best way to think of this function is a timeline starting at 1 and
+ending at 366 (in a non-leap year). In terms of a delta, think of $n
+as the number of days after Dec 31 00:00 of the previous year.
+
+=item Date_DaysInYear
+
+ $days = Date_DaysInYear($y);
+
+Returns the number of days in the year (365 or 366)
+
+=item Date_DaysInMonth
+
+ $days = Date_DaysInMonth($m,$y);
+
+Returns the number of days in the month.
+
+=item Date_WeekOfYear
+
+ $wkno = Date_WeekOfYear($m,$d,$y,$first);
+
+Figure out week number. $first is the first day of the week which is
+usually 1 (Monday) or 7 (Sunday), but could be any number between 1 and 7
+in practice.
+
+All arguments must be numeric.
+
+NOTE: This routine should only be called in rare cases. Use UnixDate with
+the %W, %U, %J, %L formats instead. This routine returns a week between 0
+and 53 which must then be "fixed" to get into the ISO-8601 weeks from 1 to
+53. A date which returns a week of 0 actually belongs to the last week of
+the previous year. A date which returns a week of 53 may belong to the
+first week of the next year.
+
+=item Date_LeapYear
+
+ $flag = Date_LeapYear($y);
+
+Returns 1 if the argument is a leap year
+Written by David Muir Sharnoff <muir@idiom.com>
+
+=item Date_DaySuffix
+
+ $day = Date_DaySuffix($d);
+
+Add `st', `nd', `rd', `th' to a date (ie 1st, 22nd, 29th). Works for
+international dates.
+
+=item Date_TimeZone
+
+ $tz = Date_TimeZone;
+
+This determines and returns the local timezone. If it is unable to determine
+the local timezone, the following error occurs:
+
+ ERROR: Date::Manip unable to determine TimeZone.
+
+See The TIMEZONES section below for more information.
+
+=item Date_ConvTZ
+
+ $date = Date_ConvTZ($date);
+ $date = Date_ConvTZ($date,$from);
+ $date = Date_ConvTZ($date,"",$to);
+ $date = Date_ConvTZ($date,$from,$to);
+
+This converts a date (which MUST be in the format returned by ParseDate)
+from one timezone to another.
+
+If it is called with no arguments, the date is converted from the local
+timezone to the timezone specified by the config variable ConvTZ (see
+documentation on ConvTZ below). If ConvTZ is set to "IGNORE", no
+conversion is done.
+
+If called with $from but no $to, the timezone is converted from the
+timezone in $from to ConvTZ (of TZ if ConvTZ is not set). Again, no
+conversion is done if ConvTZ is set to "IGNORE".
+
+If called with $to but no $from, $from defaults to ConvTZ (if set) or the
+local timezone otherwise. Although this does not seem immediately obvious,
+it actually makes sense. By default, all dates that are parsed are
+converted to ConvTZ, so most of the dates being worked with will be stored
+in that timezone.
+
+If Date_ConvTZ is called with both $from and $to, the date is converted
+from the timezone $from to $to.
+
+NOTE: As in all other cases, the $date returned from Date_ConvTZ has no
+timezone information included as part of it, so calling UnixDate with the
+"%z" format will return the timezone that Date::Manip is working in
+(usually the local timezone).
+
+Example: To convert 2/2/96 noon PST to CST (regardless of what timezone
+you are in, do the following:
+
+ $date = ParseDate("2/2/96 noon");
+ $date = Date_ConvTZ($date,"PST","CST");
+
+Both timezones MUST be in one of the formats listed below in the section
+TIMEZONES.
+
+=item Date_Init
+
+ &Date_Init();
+ &Date_Init("VAR=VAL","VAR=VAL",...);
+ @list = Date_Init();
+ @list = Date_Init("VAR=VAL","VAR=VAL",...);
+
+Normally, it is not necessary to explicitly call Date_Init. The first
+time any of the other routines are called, Date_Init will be called to set
+everything up. If for some reason you want to change the configuration of
+Date::Manip, you can pass the appropriate string or strings into Date_Init
+to reinitialize things.
+
+The strings to pass in are of the form "VAR=VAL". Any number may be
+included and they can come in any order. VAR may be any configuration
+variable. A list of all configuration variables is given in the section
+CUSTOMIZING DATE::MANIP below. VAL is any allowed value for that variable.
+For example, to switch from English to French and use non-US format (so
+that 12/10 is Oct 12), do the following:
+
+ &Date_Init("Language=French","DateFormat=non-US");
+
+If Date_Init is called in list context, it will return a list of all
+config variables and their values suitable for passing in to Date_Init
+to return Date::Manip to the current state. The only possible problem is
+that by default, holidays will not be erased, so you may need to prepend
+the "EraseHolidays=1" element to the list.
+
+=item Date_IsWorkDay
+
+ $flag = Date_IsWorkDay($date [,$flag]);
+
+This returns 1 if $date is a work day. If $flag is non-zero, the time is
+checked to see if it falls within work hours. It returns an empty string
+if $date is not valid.
+
+=item Date_NextWorkDay
+
+ $date = Date_NextWorkDay($date,$off [,$time]);
+
+Finds the day $off work days from now. If $time is passed in, we must also
+take into account the time of day.
+
+If $time is not passed in, day 0 is today (if today is a workday) or the
+next work day if it isn't. In any case, the time of day is unaffected.
+
+If $time is passed in, day 0 is now (if now is part of a workday) or the
+start of the very next work day.
+
+=item Date_PrevWorkDay
+
+ $date = Date_PrevWorkDay($date,$off [,$time]);
+
+Similar to Date_NextWorkDay.
+
+=item Date_NearestWorkDay
+
+ $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
+
+This looks for the work day nearest to $date. If $date is a work day, it
+is returned. Otherwise, it will look forward or backwards in time 1 day
+at a time until a work day is found. If $tomorrowfirst is non-zero (or if
+it is omitted and the config variable TomorrowFirst is non-zero), we look
+to the future first. Otherwise, we look in the past first. In other words,
+in a normal week, if $date is Wednesday, $date is returned. If $date is
+Saturday, Friday is returned. If $date is Sunday, Monday is returned. If
+Wednesday is a holiday, Thursday is returned if $tomorrowfirst is non-nil
+or Tuesday otherwise.
+
+=item DateManipVersion
+
+ $version = DateManipVersion;
+
+Returns the version of Date::Manip.
+
+=back
+
+=head1 TIMEZONES
+
+The following timezone names are currently understood (and can be used in
+parsing dates). These are zones defined in RFC 822.
+
+ Universal: GMT, UT
+ US zones : EST, EDT, CST, CDT, MST, MDT, PST, PDT
+ Military : A to Z (except J)
+ Other : +HHMM or -HHMM
+ ISO 8601 : +HH:MM, +HH, -HH:MM, -HH
+
+In addition, the following timezone abbreviations are also accepted. In a
+few cases, the same abbreviation is used for two different timezones (for
+example, NST stands for Newfoundland Standard -0330 and North Sumatra +0630).
+In these cases, only 1 of the two is available. The one preceded by a "#"
+sign is NOT available but is documented here for completeness. This list of
+zones comes in part from the Time::Zone module by Graham Barr, David Muir
+Sharnoff, and Paul Foley (with several additions by myself).
+
+ IDLW -1200 International Date Line West
+ NT -1100 Nome
+ HST -1000 Hawaii Standard
+ CAT -1000 Central Alaska
+ AHST -1000 Alaska-Hawaii Standard
+ AKST -0900 Alaska Standard
+ YST -0900 Yukon Standard
+ HDT -0900 Hawaii Daylight
+ AKDT -0800 Alaska Daylight
+ YDT -0800 Yukon Daylight
+ PST -0800 Pacific Standard
+ PDT -0700 Pacific Daylight
+ MST -0700 Mountain Standard
+ MDT -0600 Mountain Daylight
+ CST -0600 Central Standard
+ CDT -0500 Central Daylight
+ EST -0500 Eastern Standard
+ ACT -0500 Brazil, Acre
+ SAT -0400 Chile
+ BOT -0400 Bolivia
+ EDT -0400 Eastern Daylight
+ AST -0400 Atlantic Standard
+ AMT -0400 Brazil, Amazon
+ ACST -0400 Brazil, Acre Daylight
+ #NST -0330 Newfoundland Standard nst=North Sumatra +0630
+ NFT -0330 Newfoundland
+ #GST -0300 Greenland Standard gst=Guam Standard +1000
+ #BST -0300 Brazil Standard bst=British Summer +0100
+ BRST -0300 Brazil Standard
+ BRT -0300 Brazil Standard
+ AMST -0300 Brazil, Amazon Daylight
+ ADT -0300 Atlantic Daylight
+ ART -0300 Argentina
+ NDT -0230 Newfoundland Daylight
+ AT -0200 Azores
+ BRST -0200 Brazil Daylight (official time)
+ FNT -0200 Brazil, Fernando de Noronha
+ WAT -0100 West Africa
+ FNST -0100 Brazil, Fernando de Noronha Daylight
+ GMT +0000 Greenwich Mean
+ UT +0000 Universal (Coordinated)
+ UTC +0000 Universal (Coordinated)
+ WET +0000 Western European
+ CET +0100 Central European
+ FWT +0100 French Winter
+ MET +0100 Middle European
+ MEZ +0100 Middle European
+ MEWT +0100 Middle European Winter
+ SWT +0100 Swedish Winter
+ BST +0100 British Summer bst=Brazil standard -0300
+ GB +0100 GMT with daylight savings
+ WEST +0000 Western European Daylight
+ CEST +0200 Central European Summer
+ EET +0200 Eastern Europe, USSR Zone 1
+ FST +0200 French Summer
+ MEST +0200 Middle European Summer
+ MESZ +0200 Middle European Summer
+ METDST +0200 An alias for MEST used by HP-UX
+ SAST +0200 South African Standard
+ SST +0200 Swedish Summer sst=South Sumatra +0700
+ EEST +0300 Eastern Europe Summer
+ BT +0300 Baghdad, USSR Zone 2
+ MSK +0300 Moscow
+ EAT +0300 East Africa
+ IT +0330 Iran
+ ZP4 +0400 USSR Zone 3
+ MSD +0300 Moscow Daylight
+ ZP5 +0500 USSR Zone 4
+ IST +0530 Indian Standard
+ ZP6 +0600 USSR Zone 5
+ NOVST +0600 Novosibirsk time zone, Russia
+ NST +0630 North Sumatra nst=Newfoundland Std -0330
+ #SST +0700 South Sumatra, USSR Zone 6 sst=Swedish Summer +0200
+ JAVT +0700 Java
+ CCT +0800 China Coast, USSR Zone 7
+ AWST +0800 Australian Western Standard
+ WST +0800 West Australian Standard
+ PHT +0800 Asia Manila
+ JST +0900 Japan Standard, USSR Zone 8
+ ROK +0900 Republic of Korea
+ ACST +0930 Australian Central Standard
+ CAST +0930 Central Australian Standard
+ AEST +1000 Australian Eastern Standard
+ EAST +1000 Eastern Australian Standard
+ GST +1000 Guam Standard, USSR Zone 9 gst=Greenland Std -0300
+ ACDT +1030 Australian Central Daylight
+ CADT +1030 Central Australian Daylight
+ AEDT +1100 Australian Eastern Daylight
+ EADT +1100 Eastern Australian Daylight
+ IDLE +1200 International Date Line East
+ NZST +1200 New Zealand Standard
+ NZT +1200 New Zealand
+ NZDT +1300 New Zealand Daylight
+
+Others can be added in the future upon request.
+
+Date::Manip must be able to determine the timezone the user is in. It does
+this by looking in the following places:
+
+ $Date::Manip::TZ (set with Date_Init or in Manip.pm)
+ $ENV{TZ}
+ the unix `date` command (if available)
+ $main::TZ
+ /etc/TIMEZONE
+ /etc/timezone
+
+At least one of these should contain a timezone in one of the supported
+forms. If none do by default, the TZ variable must be set with Date_Init.
+
+The timezone may be in the STD#DST format (in which case both abbreviations
+must be in the table above) or any of the formats described above. The
+STD#DST format is NOT available when parsing a date however. The following
+forms are also available and are treated similar to the STD#DST forms:
+
+ US/Pacific
+ US/Mountain
+ US/Central
+ US/Eastern
+ Canada/Pacific
+ Canada/Mountain
+ Canada/Central
+ Canada/Eastern
+
+=head1 BUSINESS MODE
+
+Anyone using business mode is going to notice a few quirks about it which
+should be explained. When I designed business mode, I had in mind what UPS
+tells me when they say 2 day delivery, or what the local business which
+promises 1 business day turnaround really means.
+
+If you do a business day calculation (with the workday set to 9:00-5:00),
+you will get the following:
+
+ Saturday at noon + 1 business day = Tuesday at 9:00
+ Saturday at noon - 1 business day = Friday at 9:00
+
+What does this mean?
+
+We have a business that works 9-5 and they have a drop box so I can drop
+things off over the weekend and they promise 1 business day turnaround. If
+I drop something off Friday night, Saturday, or Sunday, it doesn't matter.
+They're going to get started on it Monday morning. It'll be 1 business day
+to finish the job, so the earliest I can expect it to be done is around
+17:00 Monday or 9:00 Tuesday morning. Unfortunately, there is some
+ambiguity as to what day 17:00 really falls on, similar to the ambiguity
+that occurs when you ask what day midnight falls on. Although it's not the
+only answer, Date::Manip treats midnight as the beginning of a day rather
+than the end of one. In the same way, 17:00 is equivalent to 9:00 the next
+day and any time the date calculations encounter 17:00, it automatically
+switch to 9:00 the next day. Although this introduces some quirks, I think
+this is justified. You just have to treat 17:00/9:00 as being ambiguous
+(in the same way you treat midnight as being ambiguous).
+
+Equivalently, if I want a job to be finished on Saturday (despite the fact
+that I cannot pick it up since the business is closed), I have to drop it
+off no later than Friday at 9:00. That gives them a full business day to
+finish it off. Of course, I could just as easily drop it off at 17:00
+Thursday, or any time between then and 9:00 Friday. Again, it's a matter
+of treating 9:00 as ambiguous.
+
+So, in case the business date calculations ever produce results that you
+find confusing, I believe the solution is to write a wrapper which,
+whenever it sees a date with the time of exactly 9:00, it treats it
+specially (depending on what you want.
+
+So Saturday + 1 business day = Tuesday at 9:00 (which means anything
+from Monday 17:00 to Tuesday 9:00), but Monday at 9:01 + 1 business
+day = Tuesday at 9:01 which is exact.
+
+If this is not exactly what you have in mind, don't use the DateCalc
+routine. You can probably get whatever behavior you want using the
+routines Date_IsWorkDay, Date_NextWorkDay, and Date_PrevWorkDay described
+above.
+
+=head1 CUSTOMIZING DATE::MANIP
+
+There are a number of variables which can be used to customize the way
+Date::Manip behaves. There are also several ways to set these variables.
+
+At the top of the Manip.pm file, there is a section which contains all
+customization variables. These provide the default values.
+
+These can be overridden in a global config file if one is present (this
+file is optional). If the GlobalCnf variable is set in the Manip.pm file,
+it contains the full path to a config file. If the file exists, it's
+values will override those set in the Manip.pm file. A sample config file
+is included with the Date::Manip distribution. Modify it as appropriate
+and copy it to some appropriate directory and set the GlobalCnf variable in
+the Manip.pm file.
+
+Each user can have a personal config file which is of the same form as the
+global config file. The variables PersonalCnf and PersonalCnfPath set the
+name and search path for the personal config file. This file is also
+optional. If present, it overrides any values set in the global file.
+
+NOTE: if you use business mode calculations, you must have a config file
+(either global or personal) since this is the only place where you can
+define holidays.
+
+Finally, any variables passed in through Date_Init override all other
+values.
+
+A config file can be composed of several sections. The first section sets
+configuration variables. Lines in this section are of the form:
+
+ VARIABLE = VALUE
+
+For example, to make the default language French, include the line:
+
+ Language = French
+
+Only variables described below may be used. Blank lines and lines beginning
+with a pound sign (#) are ignored. All spaces are optional and strings are
+case insensitive.
+
+A line which starts with an asterisk (*) designates a new section. For
+example, the HOLIDAY section starts with a line:
+
+ *Holiday
+
+The various sections are defined below.
+
+=head1 DATE::MANIP VARIABLES
+
+All Date::Manip variables which can be used are described in the following
+section.
+
+=over 4
+
+=item IgnoreGlobalCnf
+
+If this variable is used (any value is ignored), the global config file
+is not read. It must be present in the initial call to Date_Init or the
+global config file will be read.
+
+=item EraseHolidays
+
+If this variable is used (any value is ignored), the current list of
+defined holidays is erased. A new set will be set the next time a
+config file is read in. This can be set in either the global config file
+or as a Date_Init argument (in which case holidays can be read in from
+both the global and personal config files) or in the personal config file
+(in which case, only holidays in the personal config file are counted).
+
+=item PathSep
+
+This is a regular expression used to separate multiple paths. For example,
+on Unix, it defaults to a colon (:) so that multiple paths can be written
+PATH1:PATH2 . For Win32 platforms, it defaults to a semicolon (;) so that
+paths such as "c:\;d:\" will work.
+
+=item GlobalCnf
+
+This variable can be passed into Date_Init to point to a global
+configuration file. The value must be the complete path to a config file.
+
+By default, no global config file is read. Any time a global config file
+is read, the holidays are erased.
+
+Paths may have a tilde (~) expansion on platforms where this is supported
+(currently Unix and VMS).
+
+=item PersonalCnf
+
+This variable can be passed into Date_Init or set in a global config file
+to set the name of the personal configuration file.
+
+The default name for the config file is .DateManip.cnf on all Unix
+platforms and Manip.cnf on all non-Unix platforms (because some of them
+insist on 8.3 character filenames :-).
+
+=item PersonalCnfPath
+
+This is a list of paths separated by the separator specified by the PathSep
+variable. These paths are each checked for the PersonalCnf config file.
+
+Paths may have a tilde (~) expansion on platforms where this is supported
+(currently Unix and VMS).
+
+=item Language
+
+Date::Manip can be used to parse dates in many different languages.
+Currently, it is configured to read the following languages (the version
+in which they added is included for historical interest):
+
+ English (default)
+ French (5.02)
+ Swedish (5.05)
+ German (5.31)
+ Dutch (5.32) aka Nederlands
+ Polish (5.32)
+ Spanish (5.33)
+ Portuguese (5.34)
+ Romanian (5.35)
+ Italian (5.35)
+ Russian (5.41)
+ Turkish (5.41)
+ Danish (5.41)
+
+Others can be added easily. Language is set to the language used to parse
+dates. If you are interested in providing a translation for a new
+language, email me (see the AUTHOR section below) and I'll send you a list
+of things that I need.
+
+=item DateFormat
+
+Different countries look at the date 12/10 as Dec 10 or Oct 12. In the
+United States, the first is most common, but this certainly doesn't hold
+true for other countries. Setting DateFormat to "US" forces the first
+behavior (Dec 10). Setting DateFormat to anything else forces the second
+behavior (Oct 12).
+
+=item TZ
+
+If set, this defines the local timezone. See the TIMEZONES section above
+for information on it's format.
+
+=item ConvTZ
+
+All date comparisons and calculations must be done in a single time zone in
+order for them to work correctly. So, when a date is parsed, it should be
+converted to a specific timezone. This allows dates to easily be compared
+and manipulated as if they are all in a single timezone.
+
+The ConvTZ variable determines which timezone should be used to store dates
+in. If it is left blank, all dates are converted to the local timezone
+(see the TZ variable above). If it is set to one of the timezones listed
+above, all dates are converted to this timezone. Finally, if it is set to
+the string "IGNORE", all timezone information is ignored as the dates are
+read in (in this case, the two dates "1/1/96 12:00 GMT" and "1/1/96 12:00
+EST" would be treated as identical).
+
+=item Internal
+
+When a date is parsed using ParseDate, that date is stored in an internal
+format which is understood by the Date::Manip routines UnixDate and
+DateCalc. Originally, the format used to store the date internally was:
+
+ YYYYMMDDHH:MN:SS
+
+It has been suggested that I remove the colons (:) to shorten this to:
+
+ YYYYMMDDHHMNSS
+
+The main advantage of this is that some databases are colon delimited which
+makes storing a date from Date::Manip tedious.
+
+In order to maintain backwards compatibility, the Internal variable was
+introduced. Set it to 0 (to use the old format) or 1 (to use the new
+format).
+
+=item FirstDay
+
+It is sometimes necessary to know what day of week is regarded as first.
+By default, this is set to Monday, but many countries and people will
+prefer Sunday (and in a few cases, a different day may be desired). Set
+the FirstDay variable to be the first day of the week (1=Monday, 7=Sunday)
+Monday should be chosen to to comply with ISO 8601.
+
+=item WorkWeekBeg, WorkWeekEnd
+
+The first and last days of the work week. By default, Monday and Friday.
+WorkWeekBeg must come before WorkWeekEnd numerically. The days are
+numbered from 1 (Monday) to 7 (Sunday).
+
+There is no way to handle an odd work week of Thu to Mon for example or 10
+days on, 4 days off.
+
+=item WorkDay24Hr
+
+If this is non-nil, a work day is treated as being 24 hours long. The
+WorkDayBeg and WorkDayEnd variables are ignored in this case.
+
+=item WorkDayBeg, WorkDayEnd
+
+The times when the work day starts and ends. WorkDayBeg must come before
+WorkDayEnd (i.e. there is no way to handle the night shift where the work
+day starts one day and ends another). Also, the workday MUST be more than
+one hour long (of course, if this isn't the case, let me know... I want a
+job there!).
+
+The time in both can be in any valid time format (including international
+formats), but seconds will be ignored.
+
+=item TomorrowFirst
+
+Periodically, if a day is not a business day, we need to find the nearest
+business day to it. By default, we'll look to "tomorrow" first, but if this
+variable is set to 0, we'll look to "yesterday" first. This is only used in
+the Date_NearestWorkDay and is easily overridden (see documentation for that
+function).
+
+=item DeltaSigns
+
+Prior to Date::Manip version 5.07, a negative delta would put negative
+signs in front of every component (i.e. "0:0:-1:-3:0:-4"). By default,
+5.07 changes this behavior to print only 1 or two signs in front of the
+year and day elements (even if these elements might be zero) and the sign
+for year/month and day/hour/minute/second are the same. Setting this
+variable to non-zero forces deltas to be stored with a sign in front of
+every element (including elements equal to 0).
+
+=item Jan1Week1
+
+ISO 8601 states that the first week of the year is the one which contains
+Jan 4 (i.e. it is the first week in which most of the days in that week
+fall in that year). This means that the first 3 days of the year may
+be treated as belonging to the last week of the previous year. If this
+is set to non-nil, the ISO 8601 standard will be ignored and the first
+week of the year contains Jan 1.
+
+=item YYtoYYYY
+
+By default, a 2 digit year is treated as falling in the 100 year period of
+CURR-89 to CURR+10. YYtoYYYY may be set to any integer N to force a 2
+digit year into the period CURR-N to CURR+(99-N). A value of 0 forces
+the year to be the current year or later. A value of 99 forces the year
+to be the current year or earlier. Since I do no checking on the value of
+YYtoYYYY, you can actually have it any positive or negative value to force
+it into any century you want.
+
+YYtoYYYY can also be set to "C" to force it into the current century, or
+to "C##" to force it into a specific century. So, no (1998), "C" forces
+2 digit years to be 1900-1999 and "C18" would force it to be 1800-1899.
+
+It can also be set to the form "C####" to force it into a specific 100
+year period. C1950 refers to 1950-2049.
+
+=item UpdateCurrTZ
+
+If a script is running over a long period of time, the timezone may change
+during the course of running it (i.e. when daylight savings time starts or
+ends). As a result, parsing dates may start putting them in the wrong time
+zone. Since a lot of overhead can be saved if we don't have to check the
+current timezone every time a date is parsed, by default checking is turned
+off. Setting this to non-nil will force timezone checking to be done every
+time a date is parsed... but this will result in a considerable performance
+penalty.
+
+A better solution would be to restart the process on the two days per year
+where the timezone switch occurs.
+
+=item IntCharSet
+
+If set to 0, use the US character set (7-bit ASCII) to return strings such
+as the month name. If set to 1, use the appropriate international character
+set. For example, If you want your French representation of Decemeber to
+have the accent over the first "e", you'll want to set this to 1.
+
+=item ForceDate
+
+This variable can be set to a date in the format: YYYY-MM-DD-HH:MN:SS
+to force the current date to be interpreted as this date. Since the current
+date is used in parsing, this string will not be parsed and MUST be in the
+format given above.
+
+=back
+
+=head1 HOLIDAY SECTION
+
+The holiday section of the config file is used to define holidays. Each
+line is of the form:
+
+ DATE = HOLIDAY
+
+HOLIDAY is the name of the holiday (or it can be blank in which case the
+day will still be treated as a holiday... for example the day after
+Thanksgiving or Christmas is often a work holiday though neither are
+named).
+
+DATE is a string which can be parsed to give a valid date in any year. It
+can be of the form
+
+ Date
+ Date + Delta
+ Date - Delta
+ Recur
+
+A valid holiday section would be:
+
+ *Holiday
+
+ 1/1 = New Year's Day
+ third Monday in Feb = Presidents' Day
+ fourth Thu in Nov = Thanksgiving
+
+ # The Friday after Thanksgiving is an unnamed holiday most places
+ fourth Thu in Nov + 1 day =
+
+ 1*0:0:0:0:0:0*EASTER = Easter
+ 1*11:0:11:0:0:0*CWD = Veteran's Day (observed)
+ 1*0:0:0:0:0:0*EASTER,PD5 = Good Friday
+
+In a Date + Delta or Date - Delta string, you can use business mode by
+including the appropriate string (see documentation on DateCalc) in the
+Date or Delta. So (in English), the first workday before Christmas could
+be defined as:
+
+ 12/25 - 1 business day =
+
+The date's may optionally contain the year. For example, the dates
+
+ 1/1
+ 1/1/1999
+
+refers to Jan 1 in any year or in only 1999 respectively. For dates that
+refer to any year, the date must be written such that by simply appending
+the year (separated by spaces) it can be correctly interpreted. This
+will work for everything except ISO 8601 dates, so ISO 8601 dates may
+not be used in this case.
+
+In cases where you are interested in business type calculations, you'll
+want to define most holidays using recurrences, since they can define
+when a holiday is celebrated in the financial world. For example,
+Christmas chould be defined as:
+
+ 1*12:0:24:0:0:0*FW1 = Christmas
+
+NOTE: It was pointed out to me that using a similar type recurrence to
+define New Years does not work. The recurrence:
+
+ 1*12:0:31:0:0:0*FW1
+
+fails (worse, it goes into an infinite loop). The problem is that each
+holiday definition is applied to a specific year and it expects to find
+the holiday for that year. When this recurrence is applied to the year
+1995, it returns the holiday for 1996 and fails.
+
+Use the recurrence:
+
+ 1*1:0:1:0:0:0*NWD
+
+instead.
+
+If you wanted to define both Christmas and Boxing days (Boxing is the
+day after Christmas, and is celebrated in some parts of the world), you
+could do it in one of the following ways:
+
+ 1*12:0:24:0:0:0*FW1 = Christmas
+ 1*12:0:25:0:0:0*FW1 = Boxing
+
+ 1*12:0:24:0:0:0*FW1 = Christmas
+ 01*12:0:24:0:0:0*FW1 = Boxing
+
+ 1*12:0:24:0:0:0*FW1 = Christmas
+ 1*12:0:25:0:0:0*FW1,a = Boxing
+
+The following examples will NOT work:
+
+ 1*12:0:24:0:0:0*FW1 = Christmas
+ 1*12:0:24:0:0:0*FW2 = Boxing
+
+ 1*12:0:24:0:0:0*FW1 = Christmas
+ 1*12:0:24:0:0:0*FW1 = Boxing
+
+The reasoning behind all this is as follows:
+
+Holidays go into affect the minute they are parsed. So, in the case of:
+
+ 1*12:0:24:0:0:0*FW1 = Christmas
+ 1*12:0:24:0:0:0*FW2 = Boxing
+
+the minute the first line is parsed, Christmas is defined as a holiday.
+The second line then steps forward 2 work days (skipping Christmas since
+that's no longer a work day) and define the work day two days after
+Christmas, NOT the day after Christmas.
+
+An good alternative would appear to be:
+
+ 1*12:0:24:0:0:0*FW1 = Christmas
+ 1*12:0:24:0:0:0*FW1 = Boxing
+
+This unfortunately fails because the recurrences are currently stored in a
+hash. Since these two recurrences are identical, they fail (the first one
+is overwritten by the second and in essense, Christmas is never defined).
+
+To fix this, make them unique with either a fake flag (which is ignored):
+
+ 1*12:0:24:0:0:0*FW1,a = Boxing
+
+or adding an innocuous 0 somewhere:
+
+ 01*12:0:24:0:0:0*FW1 = Boxing
+
+The other good alternative would be to make two completely different
+recurrences such as:
+
+ 1*12:0:24:0:0:0*FW1 = Christmas
+ 1*12:0:25:0:0:0*FW1 = Boxing
+
+At times, you may want to switch back and forth between two holiday files.
+This can be done by calling the following:
+
+ &Date_Init("EraseHolidays=1","PersonalCnf=FILE1");
+ ...
+ &Date_Init("EraseHolidays=1","PersonalCnf=FILE2");
+ ...
+
+=head1 EVENTS SECTION
+
+The Events section of the config file is similar to the Holiday section.
+It is used to name certain days or times, but there are a few important
+differences:
+
+=over 4
+
+=item Events can be assigned to any time and duration
+
+All holidays are exactly 1 day long. They are assigned to a period
+of time from midnight to midnight.
+
+Events can be based at any time of the day, and may be of any duration.
+
+=item Events don't affect business mode calculations
+
+Unlike holidays, events are completely ignored when doing business
+mode calculations.
+
+=back
+
+Whereas holidays were added with business mode math in mind, events
+were added with calendar and scheduling applications in mind.
+
+Every line in the events section is of the form:
+
+ EVENT = NAME
+
+where NAME is the name of the event, and EVENT defines when it occurs
+and it's duration. An EVENT can be defined in the following ways:
+
+ Date
+ Date*
+ Recur [NYI]
+ Recur* [NYI]
+
+ Date ; Date
+ Date ; Delta
+ Recur ; Delta [NYI]
+
+ Date ; Delta ; Delta [NYI]
+ Recur ; Delta ; Delta [NYI]
+
+Here, Date* refers to a string containing a Date with NO TIME fields
+(Jan 12, 1/1/2000, 2010-01-01) while Date does contain time fields.
+Similarily, Recur* stands for a recurrence with the time fields all
+equal to 0) while Recur stands for a recurrence with at least one
+non-zero time field.
+
+Both Date* and Recur* refer to an event very similar to a holiday which
+goes from midnight to midnight.
+
+Date and Recur refer to events which occur at the time given and with
+a duration of 1 hour.
+
+Events given by "Date ; Date", "Date ; Delta", and "Recur ; Delta"
+contain both the starting date and either ending date or duration.
+
+Events given as three elements "Date ; Delta ; Delta" or "Recur ; Delta ;
+Delta" take a date and add both deltas to it to give the starting and
+ending time of the event. The order and sign of the deltas is
+unimportant (and both can be the same sign to give a range of times
+which does not contain the base date).
+
+Items marked with [NYI] are not yet implemented but will be by the
+time this is released.
+
+=head1 BACKWARDS INCOMPATIBILITIES
+
+For the most part, Date::Manip has remained backward compatible at every
+release. There have been a few minor incompatibilities introduced at
+various stages. Major differences are marked with bullets.
+
+=over 4
+
+=item VERSION 5.41
+
+=item Changed path separator for VMS
+
+Since ":" is used in some VMS paths, it should not have been used as
+the path separator. It has been changed to a newline ("\n") character.
+
+=item Delta_Format behavior changed
+
+The entire delta is exact if no month component is present (previously,
+no year or month component could be present).
+
+=item VERSION 5.38
+
+=item Removed Date_DaysSince999
+
+The Date_DaysSince999 function (deprecated in 5.35) has been removed.
+
+=item VERSION 5.35
+
+=over 4
+
+=item Deprected Date_DaysSince999
+
+In fixing support for the years 0000-0999, I rewrote Date_DaysSince999 to
+be Date_DaysSince1BC. The Date_DaysSince999 function will be removed.
+
+=item * Added PathSep variable
+
+In order to better support Win32 platforms, I added the PathSep config
+variable. This will allow the use of paths such as "c:\date" on Win32
+platforms. Old config files on Win32 platforms (which were not working
+correctly in many cases) may not work if they contain path information to
+the personal config file.
+
+=back
+
+=item VERSION 5.34
+
+=over 4
+
+=item * All Date::Manip variables are no longer accessible
+
+Previously, Date::Manip variables were declared using a full package name.
+Now, they are declared with the my() function. This means that internal
+variables are no longer accessible outside of the module.
+
+=item Week interpretation in business mode deltas
+
+A business mode delta containing a week value used to be treated as 7 days.
+A much more likely interpretation of a week is Monday to Monday, regardless
+of holidays, so this is now the behavior.
+
+=item %z UnixDate format
+
+The %z UnixDate format used to return the Timezone abbreviation. It now
+returns it as a GMT offset (i.e. -0500). %Z still returns the Timezone
+abbreviation.
+
+=item Formats "22nd sunday" returns the intuitive value
+
+The date "22nd sunday" used to return the Sunday of the 22nd week of the
+year (which could be the 21st, 22nd, or 23rd Sunday of the year depending
+on how weeks were defined). Now, it returns the 22nd Sunday of the year
+regardless.
+
+=item Separator in DD/YYmmm and mmmDD/YY formats no longer optional
+
+Previously, the date "Dec1065" would return Dec 10, 1965. After adding
+the YYYYmmm and mmmYYYY formats, this was no longer possible. The separator
+between DD and YY is no longer optional, so
+
+ Dec1065 returns December 1, 1065
+ Dec10/65 returns December 10, 1965
+
+=item * Date_Cmp added
+
+This is not a backwards incompatibility... but is added to help prepare for
+a future incompatibility. In one of the next versions of Date::Manip, the
+internal format of the date will change to include timezone information.
+All date comparisons should be made using Date_Cmp (which currently does
+nothing more than call the perl "cmp" command, but which will important
+when comparing dates that include the timezone).
+
+=back
+
+=item VERSION 5.32
+
+=over 4
+
+=item Date_Init arguments
+
+The old style Date_Init arguments that were deprecated in version 5.07
+have been removed.
+
+=item * DateManip.cnf change
+
+Changed .DateManip.cnf to Manip.cnf (to get rid of problems on OS's
+that insist on 8.3 filenames) for all non-Unix platforms (Wintel, VMS,
+Mac). For all Unix platforms, it's still .DateManip.cnf . It will only
+look in the user's home directory on VMS and Unix.
+
+=back
+
+=item VERSION 5.30
+
+=over 4
+
+=item * Delta format changed
+
+A week field has been added to the internal format of the delta. It now
+reads "Y:M:W:D:H:MN:S" instead of "Y:M:D:H:MN:S".
+
+=back
+
+=item VERSION 5.21
+
+=over 4
+
+=item Long running processes may give incorrect timezone
+
+A process that runs during a timezone change (Daylight Saving Time
+specifically) may report the wrong timezone. See the UpdateCurrTZ variable
+for more information.
+
+=item UnixDate "%J", "%W", and "%U" formats fixed
+
+The %J, %W, and %U will no longer report a week 0 or a week 53 if it should
+really be week 1 of the following year. They now report the correct week
+number according to ISO 8601.
+
+=back
+
+=item VERSION 5.20
+
+=over 4
+
+=item * ParseDate formats removed (ISO 8601 compatibility)
+
+Full support for ISO 8601 formats was added. As a result, some formats
+which previously worked may no longer be parsed since they conflict with an
+ISO 8601 format. These include MM-DD-YY (conflicts with YY-MM-DD) and
+YYMMDD (conflicts with YYYYMM). MM/DD/YY still works, so the first form
+can be kept easily by changing "-" to "/". YYMMDD can be changed to
+YY-MM-DD before being parsed. Whenever parsing dates using dashes as
+separators, they will be treated as ISO 8601 dates. You can get around
+this by converting all dashes to slashes.
+
+=item * Week day numbering
+
+The day numbering was changed from 0-6 (sun-sat) to 1-7 (mon-sun) to be
+ISO 8601 compatible. Weeks start on Monday (though this can be overridden
+using the FirstDay config variable) and the 1st week of the year contains
+Jan 4 (though it can be forced to contain Jan 1 with the Jan1Week1 config
+variable).
+
+=back
+
+=item VERSION 5.07
+
+=over 4
+
+=item UnixDate "%s" format
+
+Used to return the number of seconds since 1/1/1970 in the current
+timezone. It now returns the number of seconds since 1/1/1970 GMT.
+The "%o" format was added which returns what "%s" previously did.
+
+=item Internal format of delta
+
+The format for the deltas returned by ParseDateDelta changed. Previously,
+each element of a delta had a sign attached to it (+1:+2:+3:+4:+5:+6). The
+new format removes all unnecessary signs by default (+1:2:3:4:5:6). Also,
+because of the way deltas are normalized (see documentation on
+ParseDateDelta), at most two signs are included. For backwards
+compatibility, the config variable DeltaSigns was added. If set to 1, all
+deltas include all 6 signs.
+
+=item Date_Init arguments
+
+The format of the Date_Init calling arguments changed. The
+old method
+
+ &Date_Init($language,$format,$tz,$convtz);
+
+is still supported , but this support will likely disappear in the future.
+Use the new calling format instead:
+
+ &Date_Init("var=val","var=val",...);
+
+NOTE: The old format is no longer supported as of version 5.32 .
+
+=back
+
+=back
+
+=head1 KNOWN PROBLEMS
+
+The following are not bugs in Date::Manip, but they may give some people
+problems.
+
+=over 4
+
+=item Unable to determine TimeZone
+
+Perhaps the most common problem occurs when you get the error:
+
+ Error: Date::Manip unable to determine TimeZone.
+
+Date::Manip tries hard to determine the local timezone, but on some
+machines, it cannot do this (especially non-unix systems). To fix this,
+just set the TZ variable, either at the top of the Manip.pm file,, in the
+DateManip.cnf file, or in a call to Date_Init. I suggest using the form
+"EST5EDT" so you don't have to change it every 6 months when going to or
+from daylight savings time.
+
+Windows NT does not seem to set the TimeZone by default. From the
+Perl-Win32-Users mailing list:
+
+ > How do I get the TimeZone on my NT?
+ >
+ > $time_zone = $ENV{'TZ'};
+ >
+ You have to set the variable before, WinNT doesn't set it by
+ default. Open the properties of "My Computer" and set a SYSTEM
+ variable TZ to your timezone. Jenda@Krynicky.cz
+
+This might help out some NT users.
+
+A minor (false) assumption that some users might make is that since
+Date::Manip passed all of it's tests at install time, this should not occur
+and are surprised when it does.
+
+Some of the tests are timezone dependent. Since the tests all include
+input and expected output, I needed to know in advance what timezone they
+would be run in. So, the tests all explicitly set the timezone using the
+TZ configuration variable passed into Date_Init. Since this overrides any
+other method of determining the timezone, Date::Manip uses this and doesn't
+have to look elsewhere for the timezone.
+
+When running outside the tests, Date::Manip has to rely on it's other
+methods for determining the timezone.
+
+=item Complaining about getpwnam/getpwuid
+
+Another problem is when running on Micro$oft OS'es. I have added many
+tests to catch them, but they still slip through occasionally. If any ever
+complain about getpwnam/getpwuid, simply add one of the lines:
+
+ $ENV{OS} = Windows_NT
+ $ENV{OS} = Windows_95
+
+to your script before
+
+ use Date::Manip
+
+=item Date::Manip is slow
+
+The reasons for this are covered in the SHOULD I USE DATE::MANIP section
+above.
+
+Some things that will definitely help:
+
+Version 5.21 does run noticeably faster than earlier versions due to
+rethinking some of the initialization, so at the very least, make sure you
+are running this version or later.
+
+ISO-8601 dates are parsed first and fastest. Use them whenever possible.
+
+Avoid parsing dates that are referenced against the current time (in 2
+days, today at noon, etc.). These take a lot longer to parse.
+
+ Example: parsing 1065 dates with version 5.11 took 48.6 seconds, 36.2
+ seconds with version 5.21, and parsing 1065 ISO-8601 dates with version
+ 5.21 took 29.1 seconds (these were run on a slow, overloaded computer with
+ little memory... but the ratios should be reliable on a faster computer).
+
+Business date calculations are extremely slow. You should consider
+alternatives if possible (i.e. doing the calculation in exact mode and then
+multiplying by 5/7). There will be an approximate business mode in one of
+the next versions which will be much faster (though less accurate) which
+will do something like this. Whenever possible, use this mode. And who
+needs a business date more accurate than "6 to 8 weeks" anyway huh :-)
+
+Never call Date_Init more than once. Unless you're doing something very
+strange, there should never be a reason to anyway.
+
+=item Sorting Problems
+
+If you use Date::Manip to sort a number of dates, you must call Date_Init
+either explicitly, or by way of some other Date::Manip routine before it
+is used in the sort. For example, the following code fails:
+
+ use Date::Manip;
+ # &Date_Init;
+ sub sortDate {
+ my($date1, $date2);
+ $date1 = &ParseDate($a);
+ $date2 = &ParseDate($b);
+ return (&Date_Cmp($date1,$date2));
+ }
+ @dates = ("Fri 16 Aug 96",
+ "Mon 19 Aug 96",
+ "Thu 15 Aug 96");
+ @i=sort sortDate @dates;
+
+but if you uncomment the Date_Init line, it works. The reason for this is
+that the first time you call Date_Init, it initializes a number of items
+used by Date::Manip. Some of these have to be sorted (regular expressions
+sorted by length to ensure the longest match). It turns out that perl
+has a bug in it which does not allow a sort within a sort. At some point,
+this should be fixed, but for now, the best thing to do is to call Date_Init
+explicitly. The bug exists in all versions up to 5.005 (I haven't
+tested 5.6.0 yet).
+
+NOTE: This is an EXTREMELY inefficient way to sort data. Instead, you
+should parse the dates with ParseDate, sort them using a normal string
+comparison, and then convert them back to the format desired using
+UnixDate.
+
+=item RCS Control
+
+If you try to put Date::Manip under RCS control, you are going to have
+problems. Apparently, RCS replaces strings of the form "$Date...$" with
+the current date. This form occurs all over in Date::Manip. To prevent the
+RCS keyword expansion, checkout files using "co -ko". Since very few people
+will ever have a desire to do this (and I don't use RCS), I have not worried
+about it.
+
+=back
+
+=head1 KNOWN BUGS
+
+=over 4
+
+=item Daylight Savings Times
+
+Date::Manip does not handle daylight savings time, though it does handle
+timezones to a certain extent. Converting from EST to PST works fine.
+Going from EST to PDT is unreliable.
+
+The following examples are run in the winter of the US East coast (i.e.
+in the EST timezone).
+
+ print UnixDate(ParseDate("6/1/97 noon"),"%u"),"\n";
+ => Sun Jun 1 12:00:00 EST 1997
+
+June 1 EST does not exist. June 1st is during EDT. It should print:
+
+ => Sun Jun 1 00:00:00 EDT 1997
+
+Even explicitly adding the timezone doesn't fix things (if anything, it
+makes them worse):
+
+ print UnixDate(ParseDate("6/1/97 noon EDT"),"%u"),"\n";
+ => Sun Jun 1 11:00:00 EST 1997
+
+Date::Manip converts everything to the current timezone (EST in this case).
+
+Related problems occur when trying to do date calculations over a timezone
+change. These calculations may be off by an hour.
+
+Also, if you are running a script which uses Date::Manip over a period of
+time which starts in one time zone and ends in another (i.e. it switches
+form Daylight Savings Time to Standard Time or vice versa), many things may
+be wrong (especially elapsed time).
+
+I hope to fix these problems in a future release so that it would convert
+everything to the current zones (EST or EDT).
+
+=back
+
+=head1 BUGS AND QUESTIONS
+
+If you find a bug in Date::Manip, please send it directly to me (see the
+AUTHOR section below) rather than posting it to one of the newsgroups.
+Although I try to keep up with the comp.lang.perl.* groups, all too often I
+miss news (flaky news server, articles expiring before I caught them, 1200
+articles to wade through and I missed one that I was interested in, etc.).
+
+When filing a bug report, please include the following information:
+
+ o The version of Date::Manip you are using. You can get this by using
+ the script:
+
+ use Date::Manip;
+ print &DateManipVersion(),"\n";
+
+ o The output from "perl -V"
+
+If you have a problem using Date::Manip that perhaps isn't a bug (can't
+figure out the syntax, etc.), you're in the right place. Go right back to
+the top of this man page and start reading. If this still doesn't answer
+your question, mail me (again, please mail me rather than post to the
+newsgroup).
+
+=head1 YEAR 2000
+
+In hindsight, the fact that I've only been asked once (so far) if Date::Manip
+is year 2000 compliant surprises me a bit. Still, as 2000 approaches and
+this buzzword starts flying around more and more frantically, other's might
+follow suit, so this section answers the question.
+
+Is Date::Manip year 2000 compliant?
+
+This question is largely meaningless. Date::Manip is basically just a
+parser. You give it a date and it'll manipulate it. Date::Manip does
+store the date internally as a 4 digit year, and performs all operations
+using this internal representation, so I will state that Date::Manip is
+CAPABLE of writing Y2K compliant code.
+
+But Date::Manip is simply a library. If you use it correctly, your code
+can be Y2K compliant. If you don't, your code may not be Y2K compliant.
+
+The bottom line is this:
+
+ Date::Manip is a library that is capable of being used to write Y2K
+ compliant code. It may also be used to write non-Y2K compliant code.
+
+ If your code is NOT Y2K compliant, it is NOT due to any deficiency in
+ Date::Manip. Rather, it is due to poor programming on the part of the
+ person using Date::Manip.
+
+For an excellent treatment of the Y2K problem, see the article by Tom
+Christiansen at:
+
+ http://language.perl.com/news/y2k.html
+
+A slightly better question is "Is Perl year 2000 compliant"? This is
+covered in the perl FAQ (section 4) and in the article by Tom Crhistiansen.
+
+The best question is "For what dates is Date::Manip useful?" It definitely
+can't handle BC dates, or dates past Dec 31, 9999. So Date::Manip works
+during the years 1000 to 9999.
+
+In practical terms however, Date::Manip deals with the Gregorian calendar,
+and is therefore useful in the period that that calendar has been, or will
+be, in effect. The Gregorian calendar was first adopted by the Catholic
+church in 1582, but some countries were still using the Julian calendar as
+late as the early part of the 20th century. Also, at some point (probably
+no earlier than the year 3000 and possibly much later), the Gregorian
+system is going to have to be modified slightly since the current system of
+leap years is off by a few seconds a year. So... in practical terms,
+Date::Manip is _probably_ useful from 1900 to 3000.
+
+One other note is that Date::Manip will NOT handle 3 digit years. So, if
+you store the year as an offset from 1900 (which is 2 digits now, but will
+become 3 digits in 2000), these will NOT be parsable by Date::Manip.
+
+=head1 VERSION NUMBERS
+
+A note about version numbers.
+
+Prior to version 5.00, Date::Manip was distributed as a perl4 library.
+There were no numbering conventions in place, so I used a simple
+MAJOR.MINOR numbering scheme.
+
+With version 5.00, I switched to a perl5 module and at that time switched
+to the perl5 numbering convention of a major version followed by a 2 digit
+minor version.
+
+As of 5.41/5.42, all versions released to CPAN will be even numbered. Odd
+numbered will be development versions available from my web site. For
+example, after 5.40 was released, I started making changes, and called
+the development version 5.41. When released to CPAN, it was called 5.42.
+I may add a third digit to development versions (i.e. 5.41.9) to keep
+track of important changes in the development version.
+
+=head1 ACKNOWLEDGMENTS
+
+There are many people who have contributed to Date::Manip over the years
+that I'd like to thank. The most important contributions have come in the
+form of suggestions and bug reports by users. I have tried to include the
+name of every person who first suggested each improvement or first reported
+each bug. These are included in the HISTORY file in the Date::Manip
+distribution in the order the changes are made. The list is simply too
+long to appear here, but I appreciate their help.
+
+A number of people have made suggestions or reported bugs which are not
+mentioned in the HISTORY file. These include suggestions which have not
+been implemented and people who have made a suggestion or bug report which
+has already been suggested/reported by someone else. For those who's
+suggestions have not yet been implemented, they will be added to the
+HISTORY file when (if) their suggestions are implemented. For everyone
+else, thank you too. I'd much rather have a suggestion made twice than not
+at all.
+
+Thanks to Alan Cezar and Greg Schiedler for paying me to implement the
+Events_List routine. They gave me the idea, and were then willing to pay
+me for my time to get it implemented quickly.
+
+I'd also like a couple of authors. Date::Manip has recently been getting
+some really good press in a couple of books. Since no one's paying me to
+write Date::Manip, seeing my module get a good review in a book written by
+someone else really makes my day. My thanks to Nate Padwardhan and Clay
+Irving (Programming with Perl Modules -- part of the O'Reilly Perl Resource
+Kit); and Tom Christiansen and Nathan Torkington (The Perl Cookbook).
+Also, thanks to any other authors who've written about Date::Manip who's
+books I haven't seen.
+
+=head1 AUTHOR
+
+Sullivan Beck (sbeck@cpan.org)
+
+You can always get the newest beta version of Date::Manip (which may fix
+problems in the current CPAN version... and may add others) from my home
+page:
+
+http://www.cise.ufl.edu/~sbeck/
+
+=cut