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)
$d=&DateCalc($d1,$d2,$errref,$del)
$date=&Date_SetTime($date,$hr,$min,$sec)
$date=&Date_SetTime($date,$time)
$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)
&Date_Init()
&Date_Init("VAR=VAL",...)
$version=&DateManipVersion
$flag=&Date_IsWorkDay($date [,$flag]);
$date=&Date_NextWorkDay($date,$off [,$time]);
$date=&Date_PrevWorkDay($date,$off [,$time]);
The following routines are used by the above routines
(though they can also be called directly). Make sure that
$y is entered as the full 4 digit year (it will die if a 2
digit years is entered). 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.
$secs=&Date_SecsSince1970($m,$d,$y,$h,$mn,$s)
$secs=&Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s)
$days=&Date_DaysSince999($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()
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.
Date::Manip deals only with the Gregorian calendar (the
one currently in use). The Julian calendar defined leap
years as every 4th year. The Gregorian calendar improved
this by making every 100th year NOT a leap year, unless it
was also the 400th year. The Gregorian calendar has been
extrapolated back to the year 1000 AD and forward to the
year 9999 AD. Note that in historical context, the Julian
calendar was in use until 1582 when the Gregorian calendar
was adopted by the Catholic church. Protestant countries
did not accept it until later; Germany and Netherlands in
1698, British Empire in 1752, Russia in 1918. Note that
the Gregorian calendar is itself imperfect. Each year is
on average 26 seconds too long, which means that every
3,323 years, a day should be removed from the calendar.
No attempt is made to correct for that.
Date::Manip is therefore not equipped to truly deal with
historacle dates, but should be able to perform
(virtually) any operation dealing with a modern time and
date.
Among other things, Date::Manip allow you to:
1. Enter a date and be able to choose any format
conveniant
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
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.).
Each of these tasks is trivial (one or two lines at most)
with this package.
Although the word date is used extensively here, it is
actually somewhat misleading. Date::Manip works with the
full date AND time (year, month, day, hour, minute,
second).
In the documentation below, US formats are used, but in
most (if not all) cases, a non-English equivalent will
work equally well.
EXAMPLES
1. Parsing a date from any conveniant 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);
if ($date1 lt $date2) {
# date1 is earlier
} else {
# date2 is earlier (or the two dates are identical)
}
3. Extract information from a date.
print &UnixDate("today","The time is now %T on %b %e, %Y.");
=> "The time is now 13:24:08 on Feb 3, 1996."
4. The amount of time between two dates.
$date2=&ParseDate($string2);
$delta=&DateCalc($date1,$date2,\$err);
=> 0:0:DD:HH:MM:SS the days, hours, minutes, and seconds between the two
$delta=&DateCalc($date1,$date2,\$err,1);
=> YY:MM: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");
NOTE: Some date forms do not work as well in languages
other than English, but this is not because DateManip is
incapable of doing so (almost nothing in this module is
language dependent). It is simply that I do not have the
correct translation available for some words. If there is
a date form that works in English but does not work in a
language you need, let me know and if you can provide me
the translation, I will fix DateManip.
ROUTINES
ParseDate
$date=&ParseDate(\@args)
$date=&ParseDate($string)
$date=&ParseDate(\$string)
This takes an array or a string containing a date and
parses it. When the date is included as an array (for
example, the arguments to a program) the array should
contain a valid date in the first one or more elements
(elements after a valid date are ignored). Elements
containing a valid date are shifted from the array.
The largest possible number of elements which can be
correctly interpreted as a valid date are always used.
If a string is entered rather than an array, that
string is tested for a valid date. The string is
unmodified, even if passed in by reference.
The real work is done in the ParseDateString routine.
$date=&ParseDateString($string)
This routine is called by ParseDate, but it may also
be called directly to save some time.
A 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]
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.
Fractional seconds are also supported in parsing but
the fractional part is discarded.
Timezones always appear after the time. A number of
different forms are supported (see the section
TIMEZONEs below).
Spaces (or other separators such as "/" or "-") in the
date are always optional when there is absolutely no
ambiguity if they are not present. If there is
ambiguity, the date will either be unparsable, or (as
is more often the case) get parsed differently than
desired.
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 whenver they are immediately adjacent to
another part of the date or time.
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.
Sections of the date may be separated by spaces or by
other valid date separators (including "/", ".", and
in some cases "-"). These separators are treated very
flexibly (they are converted to spaces), so the
following dates are all equivalent:
12-10 / 1965
12 // 10 -. 1965
In some cases, this may actually be TOO flexible, but
not attempt is made to trap this.
Valid date formats include all ISO 8601 formats:
YYYYMMDDHHMNSSFFFF
YYYYMMDDHHMNSS
YYYYMMDDHHMN
YYYYMMDDHH
YY-MMDDHHMNSSF...
YY-MMDDHHMNSS
YY-MMDDHHMN
YY-MMDDHH
YYYYMMDD
YYYYMM
YYYY
YY-MMDD
YY-MM
YY
YYYYwWWD ex. 1965-W02-2
YYwWWD
YYYYDOY ex. 1965-045
YYDOY
In the above list, YYYY and YY signify 4 or 2 digit
years, MM, DD, HH, MN, SS refer to two digit month,
day, hour, minute, and second respectively. F...
refers to fractional seconds (any number of digits)
which will be ignored. The last 4 formats can be
explained by example: 1965-w02-2 refers to Tuesday
(day 2) of the 2nd week of 1965. 1965-045 refers to
the 45th day of 1965.
In all cases, parts of the date may be separated by
dashes "-". If this is done, 1 or 2 digit forms of
MM, DD, etc. may be used. All dashes are optional
except for those given in the table above (which MUST
be included for that format to be correctly parsed).
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
mmmDDYY DDmmmYY DDYYmmm YYYYmmmDD
mmmDDYYYY DDmmmYYYY DDYYYYmmm YYYY/DDmmm
the date can be separated by valid separators (space,
"/", ".", or "-" as long as it doesn't conflict with
an ISO 8601 format), but these 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 contries 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).
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"
in num weeks "in 3 weeks at
12:00"
num weeks 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)
Note that certain words such as "in", "at", "of", etc.
which commonly appear in a date or time are ignored.
Also, the year is alway optional.
In addition, the following strings are recognized:
today
now (synonym for today)
yesterday (exactly 24 hours before now)
tomorrow (exactly 24 hours from now)
noon (12:00:00)
midnight (00:00:00)
"DEceMBer" both work.
When a part of the date is not given, defaults are
used: year defaults to current year; hours, minutes,
seconds to 00.
The year may be entered as 2 or 4 digits. If entered
as 2 digits, it is taken to be the year in the range
CurrYear-89 to CurrYear+10. So, if the current year
is 1996, the range is [1907 to 2006] so entering the
year 00 refers to 2000, 05 to 2005, but 07 refers to
1907. Use 4 digit years to avoid confusion!
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. 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 otherwords, midnight is the
beginning of a day rather than the end of one. At
midnight on July 5, July 5 has just begun. The time
24:00:00 is NOT allowed (even though ISO 8601 allows
it).
The format of the date returned is YYYYMMDDHH:MM:SS.
The advantage of this time format is that two times
can be compared using simple string comparisons to
find out which is later. Also, it is readily
understood by a human. Alternate forms can be used if
that is more conveniant. See Date_Init below and the
config variable Internal.
UnixDate
@date=&UnixDate($date,@format)
$date=&UnixDate($date,@format)
This takes a date and a list of strings containing
and an array of strings corresponding to each format
is returned.
$date may be any string that can be parsed by
ParseDateString.
The format options are:
Year
%y year - 00 to 99
%Y year - 0001 to 9999
Month, Week
%m month of year - 01 to 12
%f month of year - " 1" to "12"
%b,%h month abbreviation - Jan to Dec
%B month name - January to December
%U week of year, Sunday
as first day of week - 00 to 53
%W week of year, Monday
as first day of week - 00 to 53
Day
%j day of the year - 001 to 366
%d day of month - 01 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
%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 Jan 1, 1970 GMT
- negative if before 1/1/1970
%o seconds from Jan 1, 1970 in the current time zone
%z,%Z timezone (3 characters) - "EDT"
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 %Y-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:
GLNO 1234567890 !@#$^&*()_|-=\`[];',./~{}:<>?
They currently insert the character following the %, but may (and probably
will) change in the future as new formats are requested.
If a lone percent is the final character in a format,
it is ignored.
Note that the ls format applies to date within the
past OR future 6 months!
of the year may actually be part of the last week of
the previous year. These weeks are returned as 00 in
this case. The %J option DOES produce the correct ISO
8601 format (i.e. it will not return week 0, but will
instead return week 52 or 53 of the previous year.
Note that the %s format was introduced in version
5.07. Prior to that, %s referred to the seconds since
1/1/70. This was moved to %o in 5.07.
This routine is loosely based on date.pl (version 3.2)
by Terry McGonigal. No code was used, but many of his
formats were.
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:+D:+H:+MN:+S
examples:
0:0:0:4:3:-2
+4:3:-2
mixed format
examples:
4 hour 3:-2
A field in the format +Yy is a sign, a number, and a
string specifying the type of field. The sign is "+",
"-", or absent (defaults to the next larger element).
The valid strings specifying the field type are:
y: y, yr, year, years
m: m, mon, month, months
w: w, wk, ws, wks, week, weeks
d: d, day, days
h: h, hr, hour, hours
mn: mn, min, minute, minutes
s: s, sec, second, seconds
Also, the "s" string may be omitted. The sign,
number, and string may all be separated from each
other by any number of whitespaces.
provided the rest remain in the correct order. In the
2nd (colon) format, from 2 to 6 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 prepended to the delta ("in 5
years") and the word "ago" may be appended ("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 impled minus sign in front of the 6
because when no sign is explicitely given, it carries
the previously entered sign).
The "week" field does not occur in the colon separated
delta. The reason for this is to maintain backward
compatibility with previous versions of Date::Manip.
Parsing of weeks was only added in version 5.07. At
this point, rather than change the internal format of
the delta to "Y:M:W:D:H:MN:S", I simply added the
weeks to the days (1 week = 7 days) in order to be
compatible with previous versions. So, they are not
parsed in the colon format, only in the first format.
Hopefully, this will not result in too much confusion.
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:2:-2:0:0". It returns
"+0:0:1:22:0:0" (1 day 22 hours which is equivalent).
I find (and I think most others agree) that this is a
more useful form.
Since the year/month and day/hour/min/sec parts must
be normalized separately there is the possibility that
the sign of the two parts will be different. So, the
delta "+ 2years -10 months - 2 days + 2 hours"
produces the delta "+1:2:-1:22:0:0".
For backwards compatibility, it is possible to include
a sign for all elements that is output. See the
configuration variable DeltaSigns below.
$d=&DateCalc($d1,$d2,\$err [,$mode])
This takes two dates, deltas, or one of each and
performs the appropriate calculation with them. Dates
must be a string that can be parsed by
&ParseDateString. Deltas must be a string that can be
parsed by &ParseDateDelta. Two deltas add together to
form a third delta. A date and a delta returns a 2nd
date. Two dates return a delta (the difference
between the two dates).
Note that in many cases, it is somewhat ambiguous what
the delta actually refers to. Although it is ALWAYS
known how many months in a year, hours in a day, etc.,
it is NOT known how many days form a month. As a
result, the part of the delta containing month/year
and the part with sec/min/hr/day must be treated
separately. For example, "Mar 31, 12:00:00" plus a
delta of 1month 2days would yield "May 2 12:00:00".
The year/month is first handled while keeping the same
date. Mar 31 plus one month is Apr 31 (but since Apr
only has 30 days, it becomes Apr 30). Apr 30 + 2 days
is May 2. As a result, in the case where two dates
are entered, the resulting delta can take on two
different forms. By default ($mode=0), an absolutely
correct delta (ignoring daylight savings time) is
returned in days, hours, minutes, and seconds.
If $mode is 1, the math is done using an approximate
mode where a delta is returned using years and months
as well. The year and month part is calculated first
followed by the rest. For example, the two dates "Mar
12 1995" and "Apr 13 1995" would have an exact delta
of "31 days" but in the approximate mode, it would be
returned as "1 month 1 day". Also, "Mar 31" and "Apr
30" would have deltas of "30 days" or "1 month" (since
Apr 31 doesn't exist, it drops down to Apr 30).
Approximate mode is a more human way of looking at
things (you'd say 1 month and 2 days more often then
33 days), but it is less meaningful in terms of
absolute time. In approximate mode $d1 and $d2 must
be dates. If either or both is a delta, the
calculation is done in exact mode.
If $mode is 2, a business mode is used. That is, the
calculation is done using business days, ignoring
holidays, weekends, etc. In order to correctly use
this mode, a config file must exist which contains the
section defining holidays (see documentation on the
config file below). The config file can also define
the work week and the hours of the work day, so it is
For example, if a config file defines the workday as
08:00 to 18:00, a workweek 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 autmoatically switches to the next
day. So, Tuesday at 12:00 plus 6 hours is Wednesday
at 08:00 (provided Wed is not a holiday). Also, a
date that is not during a workday automatically
becomes the start of the next workday. So, Sunday
12:00 and Monday at 03:00 both automatically becomes
Monday at 08:00 (provided Monday is not a holiday).
In business mode, any combination of date and delta
may be entered, but a delta should not contain a year
or month field (weeks are fine though).
See below for some additional comments about business
mode calculations.
Any other non-nil value of $mode is treated as $mode=1
(approximate mode).
The mode can be automatically set in the dates/deltas
passed by including a key word somewhere in it. For
example, in English, if the word "approximately" is
found in either of the date/delta arguments,
approximate mode is forced. Likewise, if the word
"business" or "exactly" appears, business/exact mode
is forced (and $mode is ignored). So, the two
following are equivalent:
$date=&DateCalc("today","+ 2 business days",\$err);
$date=&DateCalc("today","+ 2 days",\$err,2);
Note that if the keyword method is used instead of
passing in $mode, it is important that the keyword
actually appear in the argument passed in to DateCalc.
The following will NOT work:
$delta=&ParseDateDelta("+ 2 business days");
$today=&ParseDate("today");
$date=&DateCalc($today,$delta,\$err);
because the mode keyword is removed from a date/delta
by the parse routines, and the mode is reset each time
a parse routine is called. Since DateCalc parses both
of its arguments, whatever mode was previously set is
ignored.
$err is set to:
1 is returned if $d1 is not a delta or date
to 9999
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, to get the time for 7:30 tomorrow, use the
lines:
$date=&ParseDate("tomorrow")
$date=&Date_SetTime($date,"7:30")
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 a previous date.
If $dow is defined, it is a day of week (a string such
as "Fri" or a number from 0 to 6). The date of the
previous $dow is returned. If $date falls on this day
of week, the date returned will be $date (if $curr is
non-zero) or a week earlier (if $curr is 0). If a
time is passed in (either as separate hours, minutes,
seconds or as a time in HH:MM:SS or HH:MM format), the
time on this date is set to it. The following
examples should illustrate the use of Date_GetPrev:
date dow curr time returns
Fri Nov 22 18:15:00 Thu 0 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 12:30 Fri Nov 22 12:30:00
If $dow is undefined, then a time must be entered, and
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 pass 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_DayOfWeek
$day=&Date_DayOfWeek($m,$d,$y);
Returns the day of the week (0 for Sunday, 6 for
Saturday). Dec 31, 0999 was Tuesday.
All arguments must be numeric. Year must be 4 digits.
Date_SecsSince1970
$secs=&Date_SecsSince1970($m,$d,$y,$h,$mn,$s)
Returns the number of seconds since Jan 1, 1970 00:00
(negative if date is earlier).
All arguments must be numeric. Year must be 4 digits.
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
treated as being in GMT).
All arguments must be numeric. Year must be 4 digits.
Date_DaysSince999
$days=&Date_DaysSince999($m,$d,$y)
Returns the number of days since Dec 31, 0999.
All arguments must be numeric. Year must be 4 digits.
Date_DayOfYear
$day=&Date_DayOfYear($m,$d,$y);
Returns the day of the year (001 to 366)
All arguments must be numeric. Year must be 4 digits.
Date_DaysInYear
$days=&Date_DaysInYear($y);
Returns the number of days in the year (365 or 366)
Year must be 4 digits.
Date_DaysInMonth
$days=&Date_DaysInMonth($m,$y);
Returns the number of days in the month.
Year must be 4 digits.
Date_WeekOfYear
$wkno=&Date_WeekOfYear($m,$d,$y,$first);
Figure out week number. $first is the first day of
the week which is usually 0 (Sunday) or 1 (Monday),
but could be any number between 0 and 6 in practice.
All arguments must be numeric. Year must be 4 digits.
Date_LeapYear
$flag=&Date_LeapYear($y);
Returns 1 if the argument is a leap year Written by
David Muir Sharnoff <muir@idiom.com>
Date_DaySuffix
$day=&Date_DaySuffix($d);
Add `st', `nd', `rd', `th' to a date (ie 1st, 22nd,
29th). Works for international dates.
Date_TimeZone
$tz=&Date_TimeZone
This returns a timezone. It looks in the following
places for a timezone in the following order:
$ENV{TZ}
$main::TZ
unix 'date' command
/etc/TIMEZONE
If it's not found in any of those places, an error
occurs:
ERROR: Date::Manip unable to determine TimeZone.
Date_TimeZone is able to read zones of the format
PST8PDT (see TIMEZONES documentation below).
Date_ConvTZ
$date=&Date_ConvTZ($date)
$date=&Date_ConvTZ($date,$from)
$date=&Date_ConvTZ($date,(),$to)
$date=&Date_ConvTZ($date,$from,$to)
This converts a date (which MUST be in the format
returned by ParseDate) from one timezone to another.
If it is called with no arguments, the date is
converted from the local timezone to the timezone
specified by the config variable ConvTZ (see
documentation on ConvTZ below). If ConvTZ is set to
"IGNORE", no conversion is done.
If called with $from but no $to, the timezone is
converted from the timezone in $from to ConvTZ (of TZ
if ConvTZ is not set). Again, no conversion is done
if ConvTZ is set to "IGNORE".
If called with $to but no $from, $from defaults to
ConvTZ (if set) or the local timezone otherwise.
Although this does not seem immediately obvious, it
being worked with will be stored in that timezone.
If Date_ConvTZ is called with both $from and $to, the
date is converted from the timezone $from to $to.
NOTE: As in all other cases, the $date returned from
Date_ConvTZ has no timezone information included as
part of it, so calling UnixDate with the "%z" format
will return the timezone that Date::Manip is working
in (usually the local timezone).
Example: To convert 2/2/96 noon PST to CST
(regardless of what timezone you are in, do the
following:
$date=&ParseDate("2/2/96 noon");
$date=&Date_ConvTZ($date,"PST","CST");
Both timezones MUST be in one of the formst listed
below in the section TIMEZONES.
Date_Init
$flag=&Date_Init();
$flag=&Date_Init("VAR=VAL","VAR=VAL",...);
Normally, it is not necessary to explicitely 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
reinitizize 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
configuaration 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=nonUS");
Note that the usage of Date_Init changed with version
5.07. The old calling convention is allowed but is
depreciated.
If you change timezones in the middle of using
Date::Manip, comparing dates from before the switch to
dates from after the switch will produce incorrect
$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.
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.
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
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 Standare -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 from the
Time::Zone module by Graham Barr, David Muir Sharnoff, and
NT -1100 Nome
HST -1000 Hawaii Standard
CAT -1000 Central Alaska
AHST -1000 Alaska-Hawaii Standard
YST -0900 Yukon Standard
HDT -0900 Hawaii 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
EDT -0400 Eastern Daylight
AST -0400 Atlantic Standard
#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
ADT -0300 Atlantic Daylight
NDT -0230 Newfoundland Daylight
AT -0200 Azores
WAT -0100 West Africa
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
MEWT +0100 Middle European Winter
SWT +0100 Swedish Winter
#BST +0100 British Summer bst=Brazil standard -0300
CEST +0200 Central European Summer
EET +0200 Eastern Europe, USSR Zone 1
FST +0200 French Summer
MEST +0200 Middle European Summer
METDST +0200 An alias for MEST used by HP-UX
SST +0200 Swedish Summer sst=South Sumatra +0700
BT +0300 Baghdad, USSR Zone 2
IT +0330 Iran
ZP4 +0400 USSR Zone 3
ZP5 +0500 USSR Zone 4
IST +0530 Indian Standard
ZP6 +0600 USSR Zone 5
NST +0630 North Sumatra nst=Newfoundland Std -0330
WAST +0700 West Australian Standard
#SST +0700 South Sumatra, USSR Zone 6 sst=Swedish Summer +0200
JT +0730 Java (3pm in Cronusland!)
CCT +0800 China Coast, USSR Zone 7
WADT +0800 West Australian Daylight
CAST +0930 Central Australian Standard
EAST +1000 Eastern Australian Standard
GST +1000 Guam Standard, USSR Zone 9 gst=Greenland Std -0300
CADT +1030 Central Australian 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.
DateManip needs to be able to determine the local
timezone. It can do this by certain things such as the TZ
environment variable (see Date_TimeZone documentation
above) or useing the TZ config variable (described below).
In either case, the timezone can be of the form STD#DST
(for example EST5EDT). Both the standard and daylight
savings time abbreviations must be in the table above in
order for this to work. Also, this form may NOT be used
when parsing a date as there is no way to determine
whether the date is in daylight saving time or not. The
following forms are also available and are treated similar
to the STD#DST forms:
US/Pacific
US/Mountain
US/Central
US/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
as to what day 17:00 really falls on, similar to the
ambiguity that occurs when you ask what day midnight falls
on. Although it's not the only answer, Date::Manip treats
midnight as the beginning of a day rather than the end of
one. In the same way, 17:00 is equivalent to 9:00 the
next day and any time the date calculations encounter
17:00, it automatically switch to 9:00 the next day.
Although this introduces some quirks, I think this is
justified. You just have to treat 9:00 as being ambiguous
(in the same way you treat midnight as being ambiguous).
Equivalently, if I want a job to be finished on Saturday
(despite the fact that I cannot pick it up since the
business is closed), I have to drop it off no later than
Friday at 9:00. That gives them a full business day to
finish it off. Of course, I could just as easily drop it
off at 17:00 Thursday, or any time between then and 9:00
Friday. Again, it's a matter of treating 9:00 as
ambiguous.
So, in case the business date calculations ever produce
results that you find confusing, I believe the solution is
to write a wrapper which, whenever it sees a date with the
time of exactly 9:00, it treats it specially (depending on
what you want.
So Saturday + 1 business day = Tuesday at 9:00 (which
means anything from Monday 17:00 to Tuesday 9:00), but
Monday at 9:01 + 1 business day = Tuesday at 9:01 which is
exact.
If this is not exactly what you have in mind, don't use
the DateCalc routine. You can probably get whatever
behavior you want using the routines Date_IsWorkDay,
Date_NextWorkDay, and Date_PrevWorkDay described above.
CUSTOMIZING DATE::MANIP
There are a number of variables which can be used to
customize the way Date::Manip behaves. There are also
several ways to set these variables.
At the top of the Manip.pm file, there is a section which
contains all customization variables. These provide the
default values.
These can be overridden in a global config file if one is
present (this file is optional). If the GlobalCnf
variable is set in the Manip.pm file, it contains the full
path to a config file. If the file exists, 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
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.
Finally, any variables passed in through Date_Init
override all other values.
A config file can be composed of several sections (though
only 2 of them are currently used). The first section
sets configuration varibles. Lines in this section are of
the form:
VARIABLE = VALUE
For example, to make the default language French, include
the line:
Language = French
Only variables described below may be used. Blank lines
and lines beginning with a pound sign (#) are ignored.
All spaces are optional and strings are case insensitive.
A line which starts with an asterix (*) designates a new
section. The only section currently used is the Holiday
section. All lines are of the form:
DATE = HOLIDAY
HOLIDAY is the name of the holiday (or it can be blank in
which case the day will still be treated as a holiday...
for example the day after Thanksgiving or Christmas is
often a work holiday though neither are named).
DATE is a string which can be parsed to give a valid date
in any year. It can be of the form
Date
Date + Delta
Date - Delta
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
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 =
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.
PersonalCnf
This variable can be passed into Date_Init to read a
different personal configuration file. It can also be
included in the global config file to define where
personal config files live.
PersonalCnfPath
Used in the same way as the PersonalCnf option. You
can use tilde (~) expansions when defining the path.
Language
Date::Manip can be used to parse dates in many
different languages. Currently, it is configured to
read English, Swedish, and French dates, but others
can be added easily. Language is set to the language
used to parse dates.
DateFormat
Different countries look at the date 12/10/96 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 Date::Manip is able to understand some timezones (and
others will be added in the future). At the very
least, all zones defined in RFC 822 are supported.
Currently supported zones are listed in the TIMEZONES
section above and all timezones should be entered as
one of them.
user is in. It does this by looking in the following
places:
the environment variable TZ
the variable $main::TZ
the file /etc/TIMEZONE
the 5th element of the unix "date" command (not available on NT machines)
At least one of these should contain a timezone in one
of the supported forms. If it doesn't, the TZ
variable must be set to contain the local timezone in
the appropriate form.
The TZ variable will override the other methods of
determining the timezone, so it should probably be
left blank if any of the other methods will work.
Otherwise, you will have to modify the variable every
time you switch to/from daylight savings time.
ConvTZ
All date comparisons and calculations must be done in
a single time zone in order for them to work
correctly. So, when a date is parsed, it should be
converted to a specific timezone. This allows dates
to easily be compared and manipulated as if they are
all in a single timezone.
The ConvTZ variable determines which timezone should
be used to store dates in. If it is left blank, all
dates are converted to the local timezone (see the TZ
variable above). If it is set to one of the timezones
listed above, all dates are converted to this
timezone. Finally, if it is set to the string
"IGNORE", all timezone information is ignored as the
dates are read in (in this case, the two dates "1/1/96
12:00 GMT" and "1/1/96 12:00 EST" would be treated as
identical).
Internal
When a date is parsed using ParseDate, that date is
stored in an internal format which is understood by
the Date::Manip routines UnixDate and DateCalc.
Originally, the format used to store the date
internally was:
YYYYMMDDHH:MN:SS
It has been suggested that I remove the colons (:) to
shorten this to:
YYYYMMDDHHMNSS
Date::Manip tedious.
In order to maintain backwards compatibility, the
Internal variable was introduced. Set it to 0 (to use
the old format) or 1 (to use the new format).
FirstDay
It is sometimes necessary to know what day of week is
regarded as first. By default, this is set to sunday,
but many countries and people will prefer monday (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) Incidentally, monday should be
chosen as the default to be in complete accordance
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 0
(sunday) to 6 (saturday). There is no way to handle
an odd work week of Thu to Mon for example.
WorkDay24Hr
If this is non-nil, a work day is treated as being 24
hours long. The WorkDayBeg and WorkDayEnd variables
are ignored in this case.
WorkDayBeg, WorkDayEnd
The times when the work day starts and ends.
WorkDayBeg must come before WorkDayEnd (i.e. there is
no way to handle the night shift where the work day
starts one day and ends another). Also, the workday
MUST be more than one hour long (of course, if this
isn't the case, let me know... I want a job there!).
The time in both can be in any valid time format
(including international formats), but seconds will be
ignored.
DeltaSigns
Prior to Date::Manip version 5.07, a negative delta
would put negative signs in front of every component
(i.e. "0:0:-1:-3:0:-4"). By default, 5.07 changes
this behavior to print only 1 or two signs in front of
the year and day elements (even if these elements
might be zero) and the sign for year/month and
day/hour/minute/second are the same. Setting this
variable to non-zero forces deltas to be stored with a
sign in front of every element (including elements
equal to 0).
ISO 8601 states that the first week of the year is the
one which contains Jan 4 (i.e. it is the first week in
which most of the days in that week fall in that
year). This means that the first 3 days of the year
may be treated as belonging to the last week of the
previous year. If this is set to non-nil, the ISO
8601 standard will be ignored and the first week of
the year contains Jan 1.
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.
Version 5.07 introduced 2 minor incompatibilities. In the
UnixDate command, the "%s" format changed. In version
5.06, "%s" returned the number of seconds since Jan 1,
1970 in the current timezone. In 5.07, it returns the
number of seconds since Jan 1, 1970 GMT. The "%o" format
was added to return what "%s" previously did.
Also in 5.07, the format for the deltas returned by
ParseDateDelta changed. Previously, each element of a
delta had a sign attached to it (+1:+2:+3:+4:+5:+6). The
new format removes all unnecessary signs by default
(+1:2:3:4:5:6). Also, because of the way deltas are
normalized (see documentation on ParseDateDelta), at most
two signs are included. For backwards compatibility, the
config variable DeltaSigns was added. If set to 1, all
deltas include all 6 signs.
Finally, in 5.07 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",...);
Version 5.20 has some more noticable incompatibilities in
it. Full support for ISO 8601 formats was added. As a
result, some formats which previously worked may no longer
be parsed since they conflict with an ISO 8601 format.
These include MM-DD-YY (conflicts with YY-MM-DD) and
YYMMDD (conflicts with YYYYMM).
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
COMMON PROBLEMS
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 those
without a unix date command... i.e. Microsoft Windows
systems). To fix this, just set the TZ variable, either
at the top of the Manip.pm file, or in the DateManip.cnf
file. 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.
KNOWN PROBLEMS
Daylight Savings Times
Date::Manip does not handle daylight savings time,
though it does handle timezones to a certain extent.
Converting from EST to PST works fine. Going from EST
to PDT is unreliable.
The following examples are run in the winter of the US
East coast (i.e. in the EST timezone).
print UnixDate(ParseDate("6/1/97 noon"),"%u"),"\n";
=> Sun Jun 1 12:00:00 EST 1997
June 1 EST does not exist. June 1st is during EDT.
It should print:
=> Sun Jun 1 00:00:00 EDT 1997
Even explicitely adding the timezone doesn't fix
things (if anything, it makes them worse):
print UnixDate(ParseDate("6/1/97 noon EDT"),"%u"),"\n";
=> Sun Jun 1 11:00:00 EST 1997
Date::Manip converts everything to the current
timezone (EST in this case).
Related problems occur when trying to do date
calculations over a timezone change. These
calculations may be off by an hour.
Also, if you are running a script which uses
Date::Manip over a period of time which starts in one
time zone and ends in another (i.e. it switches form
Daylight Savings Time to Standard Time or vice versa),
many things may be wrong (especially elapsed time).
that it would convert everything to the current zones
(EST or EDT).
Sorting Problems
If you use Date::Manip to sort a number of dates, you
must call Date_Init either explicitely, 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 ($date1 cmp $date2);
}
@date = ("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 are sorted. It turns out
that perl (5.003 and earlier) has a bug in it which
does not allow a sort within a sort. The next version
(5.004) may fix this. For now, the best thing to do
is to call Date_Init explicitely. NOTE: This is an
extremely inefficient way to sort data. Instead, you
should translate the dates to the Date::Manip internal
format, sort them using a normal string comparison,
and then convert them back to the format desired using
UnixDate.
NOTE: 5.004 has not fixed this to date.
RCS Control
If you try to put Date::Manip under RCS control, you
are going to have problems. Apparently, RCS replaces
strings of the form "$Date...$" with the current date.
This form occurs all over in Date::Manip. Since very
few people will ever have a desire to do this (and I
don't use RCS), I have not worried about it.
BUGS AND QUESTIONS
If you find a bug in Date::Manip, please send it directly
to me (see the AUTHOR section below) rather than post 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
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).
AUTHOR
Sullivan Beck (sbeck@cise.ufl.edu)