Date::Manip(3) User Contributed Perl Documentation Date::Manip(3)NAMEDate::Manip - date manipulation routines
SYNOPSIS
use Date::Manip;
$version = DateManipVersion;
$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 [,$time]);
$date = Date_PrevWorkDay($date,$off [,$time]);
$date = Date_NearestWorkDay($date [,$tomorrowfirst]);
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 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();
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 may 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 similar to the attitude that caused the great Y2K problem...
but I have an excuse: I don't know what the correction will be, so I
can't possibly 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.
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. Time zones
are also supported to some extent.
NOTE: Much better support for time zones (including Daylight
Saving Time) is planned for the future.
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.
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.
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 does not exist, but may be added in the
future.
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.
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.
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.
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
dependencies to meet. Other modules have dependencies on a C compiler
or other Perl modules. Since it is fairly easy to satisfy these
dependencies 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.
It should be noted that using the Memoize module in conjunction with
Date::Manip can have a huge impact on its performance, depending on the
types of operations you do. Your mileage may vary though.
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 its 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.
ROUTINES
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 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.
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 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.
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
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.
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_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.
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 [,$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.
Date_PrevWorkDay
$date = Date_PrevWorkDay($date,$off [,$time]);
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
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.
In a few cases, the same abbreviation is used for two different time
zones (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
PET -0500 Peruvian Time
VET -0430 Venezuela
SAT -0400 Chile
CLT -0400 Chile Standard
CLST -0400 Chile Standard
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
CLDT -0300 Chile Daylight
#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
UYT -0300 Uruguay
NDT -0230 Newfoundland Daylight
ARST -0200 Argentina Daylight
AT -0200 Azores
BRST -0200 Brazil Daylight (official time)
FNT -0200 Brazil, Fernando de Noronha
UYST -0200 Uruguay
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 saving
WEST +0100 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
EETDST +0300 An alias for eest used by HP-UX
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
YEKT +0500 Yeakaterinburg time zone, Russia
YEKST +0500 Yeakaterinburg summer time zone, Russia
IST +0530 Indian Standard
ZP6 +0600 USSR Zone 5
NOVT +0600 Novosibirsk winter time zone, Russia
OMST +0600 Omsk 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
NOVST +0700 Novosibirsk summer time zone, Russia
ICT +0700 Indo China Time
KRAT +0700 Krasnoyarsk, Russia
MYT +0800 Malaysia
CCT +0800 China Coast, USSR Zone 7
KRAST +0800 Krasnoyarsk, Russia Daylight
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
CHST +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 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/timezone
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
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.
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*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 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*
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.
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).
Items marked with [NYI] are not yet implemented but will be by the time
this is released.
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.
VERSION 5.44
(*) Recurrences revisited
The behavior of some elements of recurrences changed. These
included making the week element (N) refer to the Nth
occurrence of a day of the week in the week, month, or year. It
is now possible to look at the 3rd Friday of every month for
example.
Changed %x format in UnixDate
The %x format used to be equivalent to %D (%m/%d/%y), but it
has been modified to use the DateFormat config variable, so it
may return %d/%m/%y if a non-US DateFormat is specified.
VERSION 5.41
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.
Delta_Format behavior changed
The entire delta is exact if no month component is present
(previously, no year or month component could be present).
VERSION 5.38
Removed Date_DaysSince999
The Date_DaysSince999 function (deprecated in 5.35) has been
removed.
VERSION 5.35
Deprecated 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.
(*) 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.
VERSION 5.34
(*) 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.
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.
%z UnixDate format
The %z UnixDate format used to return the time zone
abbreviation. It now returns it as a GMT offset (i.e. -0500).
%Z still returns the time zone abbreviation.
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.
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
(*) 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 time zone 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 time zone).
VERSION 5.32
Date_Init arguments
The old style Date_Init arguments that were deprecated in
version 5.07 have been removed.
(*) 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.
VERSION 5.30
(*) 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".
VERSION 5.21
Long running processes may give incorrect time zone
A process that runs during a time zone change (Daylight Saving
Time specifically) may report the wrong time zone. See the
UpdateCurrTZ variable for more information.
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.
VERSION 5.20
(*) 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.
(*) 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).
VERSION 5.07
UnixDate "%s" format
Used to return the number of seconds since 1/1/1970 in the
current time zone. It now returns the number of seconds since
1/1/1970 GMT. The "%o" format was added which returns what
"%s" previously did.
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.
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
.
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
Due to the number of date formats that Date::Manip CAN process,
people often get bitten when they put in a date format that they
expect to work and it doesn't.
If this happens, I'm willing to entertain the suggestion that they
be added. I'm a little less willing to add date formats at this
point due to the ever increasing complexity of the parsing
routines, but I always consider each request, and if the format
isn't too abstract, I often add them.
There is one exception to this rule though.
I have frequently been asked to add formats such as "the 15th of
last month", or "Monday of next week". I will NOT add these date
formats to Date::Manip. Since I have received the request several
times, I decided to include my reasoning here.
Date::Manip can parse pretty much any static date format that I
could think of or find reference to. Dates such as "today", "Jan
12", or "2001-01-01" are all well understood.
These are fairly limited however. Many very common date formats are
best thought of as a date plus a modification. For example,
"yesterday" is actually determined internally as "today" plus a
delta of "- 1 day". "2nd Sunday in June" is determined as "June 1"
modified to the 2nd Sunday.
As these types of formats were added over time, I quickly realized
that the number of possible date plus modification formats was
huge. The number of combinations has caused the parsing in
Date::Manip to be quite complex, and adding new formats
occasionally causes unexpected conflicts with other formats.
The first time I received a request similar to "the 15th of last
month", as I analyzed it to see about adding it to Date::Manip, I
realized that this needed to be expressed as a date plus TWO
modifications. In other words, today modified to last month modifed
to the 15th day of the month.
As bad as date plus modification formats are, date plus TWO
modifications would be exponentially worse. On realizing that, I
made a firm decision that Date::Manip will NOT support this type of
format now, or at any time in the future.
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
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).
I hope to fix these problems in a future release so that it would
convert everything to the current zones (EST or EDT).
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 manual and start reading. If this still doesn't
answer your question, mail me (again, please mail me rather than post
to the newsgroup).
YEAR 2000 AND YEAR 2007 DST CHANGE
Did Date::Manip have any problems with Y2K compliance? Did it have any
problems with the revised daylight savings time changes made in 2007?
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 Date::Manip had no problems with the Y2K issue. Of course,
applications written which stored the year as 2 digits (whether or not
it used Date::Manip) may have had problems, but they were not because
of this module.
Similarly for the 2007 changes in daylight savings time made in the
United States, Date::Manip was not affected. Date::Manip makes use of
the current timezone, but it gets that information from the operating
system the application is running on. If the operating system knows
about the new daylight saving time rules... so does Date::Manip.
WHAT DATES ARE DATE::MANIP USEFULE FOR?
As stated above, Date::Manip applies to the Gregorian calendar, and
stores the year as 4 digits.
Given the 4-digit limitation, Date::Manip definitely can't handle BC
dates, or dates past Dec 31, 9999. So Date::Manip works during the
years 0001 to 9999.
One caveat to this is that in one part of the code (calculating week-
of-year values), Date::Manip actually uses values one week after and
one week before the date being manipulated. As such, the first week in
the year 0001 fail (because a week before is in the year 1 BC), and the
last week in the year 9999 fail (because a week later is in 10,000). No
effort will be made to correct this because the added functionality is
simply not that important (to me), especially since the Gregorian
calendar doesn't really apply in either instance (see the next
paragraph). To be absolutely safe, I will state that Date::Manip works
as described in this manual during the years 0002 to 9998 (unless
you've encountered a bug, or are using the module incorrectly). If you
submit a "bug" using a date that is not in this range, I will not
attempt to fix it unless it also affects dates that are within the
years 0002 to 9998.
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, the Gregorian system may need to be modified slightly
(though since leap seconds exist, this may not need to happen for a
very long time). So... in practical terms, Date::Manip is probably
useful from around 1900 on, and should remain useful for the forseeable
future.
A caveat here is that Date::Manip does NOT make use of the leap seconds
in calculating time intervals, so the difference between two times may
not be strictly accurate due to the addition of a leap second.
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 3 digits long as
of the year 2000), these will NOT be parsable by Date::Manip. Please
note that the perl functions localtime and gmtime DO return the year as
an offset from 1900, so the output from these will need to be corrected
(probably by adding 1900 to the result) before they can be passed to
any Date::Manip routine.
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.
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.
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)
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/
perl v5.10.0 2008-05-07 Date::Manip(3)
