--- a/dummy_foundation/lib/Date/Manip.pod Wed Jun 03 18:33:51 2009 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,2755 +0,0 @@
-# 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