Unix/Linux Go Back    


CentOS 7.0 - man page for date::manip::dm5 (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Date::Manip::DM5(3)	       User Contributed Perl Documentation	      Date::Manip::DM5(3)

NAME
       Date::Manip::DM5 - Date manipulation routines

SYNOPSIS
	use Date::Manip;

	$version = DateManipVersion;

	Date_Init();
	Date_Init("VAR=VAL","VAR=VAL",...);
	@list = Date_Init();
	@list = Date_Init("VAR=VAL","VAR=VAL",...);

	$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);

	$name = Date_IsHoliday($date);

	$listref = Events_List($date);
	$listref = Events_List($date0,$date1);

	$date = Date_ConvTZ($date);
	$date = Date_ConvTZ($date,$from);
	$date = Date_ConvTZ($date,"",$to);
	$date = Date_ConvTZ($date,$from,$to);

	$flag = Date_IsWorkDay($date [,$flag]);

	$date = Date_NextWorkDay($date,$off [,$flag]);

	$date = Date_PrevWorkDay($date,$off [,$flag]);

	$date = Date_NearestWorkDay($date [,$tomorrowfirst]);

       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
       explicitly unless you want to change some of the config variables (described below).  They
       also do error checking on the input.

       The routines listed below are intended primarily for internal use by other Date::Manip
       routines.  They do little or no error checking, and do not explicitly call Date_Init.
       Those functions are all done in the main Date::Manip routines above.

       Because they are significantly faster than the full Date::Manip routines, they are
       available for use with a few caveats.  Since little or no error checking is done, it is
       the responsibility of the programmer to ensure that valid data (AND valid dates) are
       passed to them.	Passing invalid data (such as a non-numeric month) or invalid dates (Feb
       31) will fail in unpredictable ways (possibly returning erroneous results).  Also, since
       Date_Init is not called by these, it must be called explicitly by the programmer before
       using these routines.

       In the following routines, $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).

	$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);
	($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
	$days = Date_DaysInYear($y);
	$days = Date_DaysInMonth($m,$y);
	$wkno = Date_WeekOfYear($m,$d,$y,$first);
	$flag = Date_LeapYear($y);
	$day = Date_DaySuffix($d);
	$tz = Date_TimeZone();

ROUTINES
       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.

       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.

       ParseDateString
	    $date = ParseDateString($string);

	   This routine is called by ParseDate, but it may also be called directly to save some
	   time (a negligible 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 time zone.  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 occurring).

	   Time zones always appear immediately after the time.  A number of different forms are
	   supported (see the section TIME ZONES 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.  In all cases, the
	   date and time parts may be separated by the letter "T" (but this is optional), so
	      2002-12-10-12:00:00
	      2002-12-10T12:00:00 are identical.

	   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 time zone for an ISO-8601 date is
	   flexible and may be any of the time zones 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
	   behaviors.  "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 specified)
	     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 time zone.

       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
	    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
	    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, Time zone
		%M     minute			- 00 to 59
		%S     second			- 00 to 59
		%Z     time zone		- "EDT"
		%z     time zone as GMT offset	- "+0100"
	    Epoch (see NOTE 3 below)
		%s     seconds from 1/1/1970 GMT- negative if before 1/1/1970
		%o     seconds from Jan 1, 1970
		       in the current time zone
	    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     %m/%d/%y 		- 04/28/95
		%x     %m/%d/%y or %d/%m/%y	- 04/28/95 or 28/04/28
						  (Depends on DateFormat variable)
		%l     date in ls(1) format (see NOTE 1 below)
			 %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
		%O     %Y-%m-%dT%H:%M:%S	- 1996-10-25T17:40:58
		%F     %A, %B %e, %Y		- Sunday, January  1, 1996
		%K     %Y-%j			- 1997-045
	    Special Year/Week formats (see NOTE 2 below)
		%G     year, Monday as first
		       day of week		- 0001 to 9999
		%W     week of year, Monday
		       as first day of week	- 01 to 53
		%L     year, Sunday as first
		       day of week		- 0001 to 9999
		%U     week of year, Sunday
		       as first day of week	- 01 to 53
		%J     %G-W%W-%w		- 1997-W02-2
	    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:
		N 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.

	   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.

	   NOTE 1:

	   The ls format (%l) applies to date within the past OR future 6 months!

	   NOTE 2:

	   The %U, %W, %L, %G, and %J 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 both common choices, so both are supported.

	   The %W and %G formats return the week-of-year and the year treating weeks as starting
	   on Monday.

	   The %U and %L formats return the week-of-year and the year treating weeks as starting
	   on Sunday.

	   Most of the time, the %L and %G formats returns the same value as the %Y format, but
	   there is a problem with days occurring in the first or last week of the year.

	   The ISO-8601 representation of Jan 1, 1993 written in the YYYY-wWW-D format is
	   actually 1992-W53-5.  In other words, Jan 1 is treated 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 week is assigned to the year which has most of the days.  For example,
	   if the week starts on Sunday, then the last week of 2003 is 2003-12-28 to 2004-01-03.
	   This week is assigned to 2003 since 4 of the days in it are in 2003 and only 3 of them
	   are in 2004.  The first week of 2004 starts on 2004-01-04.

	   The %U and %W formats return a week-of-year number from 01 to 53. %L and %G return the
	   corresponding year, and to get this type of information, you should always use the
	   (%W,%G) combination or (%U,%L) combination. %Y should not be used as it will yield
	   incorrect results.

	   %J returns the full ISO-8601 format (%G-W%W-%w).

	   NOTE 3:

	   The %s and %o formats return negative values if the date is before the start of the
	   epoch.  Other Unix utilities would return an error, or a zero, so if you are going to
	   use Date::Manip in conjunction with these, be sure to check for a negative value.

       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 whitespace.

	   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.

       Delta_Format
	    @str = Delta_Format($delta [,$mode], $dec,@format);
	    $str = Delta_Format($delta [,$mode], $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 "%"

	   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.

	   Delta_Format can operate in two modes: exact and approximate. The exact mode is done
	   by default. Approximate mode can be done by passing in the string "approx" as the 2nd
	   argument.

	   In exact mode, Delta_Format only understands "exact" relationships. This means that
	   there can be no mixing of the Y/M and W/D/H/MN/S segments because the relationship
	   because, depending on when the delta occurs, there is no exact relation between the
	   number of years or months and the number of days.

	   The two sections are treated completely separate from each other. So, the delta
	   "1:6:1:2:12:0:0" would return the following values:

	     %yt = 1.5 (1 year, 6 months)
	     %Mt = 18

	     %dt = 9.5 (1 week, 2 days, 12 hours)

	   In approximate mode, the relationship of 1 year = 365.25 days is applied (with 1 month
	   equal to 1/12 of a year exactly). So the delta "1:6:1:2:12:0:0" would return the
	   following values:

	     %dt = 557.375 (1.5 years of 365.25 days + 9.5 days)

	   If $dec is non-zero, the %Xd and %Xt values are formatted to contain $dec decimal
	   places.

       ParseRecur
	    $recur = ParseRecur($string [,$base,$date0,$date1,$flags]);
	    @dates = ParseRecur($string [,$base,$date0,$date1,$flags]);

	   A recurrence refers to a recurring event, and more specifically, an event which occurs
	   on a regular basis.	A fully specified recurring event may requires up to four pieces
	   of information.

	   First, it requires a description of the frequency of the event.  Examples include "the
	   first of every month", "every other day", "the 4th Thursday of each month at 2:00 PM",
	   and "every 2 hours and 30 minutes".

	   Second, it may require a base date to work from.  This piece of information is not
	   required for every type of recurrence.  For example, if the frequency is "the first of
	   every month", no base date is required.  All the information about when the event
	   occurs is included in the frequency description.  If the frequency were "every other
	   day" though, you need to know at least one day on which the event occurred.

	   Third, the recurring event may have a range (a starting and ending date).

	   Fourth, there may be some flags included which modify the behavior of the above
	   information.

	   The fully specified recurrence is written as these 5 pieces of information (both a
	   start and end date) as an asterisk separated list:

	     freq*flags*base*date0*date1

	   Here, base, date0, and date1 are any strings (which must not contain any asterisks)
	   which can be parsed by ParseDate.  flags is a comma separated list of flags (described
	   below), and freq is a string describing the frequency of the recurring event.

	   The syntax of the frequency description is a colon separated list of the format
	   Y:M:W:D:H:MN:S (which stand for year, month, week, etc.).  One (and only one) of the
	   colons may optionally be replaced by an asterisk, or an asterisk may be prepended to
	   the string.	For example, the following are all valid frequency descriptions:

	     1:2:3:4:5:6:7
	     1:2*3:4:5:6:7
	    *1:2:3:4:5:6:7

	   But the following are NOT valid because they contain 2 or more asterisks:

	     1:2*3:4:5*6:7
	     1*2*3:4:5*6:7
	    *1:2:3:4:5:6*7

	   If an asterisk is included, values to the left of it refer to the number of times that
	   time interval occurs between recurring events.  For example, if the first part of the
	   recurrence is:

	     1:2*

	   this says that the recurring event occurs approximately every 1 year and 2 months.  I
	   say approximately, because elements to the right of the asterisk, as well as any flags
	   included in the recurrence will affect when the actual events occur.

	   If no asterisks are included, then the entire recurrence is of this form.  For
	   example,

	     0:0:0:1:12:0:0

	   refers to an event that occurs every 1 day, 12 hours.

	   Values that occur after an asterisk refer to a specific value for that type of time
	   element (i.e. exactly as it would appear on a calendar or a clock).	For example, if
	   the recurrence ends with:

	     *12:0:0

	   then the recurring event occurs at 12:00:00 (noon).

	   For 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)

	   Values to the right of the asterisk can be listed a single values, ranges (2 numbers
	   separated by a dash "-"), or a comma separated list of values or ranges.  In most
	   cases, negative values are appropriate for the week or day values. -1 stands for the
	   last possible value, -2 for the second to the last, etc.

	   Some examples are:

	     0:0:0:1*2,4,6:0:0	  every day at at 2:00, 4:00, and 6:00
	     0:0:0:2*12-13:0,30:0 every other day at 12:00, 12:30, 13:00,
				  and 13:30
	     0:1:0*-1:0:0:0	  the last day of every month
	     *1990-1995:12:0:1:0:0:0
				  Dec 1 in 1990 through 1995

	   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.

	   When a non-zero day element occurs to the right of the asterisk, it can take on
	   multiple meanings, depending on the value of the month and week elements.  It can
	   refer to the day of the week, day of the month, or day of the year.	Similarly, if a
	   non-zero week element occurs to the right of the asterisk, it actually refers to the
	   nth time a certain day of the week occurs, either in the month or in the year.

	   If the week element is non-zero and the day element is non-zero (and to the right of
	   the asterisk), the day element refers to the day of the week. It can be any value from
	   1 to 7 (negative values -1 to -7 are also allowed). If you use the ISO 8601
	   convention, the first day of the week is Monday (though Date::Manip can use any day as
	   the start of the week by setting the FirstDay config variable).  So, assuming that you
	   are using the ISO 8601 convention, the following examples illustrate day-of-week
	   recurrences:

	     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:0:3*2:0:0:0	  every 3rd Tuesday (every 3 weeks
				  on 2nd day of week)
	     1:0*12:2:0:0:0	  the 12th Tuesday of each year

	   If the week element is non-zero, and the day element is zero, the day defaults to 1
	   (i.e. the first day of the week).

	     0:1*2:0:0:0:0	  the 2nd occurrence of FirstDay
				  in the year (typically Monday)
	     0:1*2:1:0:0:0	  the same

	   If the week element is zero and the month element is non-zero, the day value is the
	   day of the month (it can be from 1 to 31 or -1 to -31 counting from the end of the
	   month). If a value of 0 is given, it defaults to 1.

	     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
	     0:1:0*-2:0:0:0	  2nd to last day of every month

	   If the day given refers to the 29th, 30th, or 31st, in a month that does not have that
	   number of days, it is ignored. For example, if you ask for the 31st of every month, it
	   will return dates in Jan, Mar, May, Jul, etc.  Months with fewer than 31 days will be
	   ignored.

	   If both the month and week elements are zero, and the year element is non-zero, the
	   day value is the day of the year (1 to 365 or 366 -- or the negative numbers to count
	   backwards from the end of the year).

	     1:0:0*45:0:0:0	  45th day of every year

	   Specifying a day that doesn't occur in that year silently ignores that year. The only
	   result of this is that specifying +366 or -366 will ignore all years except leap
	   years.

	   I realize that this looks a bit cryptic, but after a discussion on the CALENDAR
	   mailing list, it appeared 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. Even better, it is able to
	   express every type of recurring event I could think of that is used in common life in
	   (what I believe to be) a very concise and elegant way.

	   If ParseRecur is 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:

	     freq
	     freq*flags
	     freq**base*date0*date1

	   The only part which is required is the frequency description.  Any values contained in
	   $string are overridden or modified by values passed in as parameters to ParseRecur.

	   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: 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:

	     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).

	   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).

       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 time zones.  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 time zone information is kept as part of
	   the date), this routine will become more important.	You should use this routine in
	   preparation for that version.

       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).

	   Since the two items can be interpreted as either dates or deltas, and since many types
	   of dates can be interpreted as deltas (and vice versa), it is a good idea to pass the
	   input through ParseDate or ParseDateDelta as appropriate. For example, the string
	   "09:00:00" can be interpreted either as a date (today at 9:00:00) or a delta (9
	   hours). To avoid unexpected results, avoid calling DateCalc as:

	     $d = DateCalc("09:00:00",$someothervalue);

	   Instead, call it as:

	     $d = DateCalc(ParseDate("09:00:00"),$someothervalue);

	   to force it to be a date, or:

	     $d = DateCalc(ParseDateDelta("09:00:00"),$someothervalue);

	   to force it to be a delta. This will avoid unexpected results.

	   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 (in the generals case) how many days are in 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 saving time) is returned in weeks, 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 Date::Manip::Calc 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.

       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.

       Date_SetDateField
	    $date = Date_SetDateField($date,$field,$val [,$nocheck]);

	   This takes a date and sets one of its 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.

       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

       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.

       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.

       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.

       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.

       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.

       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.

       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.

       Date_DayOfYear
	    $day = Date_DayOfYear($m,$d,$y);

	   Returns the day of the year (001 to 366)

	   All arguments must be numeric.

       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 time line
	   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.

       Date_DaysInYear
	    $days = Date_DaysInYear($y);

	   Returns the number of days in the year (365 or 366)

       Date_DaysInMonth
	    $days = Date_DaysInMonth($m,$y);

	   Returns the number of days in the month.

       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.

       Date_LeapYear
	    $flag = Date_LeapYear($y);

	   Returns 1 if the argument is a leap year Written by David Muir Sharnoff
	   <muir@idiom.com>

       Date_DaySuffix
	    $day = Date_DaySuffix($d);

	   Add `st', `nd', `rd', `th' to a date (i.e. 1st, 22nd, 29th).  Works for international
	   dates.

       Date_TimeZone
	    $tz = Date_TimeZone;

	   This determines and returns the local time zone.  If it is unable to determine the
	   local time zone, the following error occurs:

	      ERROR: Date::Manip unable to determine Time Zone.

	   See The TIME ZONES section below for more information.

       Date_ConvTZ
	    $date = Date_ConvTZ($date);
	    $date = Date_ConvTZ($date,$from);
	    $date = Date_ConvTZ($date,"",$to [,$errlev]);
	    $date = Date_ConvTZ($date,$from,$to [,$errlev]);

	   This converts a date (which MUST be in the format returned by ParseDate) from one time
	   zone to another.

	   If it is called with no arguments, the date is converted from the local time zone to
	   the time zone 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 time zone is converted from the time zone 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 time
	   zone 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 time zone.

	   If Date_ConvTZ is called with both $from and $to, the date is converted from the time
	   zone $from to $to.

	   NOTE: As in all other cases, the $date returned from Date_ConvTZ has no time zone
	   information included as part of it, so calling UnixDate with the "%z" format will
	   return the time zone that Date::Manip is working in (usually the local time zone).

	   Example:  To convert 2/2/96 noon PST to CST (regardless of what time zone you are in,
	   do the following:

	    $date = ParseDate("2/2/96 noon");
	    $date = Date_ConvTZ($date,"PST","CST");

	   Both time zones MUST be in one of the formats listed below in the section TIME ZONES.

	   If an error occurs, $errlev determines what happens:

	     0	 : the program dies
	     1	 : a warning is produced and nothing is returned
	     2	 : the function silently returns nothing

       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.

       Date_NextWorkDay
	     $date = Date_NextWorkDay($date,$off [,$flag]);

	   Finds the day $off work days from now.  If $flag is non-zero, we must also take into
	   account the time of day.

	   If $flag is zero, 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 $flag is non-zero, day 0 is now (if now is part of a workday) or the start of the
	   very next work day.

       Date_PrevWorkDay
	     $date = Date_PrevWorkDay($date,$off [,$flag]);

	   Similar to Date_NextWorkDay.

       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.

       DateManipVersion
	     $version = DateManipVersion;

	   Returns the version of Date::Manip.

TIME ZONES
       With the release of Date::Manip 6.00, time zones and daylight saving time are now fully
       supported in Date::Manip. 6.00 uses information from several standards (most importantly
       the Olson zoneinfo database) to get a list of all known time zones.

       Unfortunately, 6.00 requires a newer version of perl, so I will continue to support the
       5.xx release for a while. However, the way I will support time zones in 5.xx has changed.
       Previously, new time zones would be added on request. That is no longer the case. Time
       zones for 5.xx are now generated automatically from those available in 6.00.

       The following time zone 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 time zone abbreviations are also accepted. These do not come
       from a standard, but were included in previous releases of Date::Manip 5.xx and are
       preserved here for backward compatibility:

	  IDLW	  -1200    International Date Line West
	  NT	  -1100    Nome
	  SAT	  -0400    Chile
	  CLDT	  -0300    Chile Daylight
	  AT	  -0200    Azores
	  MEWT	  +0100    Middle European Winter
	  MEZ	  +0100    Middle European
	  FWT	  +0100    French Winter
	  GB	  +0100    GMT with daylight savings
	  SWT	  +0100    Swedish Winter
	  MESZ	  +0200    Middle European Summer
	  FST	  +0200    French Summer
	  METDST  +0200    An alias for MEST used by HP-UX
	  EETDST  +0300    An alias for eest used by HP-UX
	  EETEDT  +0300    Eastern Europe, USSR Zone 1
	  BT	  +0300    Baghdad, USSR Zone 2
	  IT	  +0330    Iran
	  ZP4	  +0400    USSR Zone 3
	  ZP5	  +0500    USSR Zone 4
	  IST	  +0530    Indian Standard
	  ZP6	  +0600    USSR Zone 5
	  AWST	  +0800    Australian Western Standard
	  ROK	  +0900    Republic of Korea
	  AEST	  +1000    Australian Eastern Standard
	  ACDT	  +1030    Australian Central Daylight
	  CADT	  +1030    Central Australian Daylight
	  AEDT	  +1100    Australian Eastern Daylight
	  EADT	  +1100    Eastern Australian Daylight
	  NZT	  +1200    New Zealand
	  IDLE	  +1200    International Date Line East

       All other time zone abbreviations come from the standards. In many cases, an abbreviation
       may be used for multiple time zones. For example, NST stands for Newfoundland Standard
       -0330 and North Sumatra +0630.  In these cases, only 1 of the two is available. I have
       tried to use the most recent definition, and of those (if multiple time zones use the
       abbreviation), the most commonly used. I don't claim that I'm correct in all cases, but
       I've done the best I could.

       The list of abbreviations available is documented in the Date::Manip::DM5abbrevs document.

       Date::Manip must be able to determine the time zone 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/time zone

       At least one of these should contain a time zone in one of the supported forms.	If none
       do by default, the TZ variable must be set with Date_Init.

       The time zone 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

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, its 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.

DATE::MANIP VARIABLES
       All Date::Manip variables which can be used are described in the following section.

       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.

       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).

       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.

       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).

       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 :-).

       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).

       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.

       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).

       TZ  If set, this defines the local time zone.  See the TIME ZONES section above for
	   information on its format.

       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 time zone.	This allows dates to easily be compared and manipulated as if
	   they are all in a single time zone.

	   The ConvTZ variable determines which time zone should be used to store dates in.  If
	   it is left blank, all dates are converted to the local time zone (see the TZ variable
	   above).  If it is set to one of the time zones listed above, all dates are converted
	   to this time zone.  Finally, if it is set to the string "IGNORE", all time zone
	   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).

       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).

       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.

       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.

       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.

       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.

       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).

       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).

       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.

       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, in 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.

       UpdateCurrTZ
	   If a script is running over a long period of time, the time zone may change during the
	   course of running it (i.e. when daylight saving 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 time zone every time a date is
	   parsed, by default checking is turned off.  Setting this to non-nil will force time
	   zone 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
	   time zone switch occurs.

       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 December to have the accent over
	   the first "e", you'll want to set this to 1.

       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.

       TodayIsMidnight
	   If set to a true value (e.g. 1), then "today" will mean the same as "midnight today";
	   otherwise it will mean the same as "now".

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*DWD		  = 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 dates 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.

       Note that the dates are specified in whatever format is set using the Date_Init options,
       so if the standard parsing is D/M/YYYY, you would need to specify it as:

	  25/12/2002	       = Christmas

       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 should 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 essence, 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");
	 ...

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:

       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.

       Events don't affect business mode calculations
	   Unlike holidays, events are completely ignored when doing business mode calculations.

       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 its duration.
       An EVENT can be defined in the following ways:

	  Date
	  Date*

	  Date	; Date
	  Date	; Delta

       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.  Similarly, 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).

KNOWN PROBLEMS
       The following are not bugs in Date::Manip, but they may give some people problems.

       Unable to determine Time Zone
	   Perhaps the most common problem occurs when you get the error:

	      Error: Date::Manip unable to determine Time Zone.

	   Date::Manip tries hard to determine the local time zone, 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 saving time.

	   Windows NT does not seem to set the time zone 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 time zone.   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 its tests at install time, this should not occur and are surprised when it
	   does.

	   Some of the tests are time zone dependent.  Since the tests all include input and
	   expected output, I needed to know in advance what time zone they would be run in.  So,
	   the tests all explicitly set the time zone using the TZ configuration variable passed
	   into Date_Init.  Since this overrides any other method of determining the time zone,
	   Date::Manip uses this and doesn't have to look elsewhere for the time zone.

	   When running outside the tests, Date::Manip has to rely on its other methods for
	   determining the time zone.

       Missing date formats
	   Please see the Date::Manip::Problems document for a discussion.

       Complaining about getpwnam/getpwuid
	   Another problem is when running on Micro$oft OS's.  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

       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).  Who
	   needs a business date more accurate than "6 to 8 weeks" anyway, right :-)

	   Never call Date_Init more than once.  Unless you're doing something very strange,
	   there should never be a reason to anyway.

       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 (but read the 2nd note below
	   for an easy way to correct this).  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.

	   NOTE: It has been reported to me that you can still use ParseDate to sort dates in
	   this way, and be quite efficient through the use of Memoize.  Just add the following
	   lines to your code:

	      use Date::Manip;
	      use Memoize;
	      memoize('ParseDate');
	      ...
	      @i=sort sortDate @dates;

	   Since sortDate would call ParseDate with the same data over and over, this is a
	   perfect application for the Memoize module.	So, sorting with ParseDate is no longer
	   slow for sorting.

       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.

KNOWN BUGS
       Daylight Saving Times
	   Date::Manip does not handle daylight saving time, though it does handle time zones 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
	   time zone).

		   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 time zone 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 time zone (EST in this case).

	   Related problems occur when trying to do date calculations over a time zone 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 Saving
	   Time to Standard Time or vice versa), many things may be wrong (especially elapsed
	   time).

	   These problems will not be fixed in Date::Manip 5.xx. Date::Manip 6.xx has full
	   support for time zones and daylight saving time.

BUGS AND QUESTIONS
       Please refer to the Date::Manip::Problems documentation for information on submitting bug
       reports or questions to the author.

SEE ALSO
       Date::Manip	  - main module documentation

LICENSE
       This script is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

AUTHOR
       Sullivan Beck (sbeck@cpan.org)

perl v5.16.3				    2014-06-09			      Date::Manip::DM5(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 12:54 AM.