Manip(3) User Contributed Perl Documentation Manip(3)
NAME
Date::Manip - date manipulation routines
SYNOPSIS
use Date::Manip;
$date = ParseDate(\@args);
$date = ParseDate($string);
$date = ParseDate(\$string);
@date = UnixDate($date,@format);
$date = UnixDate($date,@format);
$delta = ParseDateDelta(\@args);
$delta = ParseDateDelta($string);
$delta = ParseDateDelta(\$string);
@str = Delta_Format($delta,$dec,@format);
$str = Delta_Format($delta,$dec,@format);
$recur = ParseRecur($string,$base,$date0,$date1,$flags);
@dates = ParseRecur($string,$base,$date0,$date1,$flags);
$flag = Date_Cmp($date1,$date2);
$d = DateCalc($d1,$d2 [,$errref] [,$del]);
$date = Date_SetTime($date,$hr,$min,$sec);
$date = Date_SetTime($date,$time);
$date = Date_SetDateField($date,$field,$val [,$nocheck]);
$date = Date_GetPrev($date,$dow,$today,$hr,$min,$sec);
$date = Date_GetPrev($date,$dow,$today,$time);
$date = Date_GetNext($date,$dow,$today,$hr,$min,$sec);
$date = Date_GetNext($date,$dow,$today,$time);
$version = DateManipVersion;
$flag = Date_IsWorkDay($date [,$flag]);
$date = Date_NextWorkDay($date,$off [,$time]);
$date = Date_PrevWorkDay($date,$off [,$time]);
$name = Date_IsHoliday($date);
$listref = Events_List($date);
$listref = Events_List($date0,$date1);
&Date_Init();
&Date_Init("VAR=VAL","VAR=VAL",...);
@list = Date_Init();
@list = Date_Init("VAR=VAL","VAR=VAL",...);
The above routines all check to make sure that Date_Init is called. If it hasn’t
been, they will call it automatically. As a result, there is usually no need to
call Date_Init explicitely unless you want to change some of the config variables
(described below).
The following routines are used by the above routines (though they can also be
called directly). $y may be entered as either a 2 or 4 digit year (it will be
converted to a 4 digit year based on the variable YYtoYYYY described below). Month
and day should be numeric in all cases. Most (if not all) of the information below
can be gotten from UnixDate which is really the way I intended it to be gotten, but
there are reasons to use these (these are significantly faster).
***NOTE*** Unlike the routines listed above, the following routines do NOT
explicitely call Date_Init. You must make sure that Date_Init has been called,
either by you explicitely, or by one of the above routines before you use these
routines.
$day = Date_DayOfWeek($m,$d,$y);
$secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
$secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
$days = Date_DaysSince1BC($m,$d,$y);
$day = Date_DayOfYear($m,$d,$y);
$days = Date_DaysInYear($y);
$wkno = Date_WeekOfYear($m,$d,$y,$first);
$flag = Date_LeapYear($y);
$day = Date_DaySuffix($d);
$tz = Date_TimeZone();
($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
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 ori-
ented 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 pre-
sented 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 cur-
rently 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; Ger-
many and Netherlands in 1698, British Empire in 1752, Russia in 1918. Note that
the Gregorian calendar is itself imperfect and at some point will need to be cor-
rected. No attempt is made to correct for that, and my great great great grand-
children will be long dead before this even occurs, so it’s not an immediate con-
cern. Yes, this is the same type of attitute that caused the great Y2K problem...
but I have an excuse: I don’t know what the correction will be, so I can’t possible
implement it. Nobody doubted that the year after 1999 would be known as 2000 :-).
Date::Manip is therefore not equipped to truly deal with historical dates, but
should be able to perform (virtually) any operation dealing with a modern time and
date.
Date::Manip has (or will have) functionality to work with several fundamental types
of data.
DATE
Although the word date is used extensively here, it is actually somewhat mis-
leading. Date::Manip works with the full date AND time (year, month, day,
hour, minute, second and weeks when appropriate). It doesn’t work with frac-
tional seconds. Timezones are also supported to some extent.
NOTE: Much better support for timezones (including Daylight Savings 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 identi-
cal at a granularity of days, then they only have to occur on the same day. At
a granularity of an hour, they have to occur within an hour of each other, etc.
NOTE: Support for this will be added in the future.
HOLIDAYS and EVENTS
These are basically a named time. Holidays are used in business mode calcula-
tions. 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 transla-
tion, 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 mod-
ules. It’s also the biggest and slowest.
Since Date::Manip is written entirely in perl, and depends on no other module not
in a standard perl distribution, Date::Manip has no dependancies to meet. Other
modules have dependancies on a C compiler or other perl modules. Since it is
fairly easy to satisfy these dependancies for anyone who is reasonably familiar
with perl modules, this is not a huge advantage that Date::Manip has.
On the other hand, simpler perl modules tend to be faster than Date::Manip, and
modules written in C are significantly faster than their perl counterparts (at
least if they’re done right). The TimeDate and Time-modules modules are written in
perl, but are much simpler (and hence, faster) than Date::Manip. The Date::Calc
module is written in C and is a good module for doing many date calculations much
faster than Date::Manip. Between these three, most of your common date operations
can be done.
Date::Manip is certainly the most powerful of the Date modules. To the best of my
knowledge, it will do everything that any other date module will do (not just the
ones I listed above), and there are a number of features that Date::Manip has that
none of the other modules have. Date::Manip is the "Swiss Army Knife" of Date mod-
ules. 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 mod-
ules there is. If you ignore modules like Tk, LWP, etc. which are actually pack-
ages of modules, it may be the largest. It’s true that Date::Manip will do almost
every date operation you could imagine... but you rarely need all that power. I’m
working on reducing the footprint of Date::Manip, but even at it’s slimmest, it’ll
outweigh the other modules by a good bit.
If you are going to be using the module in cases where performance is an important
factor (started up in a CGI program being run by your web server 5,000 times a sec-
ond), 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, find-
ing the difference between two dates, etc.), the other modules will almost cer-
tainly 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 inter-
preted 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 negligable amount).
NOTE: One of the most frequently asked questions that I have gotten is how to
parse seconds since the epoch. ParseDateString cannot simply parse a number as
the seconds since the epoch (it conflicts with some ISO-8601 date formats).
There are two ways to get this information. First, you can do the following:
$secs = ... # seconds since Jan 1, 1970 00:00:00 GMT
$date = &DateCalc("Jan 1, 1970 00:00:00 GMT",$secs);
Second, you can call it directly as:
$date = &ParseDateString("epoch $secs");
To go backwards, just use the "%s" format of UnixDate:
$secs = &UnixDate($date,"%s");
A full date actually includes 2 parts: date and time. A time must include
hours and minutes and can optionally include seconds, fractional seconds, an
am/pm type string, and a timezone. For example:
[at] HH:MN [Zone]
[at] HH:MN [am] [Zone]
[at] HH:MN:SS [am] [Zone]
[at] HH:MN:SS.SSSS [am] [Zone]
[at] HH am [Zone]
Hours can be written using 1 or 2 digits, but the single digit form may only be
used when no ambiguity is introduced (i.e. when it is not immediately preceded
by a digit).
A time is usually entered in 24 hour mode, but 12 hour mode can be used as well
if AM/PM are entered (AM can be entered as AM or A.M. or other variations
depending on the language).
Fractional seconds are also supported in parsing but the fractional part is
discarded (with NO rounding ocurring).
Timezones always appear immediately after the time. A number of different
forms are supported (see the section TIMEZONEs below).
Incidentally, the time is removed from the date before the date is parsed, so
the time may appear before or after the date, or between any two parts of the
date.
Valid date formats include the ISO 8601 formats:
YYYYMMDDHHMNSSF...
YYYYMMDDHHMNSS
YYYYMMDDHHMN
YYYYMMDDHH
YY-MMDDHHMNSSF...
YY-MMDDHHMNSS
YY-MMDDHHMN
YY-MMDDHH
YYYYMMDD
YYYYMM
YYYY
YY-MMDD
YY-MM
YY
YYYYwWWD ex. 1965-W02-2
YYwWWD
YYYYDOY ex. 1965-045
YYDOY
In the above list, YYYY and YY signify 4 or 2 digit years, MM, DD, HH, MN, SS
refer to two digit month, day, hour, minute, and second respectively. F...
refers to fractional seconds (any number of digits) which will be ignored. The
last 4 formats can be explained by example: 1965-w02-2 refers to Tuesday (day
2) of the 2nd week of 1965. 1965-045 refers to the 45th day of 1965.
In all cases, parts of the date may be separated by dashes "-". If this is
done, 1 or 2 digit forms of MM, DD, etc. may be used. All dashes are optional
except for those given in the table above (which MUST be included for that for-
mat to be correctly parsed). So 19980820, 1998-0820, 1998-08-20, 1998-8-20,
and 199808-20 are all equivalent, but that date may NOT be written as 980820
(it must be written as 98-0820).
NOTE: Even though not allowed in the standard, the timezone for an ISO-8601
date is flexible and may be any of the timezones understood by Date::Manip.
Additional date formats are available which may or may not be common including:
MM/DD **
MM/DD/YY **
MM/DD/YYYY **
mmmDD DDmmm mmmYYYY/DD mmmYYYY
mmmDD/YY DDmmmYY DD/YYmmm YYYYmmmDD YYYYmmm
mmmDDYYYY DDmmmYYYY DDYYYYmmm YYYY/DDmmm
Where mmm refers to the name of a month. All parts of the date can be sepa-
rated 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 sin-
gle digit forms of DD or MM are used. If separators are not used, the date
will either be unparsable or will get parsed incorrectly.
Miscellaneous other allowed formats are:
which dofw in mmm in YY "first sunday in june 1996 at 14:00" **
dofw week num YY "sunday week 22 1995" **
which dofw YY "22nd sunday at noon" **
dofw which week YY "sunday 22nd week in 1996" **
next/last dofw "next friday at noon"
next/last week/month "next month"
in num days/weeks/months "in 3 weeks at 12:00"
num days/weeks/months later "3 weeks later"
num days/weeks/months ago "3 weeks ago"
dofw in num week "Friday in 2 weeks"
in num weeks dofw "in 2 weeks on friday"
dofw num week ago "Friday 2 weeks ago"
num week ago dofw "2 weeks ago friday"
last day in mmm in YY "last day of October"
dofw "Friday" (Friday of current week)
Nth "12th", "1st" (day of current month)
epoch SECS seconds since the epoch (negative values
are supported)
** Note that the formats "sunday week 22" and "22nd sunday" give very different
bahaviors. "sunday week 22" returns the sunday of the 22nd week of the year
based on how week 1 is defined. ISO 8601 defines week one to contain Jan 4, so
"sunday week 1" might be the first or second sunday of the current year, or the
last sunday of the previous year. "22nd sunday" gives the actual 22nd time
sunday occurs in a given year, regardless of the definition of a week.
Note that certain words such as "in", "at", "of", etc. which commonly appear in
a date or time are ignored. Also, the year is always optional.
In addition, the following strings are recognized:
today (exactly now OR today at a given time if a time is specified)
now (synonym for today)
yesterday (exactly 24 hours ago unless a time is specified)
tomorrow (exactly 24 hours from now unless a time is specifed)
noon (12:00:00)
midnight (00:00:00) Other languages have similar (and in some cases addi-
tional) 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 cur-
rent 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 infor-
mation 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. Alter-
nate 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
%G year - 0001 to 9999 (see below)
%L year - 0001 to 9999 (see below)
Month, Week
%m month of year - 01 to 12
%f month of year - " 1" to "12"
%b,%h month abbreviation - Jan to Dec
%B month name - January to December
%U week of year, Sunday
as first day of week - 01 to 53
%W week of year, Monday
as first day of week - 01 to 53
Day
%j day of the year - 001 to 366
%d day of month - 01 to 31
%e day of month - " 1" to "31"
%v weekday abbreviation - " S"," M"," T"," W","Th"," F","Sa"
%a weekday abbreviation - Sun to Sat
%A weekday name - Sunday to Saturday
%w day of week - 1 (Monday) to 7 (Sunday)
%E day of month with suffix - 1st, 2nd, 3rd...
Hour
%H hour - 00 to 23
%k hour - " 0" to "23"
%i hour - " 1" to "12"
%I hour - 01 to 12
%p AM or PM
Minute, Second, Timezone
%M minute - 00 to 59
%S second - 00 to 59
%s seconds from 1/1/1970 GMT- negative if before 1/1/1970
%o seconds from Jan 1, 1970
in the current time zone
%Z timezone - "EDT"
%z timezone as GMT offset - "+0100"
Date, Time
%c %a %b %e %H:%M:%S %Y - Fri Apr 28 17:23:15 1995
%C,%u %a %b %e %H:%M:%S %z %Y - Fri Apr 28 17:25:57 EDT 1995
%g %a, %d %b %Y %H:%M:%S %z - Fri, 28 Apr 1995 17:23:15 EDT
%D,%x %m/%d/%y - 04/28/95
%l date in ls(1) format
%b %e $H:$M - Apr 28 17:23 (if within 6 months)
%b %e %Y - Apr 28 1993 (otherwise)
%r %I:%M:%S %p - 05:39:55 PM
%R %H:%M - 17:40
%T,%X %H:%M:%S - 17:40:58
%V %m%d%H%M%y - 0428174095
%Q %Y%m%d - 19961025
%q %Y%m%d%H%M%S - 19961025174058
%P %Y%m%d%H%M%S - 1996102517:40:58
%F %A, %B %e, %Y - Sunday, January 1, 1996
%J %G-W%W-%w - 1997-W02-2
%K %Y-%j - 1997-045
Other formats
%n insert a newline character
%t insert a tab character
%% insert a ‘%’ character
%+ insert a ‘+’ character
The following formats are currently unused but may be used in the future:
NO 1234567890 !@#$^&*()_│-=\‘[];’,./~{}:<>?
They currently insert the character following the %, but may (and probably
will) change in the future as new formats are added.
If a lone percent is the final character in a format, it is ignored.
Note that the ls format (%l) applies to date within the past OR future 6
months!
The %U, %W, %L, and %G formats are used to support the ISO-8601 format:
YYYY-wWW-D. In this format, a date is written as a year, the week of the year,
and the day of the week. Technically, the week may be considered to start on
any day of the week, but Sunday and Monday are the two most common choices, so
both are supported.
The %U and %W formats return a week-of-year number from 01 to 53, and %L and %G
return a 4-digit year corresponding to the week. Most of the time, the %L and
%G formats returns the same value as the %Y format, but there is a problem with
days occuring in the first or last week of the year.
The ISO-8601 representation of Jan 1, 1993 written in the YYYY-wWWW-D format is
actually 1992-W53-5. In other words, Jan 1 is treates as being in the last
week of the preceding year. Depending on the year, days in the first week of a
year may belong to the previous year, and days in the final week of a year may
belong to the next year.
The %L and %U formats contains the year and week-of-year values treating weeks
as starting on Sunday. The %G and %W formats are the year and week-of-year
values treating weeks as starting on Monday.
%J returns the full ISO-8601 format (%G-W%W-%w).
The formats used in this routine were originally based on date.pl (version 3.2)
by Terry McGonigal, as well as a couple taken from different versions of the
Solaris date(1) command. Also, several have been added which are unique to
Date::Manip.
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 ele-
ment). 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 pre-
viously 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 equiv-
alent). 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 con-
figuration 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,$dec,@format);
$str = Delta_Format($delta,$dec,@format);
This is similar to the UnixDate routine except that it extracts information
from a delta. Unlike the UnixDate routine, most of the formats are 2 charac-
ters instead of 1.
Formats currently understood are:
%Xv : the value of the field named X
%Xd : the value of the field X, and all smaller fields, expressed in
units of X
%Xh : the value of field X, and all larger fields, expressed in units
of X
%Xt : the value of all fields expressed in units of X
X is one of y,M,w,d,h,m,s (case sensitive).
%% : returns a "%"
NOTE: Delta_Format only understands "exact" relationships, so for any delta
that has a month component, there can be no mixing of the Y/M and W/D/H/MN/S
segments. In other words, the delta 1:6:1:1:1:1:1 has a month component, so
asking for the total number of years (using the %yd format) will return 1.5
(which is what 1 year 6 months is). For deltas which have NO month component,
the relationship between years and days is known (365.25 is used) and all for-
mats work as expected (except that formats with X equal to "M" are not
allowed).
So, the format "%hd" means the values of H, MN, and S expressed in hours. So
for the delta "0:0:0:0:2:30:0", this format returns 2.5. Similarly, the format
"%yd" means the value (in years) of both the Y and M fields, or, if the month
component is 0, it uses Y, W, D, H, MN, S.
The format "%hh" returns the value of W, D, and H expressed in hours if the
month component is non-zero, or Y, W, D, H if the month component is 0.
If $dec is non-zero, the %Xd and %Xt values are formatted to contain $dec deci-
mal places.
ParseRecur
$recur = ParseRecur($string [,$base,$date0,$date1,$flags]);
@dates = ParseRecur($string [,$base,$date0,$date1,$flags]);
A recurrence refers to a recurring event. A fully specified recurrence
requires (in most cases) 4 items: a recur description (describing the frequency
of the event), a base date (a date when the event occurred and which other
occurrences are based on), and a start and end date. There may be one or more
flags included which modify the behavior of the recur description. The fully
specified recurrence is written as:
recur*flags*base*date0*date1
Here, base, date0, and date1 are any strings (which must not contain any aster-
ixes) which can be parsed by ParseDate. flags is a comma separated list of
flags (described below), and recur is a string describing a recurring event.
If called in scalar context, it returns a string containing a fully specified
recurrence (or as much of it as can be determined with unspecified fields left
blank). In list context, it returns a list of all dates referred to by a
recurrence if enough information is given in the recurrence. All dates
returned are in the range:
date0 <= date < date1
The argument $string can contain any of the parts of a full recurrence. For
example:
recur
recur*flags
recur**base*date0*date1
The only part which is required is the recur description. Any values contained
in $string are overridden or modified by values passed in as parameters to
ParseRecur.
A recur description is a string of the format Y:M:W:D:H:MN:S . Exactly one of
the colons may optionally be replaced by an asterisk, or an asterisk may be
prepended to the string.
Any value "N" to the left of the asterisk refers to the "Nth" one. Any value
to the right of the asterisk refers to a value as it appears on a calen-
dar/clock. Values to the right can be listed a single values, ranges (2 num-
bers separated by a dash "-"), or a comma separated list of values or ranges.
In a few cases, negative values are appropriate.
This is best illustrated by example.
0:0:2:1:0:0:0 every 2 weeks and 1 day
0:0:0:0:5:30:0 every 5 hours and 30 minutes
0:0:0:2*12:30:0 every 2 days at 12:30 (each day)
3*1:0:2:12:0:0 every 3 years on Jan 2 at noon
0:1*0:2:12,14:0:0 2nd of every month at 12:00 and 14:00
1:0:0*45:0:0:0 45th day of every year
0:1*4:2:0:0:0 4th tuesday (day 2) of every month
0:1*-1:2:0:0:0 last tuesday of every month
0:1:0*-2:0:0:0 2nd to last day of every month
0:0:3*2:0:0:0 every 3rd tuesday (every 3 weeks on 2nd day of week)
1:0*12:2:0:0:0 tuesday of the 12th week of each year
*1990-1995:12:0:1:0:0:0
Dec 1 in 1990 through 1995
0:1*2:0:0:0:0 the start of the 2nd week of every month (see Note 2)
1*1:2:0:0:0:0 the start of the 2nd week in January each year (Note 2)
I realize that this looks a bit cryptic, but after a discussion on the CALENDAR
mailing list, it looked like there was no concise, flexible notation for han-
dling recurring events. ISO 8601 notations were very bulky and lacked the
flexibility I wanted. As a result, I developed this notation (based on crontab
formats, but with much more flexibility) which fits in well with this module,
and which is able to express every type of recurring event I could think of.
NOTE: If a recurrence has a date0 and date1 in it AND a date0 and date1 are
passed in to the function, both sets of criteria apply. If flags are passed
in, they override any flags in the recurrence UNLESS the flags passed in start
with a plus (+) character in which case they are appended to the flags in the
recurrence.
NOTE: There is no way to express the following with a single recurrence:
every day at 12:30 and 1:00
You have to use two recurrences to do this.
NOTE: A recurrence specifying the week of a month is NOT clearly defined in
common usage. What is the 1st week in a month? The behavior (with respect to
this module) is well defined (using the FDn and FIn flags below), but in common
usage, this is so ambiguous that this form should probably never be used. It
is included here solely for the sake of completeness.
NOTE: Depending on whether M and W are 0 or nonzero, D means different things.
This is given in the following table.
M W D (when right of an asterisk) refers to
- - -------------------------------------------
0 0 day of year (1-366)
M 0 day of month (1-31)
0 W day of week (1-7), W refers to the week of year
M W the Wth (1-5 or -1 to -5) occurrence of Dth (1-7) day of week in month
NOTE: Base dates are only used with some types of recurrences. For example,
0:0:3*2:0:0:0 every 3rd tuesday
requires a base date. If a base date is specified which doesn’t match the cri-
teria (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 neces-
sary 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 miss-
ing).
The following flags (case insensitive) are understood:
MWn : n is 1-7. The first week of the month is the week
which contains the first occurrence of day n (1=Monday).
MW2 means that the first week contains the first Tuesday
of the month.
MDn : n is 1-7. The first week of the month contains the
actual date (1st through 7th). MD4 means that the first
week of the month contains the 4th of that month.
PDn : n is 1-7. Means the previous day n not counting today
PTn : n is 1-7. Means the previous day n counting today
NDn : n is 1-7. Means the next day n not counting today
NTn : n is 1-7. Means the next day n counting today
FDn : n is any number. Means step forward n days.
BDn : n is any number. Means step backward n days.
FWn : n is any number. Means step forward n workdays.
BWn : n is any number. Means step backward n workdays.
CWD : the closest work day (using the TomorrowFirst config variable).
CWN : the closest work day (looking forward first).
CWP : the closest work day (looking backward first).
NWD : next work day counting today
PWD : previous work day counting today
DWD : next/previous work day (TomorrowFirst config) counting today
EASTER: select easter for this year (the M, W, D fields are ignored
in the recur).
NOTE: only one of MWn and MDn can be set. If both are set, only the last one
is used. The default is MW7 (i.e. the first week contains the first Sunday).
CWD, CWN, and CWP will usually return the same value, but if you are starting
at the middle day of a 3-day weekend (for example), it will return either the
first work day of the following week, or the last work day of the previous week
depending on whether it looks forward or backward first.
All flags are applied AFTER the recurrence dates are calculated, and they may
move a date outside of the date0 to date1 range. No check is made for this.
The workday flags do not act exactly the same as a business mode calculation.
For example, a date that is Saturday with a FW1 steps forward to the first
workday (i.e. Monday).
Date_Cmp
$flag = Date_Cmp($date1,$date2);
This takes two dates and compares them. Almost all dates can be compared using
the perl "cmp" command. The only time this will not work is when comparing
dates in different timezones. This routine will take that into account.
NOTE: This routine currently does little more than use "cmp", but once the
internal format for storing dates is in place (where timezone information is
kept as part of the date), this routine will become more important. You should
use this routine in prepartation for that version.
DateCalc
$d = DateCalc($d1,$d2 [,\$err] [,$mode]);
This takes two dates, deltas, or one of each and performs the appropriate cal-
culation with them. Dates must be a string that can be parsed by &ParseDat-
eString. Deltas must be a string that can be parsed by &ParseDateDelta. Two
deltas add together to form a third delta. A date and a delta returns a 2nd
date. Two dates return a delta (the difference between the two dates).
Note that in many cases, it is somewhat ambiguous what the delta actually
refers to. Although it is ALWAYS known how many months in a year, hours in a
day, etc., it is NOT known how many days form a month. As a result, the part
of the delta containing month/year and the part with sec/min/hr/day must be
treated separately. For example, "Mar 31, 12:00:00" plus a delta of 1month
2days would yield "May 2 12:00:00". The year/month is first handled while
keeping the same date. Mar 31 plus one month is Apr 31 (but since Apr only has
30 days, it becomes Apr 30). Apr 30 + 2 days is May 2. As a result, in the
case where two dates are entered, the resulting delta can take on two different
forms. By default ($mode=0), an absolutely correct delta (ignoring daylight
savings time) is returned in days, hours, minutes, and seconds.
If $mode is 1, the math is done using an approximate mode where a delta is
returned using years and months as well. The year and month part is calculated
first followed by the rest. For example, the two dates "Mar 12 1995" and "Apr
13 1995" would have an exact delta of "31 days" but in the approximate mode, it
would be returned as "1 month 1 day". Also, "Mar 31" and "Apr 30" would have
deltas of "30 days" or "1 month" (since Apr 31 doesn’t exist, it drops down to
Apr 30). Approximate mode is a more human way of looking at things (you’d say
1 month and 2 days more often then 33 days), but it is less meaningful in terms
of absolute time. In approximate mode $d1 and $d2 must be dates. If either or
both is a delta, the calculation is done in exact mode.
If $mode is 2, a business mode is used. That is, the calculation is done using
business days, ignoring holidays, weekends, etc. In order to correctly use
this mode, a config file must exist which contains the section defining holi-
days (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 (pro-
vided Wed is not a holiday). Also, a date that is not during a workday auto-
matically 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 Tues-
day to Tuesday, regardless of holidays). Because this means that the relation-
ship 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 busi-
ness 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. Like-
wise, 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 Date-
Calc. 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 it’s fields to a new value. $field is any of
the strings "y", "m", "d", "h", "mn", "s" (case insensitive) and $val is the
new value.
If $nocheck is non-zero, no check is made as to the validity of the date.
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 follow-
ing 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 evalu-
ates to 0, the range of times will be the 24 hour period from midnight to mid-
night 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 ear-
lier).
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_SecsS-
ince1970 (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 float-
ing 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 func-
tion 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 AT idiom.com>
Date_DaySuffix
$day = Date_DaySuffix($d);
Add ‘st’, ‘nd’, ‘rd’, ‘th’ to a date (ie 1st, 22nd, 29th). Works for interna-
tional dates.
Date_TimeZone
$tz = Date_TimeZone;
This determines and returns the local timezone. If it is unable to determine
the local timezone, the following error occurs:
ERROR: Date::Manip unable to determine TimeZone.
See The TIMEZONES section below for more information.
Date_ConvTZ
$date = Date_ConvTZ($date);
$date = Date_ConvTZ($date,$from);
$date = Date_ConvTZ($date,"",$to);
$date = Date_ConvTZ($date,$from,$to);
This converts a date (which MUST be in the format returned by ParseDate) from
one timezone to another.
If it is called with no arguments, the date is converted from the local time-
zone to the timezone specified by the config variable ConvTZ (see documentation
on ConvTZ below). If ConvTZ is set to "IGNORE", no conversion is done.
If called with $from but no $to, the timezone is converted from the timezone in
$from to ConvTZ (of TZ if ConvTZ is not set). Again, no conversion is done if
ConvTZ is set to "IGNORE".
If called with $to but no $from, $from defaults to ConvTZ (if set) or the local
timezone otherwise. Although this does not seem immediately obvious, it actu-
ally makes sense. By default, all dates that are parsed are converted to Con-
vTZ, so most of the dates being worked with will be stored in that timezone.
If Date_ConvTZ is called with both $from and $to, the date is converted from
the timezone $from to $to.
NOTE: As in all other cases, the $date returned from Date_ConvTZ has no time-
zone information included as part of it, so calling UnixDate with the "%z" for-
mat will return the timezone that Date::Manip is working in (usually the local
timezone).
Example: To convert 2/2/96 noon PST to CST (regardless of what timezone you
are in, do the following:
$date = ParseDate("2/2/96 noon");
$date = Date_ConvTZ($date,"PST","CST");
Both timezones MUST be in one of the formats listed below in the section TIME-
ZONES.
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 "EraseHol-
idays=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 holi-
day, Thursday is returned if $tomorrowfirst is non-nil or Tuesday otherwise.
DateManipVersion
$version = DateManipVersion;
Returns the version of Date::Manip.
TIMEZONES
The following timezone names are currently understood (and can be used in parsing
dates). These are zones defined in RFC 822.
Universal: GMT, UT
US zones : EST, EDT, CST, CDT, MST, MDT, PST, PDT
Military : A to Z (except J)
Other : +HHMM or -HHMM
ISO 8601 : +HH:MM, +HH, -HH:MM, -HH
In addition, the following timezone abbreviations are also accepted. In a few
cases, the same abbreviation is used for two different timezones (for example, NST
stands for Newfoundland Standard -0330 and North Sumatra +0630). In these cases,
only 1 of the two is available. The one preceded by a "#" sign is NOT available
but is documented here for completeness. This list of zones comes in part from the
Time::Zone module by Graham Barr, David Muir Sharnoff, and Paul Foley (with several
additions by myself).
IDLW -1200 International Date Line West
NT -1100 Nome
HST -1000 Hawaii Standard
CAT -1000 Central Alaska
AHST -1000 Alaska-Hawaii Standard
AKST -0900 Alaska Standard
YST -0900 Yukon Standard
HDT -0900 Hawaii Daylight
AKDT -0800 Alaska Daylight
YDT -0800 Yukon Daylight
PST -0800 Pacific Standard
PDT -0700 Pacific Daylight
MST -0700 Mountain Standard
MDT -0600 Mountain Daylight
CST -0600 Central Standard
CDT -0500 Central Daylight
EST -0500 Eastern Standard
ACT -0500 Brazil, Acre
SAT -0400 Chile
BOT -0400 Bolivia
EDT -0400 Eastern Daylight
AST -0400 Atlantic Standard
AMT -0400 Brazil, Amazon
ACST -0400 Brazil, Acre Daylight
#NST -0330 Newfoundland Standard nst=North Sumatra +0630
NFT -0330 Newfoundland
#GST -0300 Greenland Standard gst=Guam Standard +1000
#BST -0300 Brazil Standard bst=British Summer +0100
BRST -0300 Brazil Standard
BRT -0300 Brazil Standard
AMST -0300 Brazil, Amazon Daylight
ADT -0300 Atlantic Daylight
ART -0300 Argentina
NDT -0230 Newfoundland Daylight
AT -0200 Azores
BRST -0200 Brazil Daylight (official time)
FNT -0200 Brazil, Fernando de Noronha
WAT -0100 West Africa
FNST -0100 Brazil, Fernando de Noronha Daylight
GMT +0000 Greenwich Mean
UT +0000 Universal (Coordinated)
UTC +0000 Universal (Coordinated)
WET +0000 Western European
CET +0100 Central European
FWT +0100 French Winter
MET +0100 Middle European
MEZ +0100 Middle European
MEWT +0100 Middle European Winter
SWT +0100 Swedish Winter
BST +0100 British Summer bst=Brazil standard -0300
GB +0100 GMT with daylight savings
WEST +0000 Western European Daylight
CEST +0200 Central European Summer
EET +0200 Eastern Europe, USSR Zone 1
FST +0200 French Summer
MEST +0200 Middle European Summer
MESZ +0200 Middle European Summer
METDST +0200 An alias for MEST used by HP-UX
SAST +0200 South African Standard
SST +0200 Swedish Summer sst=South Sumatra +0700
EEST +0300 Eastern Europe Summer
BT +0300 Baghdad, USSR Zone 2
MSK +0300 Moscow
EAT +0300 East Africa
IT +0330 Iran
ZP4 +0400 USSR Zone 3
MSD +0300 Moscow Daylight
ZP5 +0500 USSR Zone 4
IST +0530 Indian Standard
ZP6 +0600 USSR Zone 5
NOVST +0600 Novosibirsk time zone, Russia
NST +0630 North Sumatra nst=Newfoundland Std -0330
#SST +0700 South Sumatra, USSR Zone 6 sst=Swedish Summer +0200
JAVT +0700 Java
CCT +0800 China Coast, USSR Zone 7
AWST +0800 Australian Western Standard
WST +0800 West Australian Standard
PHT +0800 Asia Manila
JST +0900 Japan Standard, USSR Zone 8
ROK +0900 Republic of Korea
ACST +0930 Australian Central Standard
CAST +0930 Central Australian Standard
AEST +1000 Australian Eastern Standard
EAST +1000 Eastern Australian Standard
GST +1000 Guam Standard, USSR Zone 9 gst=Greenland Std -0300
ACDT +1030 Australian Central Daylight
CADT +1030 Central Australian Daylight
AEDT +1100 Australian Eastern Daylight
EADT +1100 Eastern Australian Daylight
IDLE +1200 International Date Line East
NZST +1200 New Zealand Standard
NZT +1200 New Zealand
NZDT +1300 New Zealand Daylight
Others can be added in the future upon request.
Date::Manip must be able to determine the timezone the user is in. It does this by
looking in the following places:
$Date::Manip::TZ (set with Date_Init or in Manip.pm)
$ENV{TZ}
the unix ‘date‘ command (if available)
$main::TZ
/etc/TIMEZONE
/etc/timezone
At least one of these should contain a timezone in one of the supported forms. If
none do by default, the TZ variable must be set with Date_Init.
The timezone may be in the STD#DST format (in which case both abbreviations must be
in the table above) or any of the formats described above. The STD#DST format is
NOT available when parsing a date however. The following forms are also available
and are treated similar to the STD#DST forms:
US/Pacific
US/Mountain
US/Central
US/Eastern
Canada/Pacific
Canada/Mountain
Canada/Central
Canada/Eastern
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, simi-
lar 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 justi-
fied. 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 con-
fusing, 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 customiza-
tion variables. These provide the default values.
These can be overridden in a global config file if one is present (this file is
optional). If the GlobalCnf variable is set in the Manip.pm file, it contains the
full path to a config file. If the file exists, it’s values will override those
set in the Manip.pm file. A sample config file is included with the Date::Manip
distribution. Modify it as appropriate and copy it to some appropriate directory
and set the GlobalCnf variable in the Manip.pm file.
Each user can have a personal config file which is of the same form as the global
config file. The variables PersonalCnf and PersonalCnfPath set the name and search
path for the personal config file. This file is also optional. If present, it
overrides any values set in the global file.
NOTE: if you use business mode calculations, you must have a config file (either
global or personal) since this is the only place where you can define holidays.
Finally, any variables passed in through Date_Init override all other values.
A config file can be composed of several sections. The first section sets configu-
ration 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 insensi-
tive.
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 argu-
ment (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 (cur-
rently 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 (cur-
rently 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 timezone. See the TIMEZONES section above for
information on it’s 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 con-
verted to a specific timezone. This allows dates to easily be compared and
manipulated as if they are all in a single timezone.
The ConvTZ variable determines which timezone should be used to store dates in.
If it is left blank, all dates are converted to the local timezone (see the TZ
variable above). If it is set to one of the timezones listed above, all dates
are converted to this timezone. Finally, if it is set to the string "IGNORE",
all timezone information is ignored as the dates are read in (in this case, the
two dates "1/1/96 12:00 GMT" and "1/1/96 12:00 EST" would be treated as identi-
cal).
Internal
When a date is parsed using ParseDate, that date is stored in an internal for-
mat 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 intro-
duced. 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 Sun-
day (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 WorkDay-
Beg and WorkDayEnd variables are ignored in this case.
WorkDayBeg, WorkDayEnd
The times when the work day starts and ends. WorkDayBeg must come before Work-
DayEnd (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 for-
mats), but seconds will be ignored.
TomorrowFirst
Periodically, if a day is not a business day, we need to find the nearest busi-
ness day to it. By default, we’ll look to "tomorrow" first, but if this vari-
able 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 func-
tion).
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 ele-
ments (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 belong-
ing 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, no (1998), "C" forces 2 digit
years to be 1900-1999 and "C18" would force it to be 1800-1899.
It can also be set to the form "C####" to force it into a specific 100 year
period. C1950 refers to 1950-2049.
UpdateCurrTZ
If a script is running over a long period of time, the timezone may change dur-
ing the course of running it (i.e. when daylight savings time starts or ends).
As a result, parsing dates may start putting them in the wrong time zone.
Since a lot of overhead can be saved if we don’t have to check the current
timezone every time a date is parsed, by default checking is turned off. Set-
ting this to non-nil will force timezone checking to be done every time a date
is parsed... but this will result in a considerable performance penalty.
A better solution would be to restart the process on the two days per year
where the timezone switch occurs.
IntCharSet
If set to 0, use the US character set (7-bit ASCII) to return strings such as
the month name. If set to 1, use the appropriate international character set.
For example, If you want your French representation of Decemeber to have the
accent over the first "e", you’ll want to set this to 1.
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.
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 Christ-
mas 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 (sepa-
rated by spaces) it can be correctly interpreted. This will work for everything
except ISO 8601 dates, so ISO 8601 dates may not be used in this case.
In cases where you are interested in business type calculations, you’ll want to
define most holidays using recurrences, since they can define when a holiday is
celebrated in the financial world. For example, Christmas chould be defined as:
1*12:0:24:0:0:0*FW1 = Christmas
NOTE: It was pointed out to me that using a similar type recurrence to define New
Years does not work. The recurrence:
1*12:0:31:0:0:0*FW1
fails (worse, it goes into an infinite loop). The problem is that each holiday
definition is applied to a specific year and it expects to find the holiday for
that year. When this recurrence is applied to the year 1995, it returns the holi-
day for 1996 and fails.
Use the recurrence:
1*1:0:1:0:0:0*NWD
instead.
If you wanted to define both Christmas and Boxing days (Boxing is the day after
Christmas, and is celebrated in some parts of the world), you could do it in one of
the following ways:
1*12:0:24:0:0:0*FW1 = Christmas
1*12:0:25:0:0:0*FW1 = Boxing
1*12:0:24:0:0:0*FW1 = Christmas
01*12:0:24:0:0:0*FW1 = Boxing
1*12:0:24:0:0:0*FW1 = Christmas
1*12:0:25:0:0:0*FW1,a = Boxing
The following examples will NOT work:
1*12:0:24:0:0:0*FW1 = Christmas
1*12:0:24:0:0:0*FW2 = Boxing
1*12:0:24:0:0:0*FW1 = Christmas
1*12:0:24:0:0:0*FW1 = Boxing
The reasoning behind all this is as follows:
Holidays go into affect the minute they are parsed. So, in the case of:
1*12:0:24:0:0:0*FW1 = Christmas
1*12:0:24:0:0:0*FW2 = Boxing
the minute the first line is parsed, Christmas is defined as a holiday. The second
line then steps forward 2 work days (skipping Christmas since that’s no longer a
work day) and define the work day two days after Christmas, NOT the day after
Christmas.
An good alternative would appear to be:
1*12:0:24:0:0:0*FW1 = Christmas
1*12:0:24:0:0:0*FW1 = Boxing
This unfortunately fails because the recurrences are currently stored in a hash.
Since these two recurrences are identical, they fail (the first one is overwritten
by the second and in essense, Christmas is never defined).
To fix this, make them unique with either a fake flag (which is ignored):
1*12:0:24:0:0:0*FW1,a = Boxing
or adding an innocuous 0 somewhere:
01*12:0:24:0:0:0*FW1 = Boxing
The other good alternative would be to make two completely different recurrences
such as:
1*12:0:24:0:0:0*FW1 = Christmas
1*12:0:25:0:0:0*FW1 = Boxing
At times, you may want to switch back and forth between two holiday files. This
can be done by calling the following:
&Date_Init("EraseHolidays=1","PersonalCnf=FILE1");
...
&Date_Init("EraseHolidays=1","PersonalCnf=FILE2");
...
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 calcu-
lations.
Whereas holidays were added with business mode math in mind, events were added with
calendar and scheduling applications in mind.
Every line in the events section is of the form:
EVENT = NAME
where NAME is the name of the event, and EVENT defines when it occurs and it’s
duration. An EVENT can be defined in the following ways:
Date
Date*
Recur [NYI]
Recur* [NYI]
Date ; Date
Date ; Delta
Recur ; Delta [NYI]
Date ; Delta ; Delta [NYI]
Recur ; Delta ; Delta [NYI]
Here, Date* refers to a string containing a Date with NO TIME fields (Jan 12,
1/1/2000, 2010-01-01) while Date does contain time fields. Similarily, Recur*
stands for a recurrence with the time fields all equal to 0) while Recur stands for
a recurrence with at least one non-zero time field.
Both Date* and Recur* refer to an event very similar to a holiday which goes from
midnight to midnight.
Date and Recur refer to events which occur at the time given and with a duration of
1 hour.
Events given by "Date ; Date", "Date ; Delta", and "Recur ; Delta" contain both the
starting date and either ending date or duration.
Events given as three elements "Date ; Delta ; Delta" or "Recur ; Delta ; Delta"
take a date and add both deltas to it to give the starting and ending time of the
event. The order and sign of the deltas is unimportant (and both can be the same
sign to give a range of times which does not contain the base date).
Items marked with [NYI] are not yet implemented but will be by the time this is
released.
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.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
Deprected Date_DaysSince999
In fixing support for the years 0000-0999, I rewrote Date_DaysSince999 to
be Date_DaysSince1BC. The Date_DaysSince999 function will be removed.
* 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 Timezone abbreviation. It now
returns it as a GMT offset (i.e. -0500). %Z still returns the Timezone
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 timezone information.
All date comparisons should be made using Date_Cmp (which currently does
nothing more than call the perl "cmp" command, but which will important
when comparing dates that include the timezone).
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 timezone
A process that runs during a timezone change (Daylight Saving Time specifi-
cally) may report the wrong timezone. 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 YYM-
MDD (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 con-
verting 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 ParseDat-
eDelta), 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 TimeZone
Perhaps the most common problem occurs when you get the error:
Error: Date::Manip unable to determine TimeZone.
Date::Manip tries hard to determine the local timezone, but on some machines,
it cannot do this (especially non-unix systems). To fix this, just set the TZ
variable, either at the top of the Manip.pm file,, in the DateManip.cnf file,
or in a call to Date_Init. I suggest using the form "EST5EDT" so you don’t
have to change it every 6 months when going to or from daylight savings time.
Windows NT does not seem to set the TimeZone by default. From the
Perl-Win32-Users mailing list:
> How do I get the TimeZone on my NT?
>
> $time_zone = $ENV{’TZ’};
>
You have to set the variable before, WinNT doesn’t set it by
default. Open the properties of "My Computer" and set a SYSTEM
variable TZ to your timezone. Jenda AT Krynicky.cz
This might help out some NT users.
A minor (false) assumption that some users might make is that since Date::Manip
passed all of it’s tests at install time, this should not occur and are sur-
prised when it does.
Some of the tests are timezone dependent. Since the tests all include input
and expected output, I needed to know in advance what timezone they would be
run in. So, the tests all explicitly set the timezone using the TZ configura-
tion variable passed into Date_Init. Since this overrides any other method of
determining the timezone, Date::Manip uses this and doesn’t have to look else-
where for the timezone.
When running outside the tests, Date::Manip has to rely on it’s other methods
for determining the timezone.
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 alterna-
tives if possible (i.e. doing the calculation in exact mode and then multiply-
ing by 5/7). There will be an approximate business mode in one of the next
versions which will be much faster (though less accurate) which will do some-
thing like this. Whenever possible, use this mode. And who needs a business
date more accurate than "6 to 8 weeks" anyway huh :-)
Never call Date_Init more than once. Unless you’re doing something very
strange, there should never be a reason to anyway.
Sorting Problems
If you use Date::Manip to sort a number of dates, you must call Date_Init
either explicitly, or by way of some other Date::Manip routine before it is
used in the sort. For example, the following code fails:
use Date::Manip;
# &Date_Init;
sub sortDate {
my($date1, $date2);
$date1 = &ParseDate($a);
$date2 = &ParseDate($b);
return (&Date_Cmp($date1,$date2));
}
@dates = ("Fri 16 Aug 96",
"Mon 19 Aug 96",
"Thu 15 Aug 96");
@i=sort sortDate @dates;
but if you uncomment the Date_Init line, it works. The reason for this is that
the first time you call Date_Init, it initializes a number of items used by
Date::Manip. Some of these have to be sorted (regular expressions sorted by
length to ensure the longest match). It turns out that perl has a bug in it
which does not allow a sort within a sort. At some point, this should be
fixed, but for now, the best thing to do is to call Date_Init explicitly. The
bug exists in all versions up to 5.005 (I haven’t tested 5.6.0 yet).
NOTE: This is an EXTREMELY inefficient way to sort data. Instead, you should
parse the dates with ParseDate, sort them using a normal string comparison, and
then convert them back to the format desired using UnixDate.
RCS Control
If you try to put Date::Manip under RCS control, you are going to have prob-
lems. Apparently, RCS replaces strings of the form "$Date...$" with the cur-
rent date. This form occurs all over in Date::Manip. To prevent the RCS key-
word 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 Savings Times
Date::Manip does not handle daylight savings 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 timezone).
print UnixDate(ParseDate("6/1/97 noon"),"%u"),"\n";
=> Sun Jun 1 12:00:00 EST 1997
June 1 EST does not exist. June 1st is during EDT. It should print:
=> Sun Jun 1 00:00:00 EDT 1997
Even explicitly adding the timezone doesn’t fix things (if anything, it makes
them worse):
print UnixDate(ParseDate("6/1/97 noon EDT"),"%u"),"\n";
=> Sun Jun 1 11:00:00 EST 1997
Date::Manip converts everything to the current timezone (EST in this case).
Related problems occur when trying to do date calculations over a timezone
change. These calculations may be off by an hour.
Also, if you are running a script which uses Date::Manip over a period of time
which starts in one time zone and ends in another (i.e. it switches form Day-
light Savings Time to Standard Time or vice versa), many things may be wrong
(especially elapsed time).
I hope to fix these problems in a future release so that it would convert
everything to the current zones (EST or EDT).
BUGS AND QUESTIONS
If you find a bug in Date::Manip, please send it directly to me (see the AUTHOR
section below) rather than posting it to one of the newsgroups. Although I try to
keep up with the comp.lang.perl.* groups, all too often I miss news (flaky news
server, articles expiring before I caught them, 1200 articles to wade through and I
missed one that I was interested in, etc.).
When filing a bug report, please include the following information:
o The version of Date::Manip you are using. You can get this by using
the script:
use Date::Manip;
print &DateManipVersion(),"\n";
o The output from "perl -V"
If you have a problem using Date::Manip that perhaps isn’t a bug (can’t figure out
the syntax, etc.), you’re in the right place. Go right back to the top of this man
page and start reading. If this still doesn’t answer your question, mail me
(again, please mail me rather than post to the newsgroup).
YEAR 2000
In hindsight, the fact that I’ve only been asked once (so far) if Date::Manip is
year 2000 compliant surprises me a bit. Still, as 2000 approaches and this buz-
zword starts flying around more and more frantically, other’s might follow suit, so
this section answers the question.
Is Date::Manip year 2000 compliant?
This question is largely meaningless. Date::Manip is basically just a parser. You
give it a date and it’ll manipulate it. Date::Manip does store the date internally
as a 4 digit year, and performs all operations using this internal representation,
so I will state that Date::Manip is CAPABLE of writing Y2K compliant code.
But Date::Manip is simply a library. If you use it correctly, your code can be Y2K
compliant. If you don’t, your code may not be Y2K compliant.
The bottom line is this:
Date::Manip is a library that is capable of being used to write Y2K
compliant code. It may also be used to write non-Y2K compliant code.
If your code is NOT Y2K compliant, it is NOT due to any deficiency in
Date::Manip. Rather, it is due to poor programming on the part of the
person using Date::Manip.
For an excellent treatment of the Y2K problem, see the article by Tom Christiansen
at:
http://language.perl.com/news/y2k.html
A slightly better question is "Is Perl year 2000 compliant"? This is covered in
the perl FAQ (section 4) and in the article by Tom Crhistiansen.
The best question is "For what dates is Date::Manip useful?" It definitely can’t
handle BC dates, or dates past Dec 31, 9999. So Date::Manip works during the years
1000 to 9999.
In practical terms however, Date::Manip deals with the Gregorian calendar, and is
therefore useful in the period that that calendar has been, or will be, in effect.
The Gregorian calendar was first adopted by the Catholic church in 1582, but some
countries were still using the Julian calendar as late as the early part of the
20th century. Also, at some point (probably no earlier than the year 3000 and pos-
sibly much later), the Gregorian system is going to have to be modified slightly
since the current system of leap years is off by a few seconds a year. So... in
practical terms, Date::Manip is _probably_ useful from 1900 to 3000.
One other note is that Date::Manip will NOT handle 3 digit years. So, if you store
the year as an offset from 1900 (which is 2 digits now, but will become 3 digits in
2000), these will NOT be parsable by Date::Manip.
VERSION NUMBERS
A note about version numbers.
Prior to version 5.00, Date::Manip was distributed as a perl4 library. There were
no numbering conventions in place, so I used a simple MAJOR.MINOR numbering scheme.
With version 5.00, I switched to a perl5 module and at that time switched to the
perl5 numbering convention of a major version followed by a 2 digit minor version.
As of 5.41/5.42, all versions released to CPAN will be even numbered. Odd numbered
will be development versions available from my web site. For example, after 5.40
was released, I started making changes, and called the development version 5.41.
When released to CPAN, it was called 5.42. I may add a third digit to development
versions (i.e. 5.41.9) to keep track of important changes in the development ver-
sion.
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 sugges-
tions 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 mention