|
Packit |
95306a |
# Copyright (c) 1995-2017 Sullivan Beck. All rights reserved.
|
|
Packit |
95306a |
# This program is free software; you can redistribute it and/or modify it
|
|
Packit |
95306a |
# under the same terms as Perl itself.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=pod
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 NAME
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip::DM6 - Date manipulation routines
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 SYNOPSIS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
use Date::Manip;
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$version = DateManipVersion($flag);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date_Init("VAR=VAL","VAR=VAL",...);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = ParseDate(\@args [,@opts]);
|
|
Packit |
95306a |
$date = ParseDate($string [,@opts]);
|
|
Packit |
95306a |
$date = ParseDate(\$string [,@opts]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = ParseDateString($string [,@opts]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = ParseDateFormat($format,$string);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
@date = UnixDate($date,@format);
|
|
Packit |
95306a |
$date = UnixDate($date,@format);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$delta = ParseDateDelta(\@args [,$mode]);
|
|
Packit |
95306a |
$delta = ParseDateDelta($string [,$mode]);
|
|
Packit |
95306a |
$delta = ParseDateDelta(\$string [,$mode]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
@str = Delta_Format($delta, [$mode,] $dec,@format);
|
|
Packit |
95306a |
$str = Delta_Format($delta, [$mode,] $dec,@format);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$recur = ParseRecur($string,$base,$date0,$date1,$flags);
|
|
Packit |
95306a |
@dates = ParseRecur($string,$base,$date0,$date1,$flags);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$flag = Date_Cmp($date1,$date2);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$d = DateCalc($d1,$d2 [,$errref] [,$mode]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_SetTime($date,$hr,$min,$sec);
|
|
Packit |
95306a |
$date = Date_SetTime($date,$time);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_SetDateField($date,$field,$val [,$nocheck]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_GetPrev($date,$dow,$today,$hr,$min,$sec);
|
|
Packit |
95306a |
$date = Date_GetPrev($date,$dow,$today,$time);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_GetNext($date,$dow,$today,$hr,$min,$sec);
|
|
Packit |
95306a |
$date = Date_GetNext($date,$dow,$today,$time);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$name = Date_IsHoliday($date);
|
|
Packit |
95306a |
@name = Date_IsHoliday($date);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$listref = Events_List($date);
|
|
Packit |
95306a |
$listref = Events_List($date0,$date1);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_ConvTZ($date,$from,$to);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$flag = Date_IsWorkDay($date [,$flag]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_NextWorkDay($date,$off [,$time]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_PrevWorkDay($date,$off [,$time]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_NearestWorkDay($date [,$tomorrowfirst]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In the following routines, $y may be entered as either a 2 or 4 digit
|
|
Packit |
95306a |
year (it will be converted to a 4 digit year based on the variable
|
|
Packit |
95306a |
YYtoYYYY described below). Month and day should be numeric in all
|
|
Packit |
95306a |
cases.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$day = Date_DayOfWeek($m,$d,$y);
|
|
Packit |
95306a |
$secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
|
|
Packit |
95306a |
$secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
|
|
Packit |
95306a |
$days = Date_DaysSince1BC($m,$d,$y);
|
|
Packit |
95306a |
$day = Date_DayOfYear($m,$d,$y);
|
|
Packit |
95306a |
($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
|
|
Packit |
95306a |
$days = Date_DaysInYear($y);
|
|
Packit |
95306a |
$days = Date_DaysInMonth($m,$y);
|
|
Packit |
95306a |
$wkno = Date_WeekOfYear($m,$d,$y,$first);
|
|
Packit |
95306a |
$flag = Date_LeapYear($y);
|
|
Packit |
95306a |
$day = Date_DaySuffix($d);
|
|
Packit |
95306a |
$tz = Date_TimeZone();
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 ROUTINES
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<DateManipVersion>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$version = DateManipVersion($flag);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Returns the version of Date::Manip. If $flag is non-zero, timezone information
|
|
Packit |
95306a |
is also returned.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_Init>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date_Init("VAR=VAL","VAR=VAL",...);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The Date_Init function is used to set any of the Date::Manip configuration
|
|
Packit |
95306a |
variables described in the Date::Manip::Config document.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The strings to pass in are of the form "VAR=VAL". Any number may be
|
|
Packit |
95306a |
included and they can come in any order. VAR may be any configuration
|
|
Packit |
95306a |
variable. VAL is any allowed value for that variable. For example,
|
|
Packit |
95306a |
to switch from English to French and use non-US format (so that 12/10
|
|
Packit |
95306a |
is Oct 12), do the following:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date_Init("Language=French","DateFormat=non-US");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Note that variables are parsed in the order they are given, so
|
|
Packit |
95306a |
"DateFormat=non-US", "ConfigFile=./manip.cnf" may not give the
|
|
Packit |
95306a |
expected result. To be safe, ConfigFile should always appear first in
|
|
Packit |
95306a |
the list.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<ParseDate>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = ParseDate(\@args [,@opts]);
|
|
Packit |
95306a |
$date = ParseDate($string [,@opts]);
|
|
Packit |
95306a |
$date = ParseDate(\$string [,@opts]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This takes an array or a string containing a date and parses it. When the
|
|
Packit |
95306a |
date is included as an array (for example, the arguments to a program) the
|
|
Packit |
95306a |
array should contain a valid date in the first one or more elements
|
|
Packit |
95306a |
(elements after a valid date are ignored). Elements containing a valid
|
|
Packit |
95306a |
date are shifted from the array. The largest possible number of elements
|
|
Packit |
95306a |
which can be correctly interpreted as a valid date are always used. If a
|
|
Packit |
95306a |
string is entered rather than an array, that string is tested for a valid
|
|
Packit |
95306a |
date. The string is unmodified, even if passed in by reference.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The ParseDate routine is primarily used to handle command line arguments.
|
|
Packit |
95306a |
If you have a command where you want to enter a date as a command line
|
|
Packit |
95306a |
argument, you can use Date::Manip to make something like the following
|
|
Packit |
95306a |
work:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
mycommand -date Dec 10 1997 -arg -arg2
|
|
Packit |
95306a |
|
|
Packit |
95306a |
No more reading man pages to find out what date format is required in a
|
|
Packit |
95306a |
man page.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The C<@opts> argument may contain values that can be passed to the
|
|
Packit |
95306a |
C<Date::Manip::Date::parse> method.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Historical note: this is originally why the Date::Manip routines were
|
|
Packit |
95306a |
written (though long before they were released as the Date::Manip module).
|
|
Packit |
95306a |
I was using a bunch of programs (primarily batch queue managers) where
|
|
Packit |
95306a |
dates and times were entered as command line options and I was getting
|
|
Packit |
95306a |
highly annoyed at the many different (but not compatible) ways that they
|
|
Packit |
95306a |
had to be entered. Date::Manip originally consisted of basically 1 routine
|
|
Packit |
95306a |
which I could pass "@ARGV" to and have it remove a date from the beginning.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<ParseDateString>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = ParseDateString($string [,@opts]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This parses a string containing a date and returns it. Refer to the
|
|
Packit |
95306a |
Date::Manip::Date documentation for valid date formats. The date
|
|
Packit |
95306a |
returned is in the local time zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The C<@opts> argument may contain values that can be passed to the
|
|
Packit |
95306a |
C<Date::Manip::Date::parse> method.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<ParseDateFormat>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = ParseDateFormat($format,$string);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This parses a string containing a date based on a format string and
|
|
Packit |
95306a |
returns the date. Refer to the Date::Manip::Date documentation for the
|
|
Packit |
95306a |
parse_format method for more information. The date returned is in the
|
|
Packit |
95306a |
local time zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<UnixDate>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$out = UnixDate($date,$in);
|
|
Packit |
95306a |
@out = UnixDate($date,@in);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This takes a date and a list of strings containing formats roughly
|
|
Packit |
95306a |
identical to the format strings used by the UNIX date(1) command.
|
|
Packit |
95306a |
Each format is parsed and an array of strings corresponding to each
|
|
Packit |
95306a |
format is returned.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The formats are described in the Date::Manip::Date document.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<ParseDateDelta>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$delta = ParseDateDelta(\@args [,$mode]);
|
|
Packit |
95306a |
$delta = ParseDateDelta($string [,$mode]);
|
|
Packit |
95306a |
$delta = ParseDateDelta(\$string [,$mode]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In the first form, it takes an array and shifts a valid delta from it.
|
|
Packit |
95306a |
In the other two forms, it parses a string to see if it contains a
|
|
Packit |
95306a |
valid delta.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
A valid delta is returned if found. Otherwise, an empty string is
|
|
Packit |
95306a |
returned.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The delta can be converted to 'exact', 'semi', or 'approx' using the
|
|
Packit |
95306a |
Date::Manip::Delta::convert method if $mode is passed in.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Delta_Format>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$out = Delta_Format($delta [,$mode], $dec,$in);
|
|
Packit |
95306a |
@out = Delta_Format($delta [,$mode], $dec,@in);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This is similar to the UnixDate routine except that it extracts information
|
|
Packit |
95306a |
from a delta.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
When formatting fields in a delta, the Date::Manip 6.00 formats have changed
|
|
Packit |
95306a |
and are much more powerful. The old 5.xx formats are still available for
|
|
Packit |
95306a |
the Delta_Format command for backward compatibility. These formats include:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
%Xv : print the value of the field X
|
|
Packit |
95306a |
|
|
Packit |
95306a |
%Xd : print the value of the field X and all
|
|
Packit |
95306a |
smaller units in terms of X
|
|
Packit |
95306a |
|
|
Packit |
95306a |
%Xh : print the value of field X and all
|
|
Packit |
95306a |
larger units in terms of X
|
|
Packit |
95306a |
|
|
Packit |
95306a |
%Xt : print the value of all fields in
|
|
Packit |
95306a |
terms of X
|
|
Packit |
95306a |
|
|
Packit |
95306a |
These make use of the $mode and $dec arguments to determine how to
|
|
Packit |
95306a |
format the information.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$dec is an integer, and is required, It tells the number of decimal
|
|
Packit |
95306a |
places to use.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$mode is either "exact", "semi", or "approx" and defaults to "exact"
|
|
Packit |
95306a |
if it is not included.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In "exact" mode, only exact relationships are used. This means that
|
|
Packit |
95306a |
there can be no mixing of the Y/M, W/D, and H/MN/S segments (for
|
|
Packit |
95306a |
non-business deltas, or Y/M, W, and D/H/MN/S segments for business
|
|
Packit |
95306a |
deltas) because there is no exact relation between the fields of each
|
|
Packit |
95306a |
set.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In "semi" mode, the semi-approximate relationships are used so
|
|
Packit |
95306a |
there is no mixing between Y/M and W/D/H/MN/S.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In "approx" mode, approximate relationships are used so all fields
|
|
Packit |
95306a |
can mix.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The semi-approximate and approximate relationships are described in
|
|
Packit |
95306a |
the Date::Manip::Delta manual.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
So, in "exact" mode, with a non-business delta, and $dec = 2, the
|
|
Packit |
95306a |
following are equivalent:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
old style new style
|
|
Packit |
95306a |
--------- ---------
|
|
Packit |
95306a |
%Xv %Xv
|
|
Packit |
95306a |
%hd %.2hhs
|
|
Packit |
95306a |
%hh %.2hdh
|
|
Packit |
95306a |
%ht %.2hds
|
|
Packit |
95306a |
%yd %.2yyM
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In "approximate" mode, the following are equivalent:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
old style new style
|
|
Packit |
95306a |
--------- ---------
|
|
Packit |
95306a |
%Xv %Xv
|
|
Packit |
95306a |
%hd %.2hhs
|
|
Packit |
95306a |
%hh %.2hdh
|
|
Packit |
95306a |
%ht %.2hys
|
|
Packit |
95306a |
%yd %.2yys
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If you want to use the new style formats in Delta_Format, use one of
|
|
Packit |
95306a |
the calls:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Delta_Format($delta, @in);
|
|
Packit |
95306a |
Delta_Format($delta, undef, @in);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If the first element of @in is an integer, you have to use the 2nd
|
|
Packit |
95306a |
form.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The old formats will remain available for the time being, though at
|
|
Packit |
95306a |
some point they may be deprecated.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<DateCalc>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$d = DateCalc($d1,$d2 [,\$err] [,$mode]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This takes two dates, deltas, or one of each and performs the appropriate
|
|
Packit |
95306a |
calculation with them. Dates must be a string that can be parsed by
|
|
Packit |
95306a |
ParseDateString. Deltas must be a string that can be parsed by
|
|
Packit |
95306a |
ParseDateDelta. Two deltas add together to form a third delta. A date
|
|
Packit |
95306a |
and a delta returns a 2nd date. Two dates return a delta (the difference
|
|
Packit |
95306a |
between the two dates).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Since the two items can be interpreted as either dates or deltas, and
|
|
Packit |
95306a |
since many strings can be interpreted as both a date or a delta, it
|
|
Packit |
95306a |
is a good idea to pass the input through ParseDateDelta,
|
|
Packit |
95306a |
if appropriate if there is any ambiguity. For example, the string
|
|
Packit |
95306a |
"09:00:00" can be interpreted either as a date (today at 9:00:00) or a
|
|
Packit |
95306a |
delta (9 hours). To avoid unexpected results, avoid calling DateCalc
|
|
Packit |
95306a |
as:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$d = DateCalc("09:00:00",$someothervalue);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Instead, call it as:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$d = DateCalc(ParseDate("09:00:00"),$someothervalue);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
to force it to be a date, or:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$d = DateCalc(ParseDateDelta("09:00:00"),$someothervalue);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
to force it to be a delta. This will avoid unexpected results.
|
|
Packit |
95306a |
Passing something through ParseDate is optional since they will be
|
|
Packit |
95306a |
treated as dates by default (and for performance reasons, you're
|
|
Packit |
95306a |
better off not calling ParseDate).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If there is no ambiguity, you are better off NOT doing this for
|
|
Packit |
95306a |
performance reasons. If the delta is a business delta, you definitely
|
|
Packit |
95306a |
should NOT do this.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
One other thing to note is that when parsing dates, a delta can
|
|
Packit |
95306a |
be interpreted as a date relative to now. DateCalc will ALWAYS
|
|
Packit |
95306a |
treat a delta as a delta, NOT a date.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
For details on how calculations are done, refer to the Date::Manip::Calc
|
|
Packit |
95306a |
documentation.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
By default, math is done using an exact mode.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If two deltas, or a date and a delta are passed in, $mode may be used
|
|
Packit |
95306a |
to force the delta to be either business or non-business mode deltas.
|
|
Packit |
95306a |
If $mode is 0 or 1, the delta(s) will be non-business. Otherwise,
|
|
Packit |
95306a |
they will be business deltas. If $mode is passed in, it will be used
|
|
Packit |
95306a |
only if the business or non-business state was not explicitly set in
|
|
Packit |
95306a |
the delta. $mode can also be any of the modes discussed in
|
|
Packit |
95306a |
the Date::Manip::Calc documentation.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If two dates are passed in, $mode is used to determine the type of
|
|
Packit |
95306a |
calculation. By default, an exact delta is produced. If $mode is 1,
|
|
Packit |
95306a |
an approximate delta is produced. If $mode is 2, a business
|
|
Packit |
95306a |
approximate (bapprox) mode calculation is done. If $mode is 3, a
|
|
Packit |
95306a |
exact business mode delta is produced.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If \$err is passed in, it is set to:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
1 is returned if $d1 is not a delta or date
|
|
Packit |
95306a |
2 is returned if $d2 is not a delta or date
|
|
Packit |
95306a |
3 if any other error occurs.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This argument is optional, but if included, it must come before $mode.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Nothing is returned if an error occurs.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<ParseRecur>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$recur = ParseRecur($string [,$base,$date0,$date1,$flags]);
|
|
Packit |
95306a |
@dates = ParseRecur($string [,$base,$date0,$date1,$flags]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This parses a string containing a recurrence and returns a fully specified
|
|
Packit |
95306a |
recurrence, or a list of dates referred to.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$string can be any of the forms:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
FREQ
|
|
Packit |
95306a |
FREQ*FLAGS
|
|
Packit |
95306a |
FREQ*FLAGS*BASE
|
|
Packit |
95306a |
FREQ*FLAGS*BASE*DATE0
|
|
Packit |
95306a |
FREQ*FLAGS*BASE*DATE0*DATE1
|
|
Packit |
95306a |
|
|
Packit |
95306a |
where FREQ is a frequence (see the Date::Manip::Delta documentation),
|
|
Packit |
95306a |
FLAGS is a comma separated list of flags, and BASE, DATE0, and DATE1 are
|
|
Packit |
95306a |
date strings. The dates and flags can also be passed in as $base, $date0,
|
|
Packit |
95306a |
$date1, and $flags, and these will override any values in $string.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In scalar context, the fully specified recurrence (or as much information
|
|
Packit |
95306a |
as is available) will be returned. In list context, a list of dates will
|
|
Packit |
95306a |
be returned.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_Cmp>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$flag = Date_Cmp($date1,$date2);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This takes two dates and compares them. Any dates that can be parsed will be
|
|
Packit |
95306a |
compared.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_GetPrev>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_GetPrev($date,$dow, $curr [,$hr,$min,$sec]);
|
|
Packit |
95306a |
$date = Date_GetPrev($date,$dow, $curr [,$time]);
|
|
Packit |
95306a |
$date = Date_GetPrev($date,undef,$curr,$hr,$min,$sec);
|
|
Packit |
95306a |
$date = Date_GetPrev($date,undef,$curr,$time);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This takes a date (any string that may be parsed by ParseDateString) and finds
|
|
Packit |
95306a |
the previous occurrence of either a day of the week, or a certain time of day.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This is documented in the "prev" method in Date::Manip::Date, except that
|
|
Packit |
95306a |
here, $time is a string (HH, HH:MN:, or HH:MN:SS), and $dow may be a string
|
|
Packit |
95306a |
of the form "Fri" or "Friday".
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_GetNext>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_GetNext($date,$dow, $curr [,$hr,$min,$sec]);
|
|
Packit |
95306a |
$date = Date_GetNext($date,$dow, $curr [,$time]);
|
|
Packit |
95306a |
$date = Date_GetNext($date,undef,$curr,$hr,$min,$sec);
|
|
Packit |
95306a |
$date = Date_GetNext($date,undef,$curr,$time);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Similar to Date_GetPrev.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_SetTime>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_SetTime($date,$hr,$min,$sec);
|
|
Packit |
95306a |
$date = Date_SetTime($date,$time);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This takes a date (any string that may be parsed by ParseDateString) and
|
|
Packit |
95306a |
sets the time in that date. For example, one way to get the time for 7:30
|
|
Packit |
95306a |
tomorrow would be to use the lines:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = ParseDate("tomorrow");
|
|
Packit |
95306a |
$date = Date_SetTime($date,"7:30");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$time is a string (HH, HH:MN, or HH:MN:SS).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_SetDateField>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_SetDateField($date,$field,$val);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This takes a date and sets one of its fields to a new value. $field is
|
|
Packit |
95306a |
any of the strings "y", "m", "d", "h", "mn", "s" (case insensitive) and
|
|
Packit |
95306a |
$val is the new value.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_IsHoliday>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$name = Date_IsHoliday($date);
|
|
Packit |
95306a |
@name = Date_IsHoliday($date);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This returns undef if $date is not a holiday, or a string containing
|
|
Packit |
95306a |
the name of the holiday otherwise (or a list of names in list
|
|
Packit |
95306a |
context). An empty string is returned for an unnamed holiday.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_IsWorkDay>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$flag = Date_IsWorkDay($date [,$flag]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This returns 1 if $date is a work day. If $flag is non-zero, the time is
|
|
Packit |
95306a |
checked to see if it falls within work hours. It returns an empty string
|
|
Packit |
95306a |
if $date is not valid.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Events_List>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$ref = Events_List($date);
|
|
Packit |
95306a |
$ref = Events_List($date,0 [,$flag]);
|
|
Packit |
95306a |
$ref = Events_List($date,$date1 [,$flag]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This returns a list of events. If $flag is not given, or is equal to 0,
|
|
Packit |
95306a |
the list (returned as a reference) is similar to the the list returned
|
|
Packit |
95306a |
by the Date::Manip::Date::list_events method with $format = "dates".
|
|
Packit |
95306a |
The only difference is that it is formatted slightly different to be
|
|
Packit |
95306a |
backward compatible with Date::Manip 5.xx.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The data from the list_events method is:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
( [DATE1, NAME1a, NAME1b, ...],
|
|
Packit |
95306a |
[DATE2, NAME2a, NAME2b, ...],
|
|
Packit |
95306a |
...
|
|
Packit |
95306a |
)
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The reference returned from Events_List (if $flag = 0) is:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
[ DATE1, [NAME1a, NAME1b, ...],
|
|
Packit |
95306a |
DATE2, [DATE2a, DATE2b, ...],
|
|
Packit |
95306a |
...
|
|
Packit |
95306a |
]
|
|
Packit |
95306a |
|
|
Packit |
95306a |
For example, if the following events are defined:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
2000-01-01 ; 2000-03-21 = Winter
|
|
Packit |
95306a |
2000-03-22 ; 2000-06-21 = Spring
|
|
Packit |
95306a |
2000-02-01 = Event1
|
|
Packit |
95306a |
2000-05-01 = Event2
|
|
Packit |
95306a |
2000-04-01-12:00:00 = Event3
|
|
Packit |
95306a |
|
|
Packit |
95306a |
the following examples illustrate the function:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Events_List("2000-04-01")
|
|
Packit |
95306a |
=> [ 2000040100:00:00, [ Spring ] ]
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Events_List("2000-04-01 12:30");
|
|
Packit |
95306a |
=> [ 2000040112:30:00, [ Spring, Event3 ] ]
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Events_List("2000-04-01",0);
|
|
Packit |
95306a |
=> [ 2000040100:00:00, [ Spring ],
|
|
Packit |
95306a |
2000040112:00:00, [ Spring, Event3 ],
|
|
Packit |
95306a |
2000040113:00:00, [ Spring ] ]
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Events_List("2000-03-15","2000-04-10");
|
|
Packit |
95306a |
=> [ 2000031500:00:00, [ Winter ],
|
|
Packit |
95306a |
2000032200:00:00, [ Spring ]
|
|
Packit |
95306a |
2000040112:00:00, [ Spring, Event3 ]
|
|
Packit |
95306a |
2000040113:00:00, [ Spring ] ]
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If $flag is 1, then a tally of the amount of time given to each event
|
|
Packit |
95306a |
is returned. Time for which two or more events apply is counted for
|
|
Packit |
95306a |
both.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Events_List("2000-03-15","2000-04-10",1);
|
|
Packit |
95306a |
=> { Event3 => +0:0:+0:0:1:0:0,
|
|
Packit |
95306a |
Spring => +0:0:+2:4:23:0:0,
|
|
Packit |
95306a |
Winter => +0:0:+1:0:0:0:0
|
|
Packit |
95306a |
}
|
|
Packit |
95306a |
|
|
Packit |
95306a |
When $flag is 2, a more complex tally with no event counted twice is
|
|
Packit |
95306a |
returned.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Events_List("2000-03-15","2000-04-10",2);
|
|
Packit |
95306a |
=> { Event3+Spring => +0:0:+0:0:1:0:0,
|
|
Packit |
95306a |
Spring => +0:0:+2:4:22:0:0,
|
|
Packit |
95306a |
Winter => +0:0:+1:0:0:0:0
|
|
Packit |
95306a |
}
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The hash contains one element for each combination of events.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In both of these cases, there may be a hash element with an empty
|
|
Packit |
95306a |
string as the key which contains the amount of time with no events
|
|
Packit |
95306a |
active.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_DayOfWeek>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$day = Date_DayOfWeek($m,$d,$y);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Returns the day of the week (1 for Monday, 7 for Sunday).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_SecsSince1970>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Returns the number of seconds since Jan 1, 1970 00:00 (negative if date is
|
|
Packit |
95306a |
earlier) in the current timezone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_SecsSince1970GMT>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Returns the number of seconds since Jan 1, 1970 00:00 GMT (negative if date
|
|
Packit |
95306a |
is earlier). Note that the date is still given in the current timezone, NOT
|
|
Packit |
95306a |
GMT.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_DaysSince1BC>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$days = Date_DaysSince1BC($m,$d,$y);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Returns the number of days since Dec 31, 1BC. This includes the year 0001.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_DayOfYear>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$day = Date_DayOfYear($m,$d,$y);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Returns the day of the year (1 to 366)
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_NthDayOfYear>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Returns the year, month, day, hour, minutes, and decimal seconds given
|
|
Packit |
95306a |
a floating point day of the year.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
All arguments must be numeric. $n must be greater than or equal to 1
|
|
Packit |
95306a |
and less than 366 on non-leap years and 367 on leap years.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
NOTE: When $n is a decimal number, the results are non-intuitive perhaps.
|
|
Packit |
95306a |
Day 1 is Jan 01 00:00. Day 2 is Jan 02 00:00. Intuitively, you
|
|
Packit |
95306a |
might think of day 1.5 as being 1.5 days after Jan 01 00:00, but this
|
|
Packit |
95306a |
would mean that Day 1.5 was Jan 02 12:00 (which is later than Day 2).
|
|
Packit |
95306a |
The best way to think of this function is a time line starting at 1 and
|
|
Packit |
95306a |
ending at 366 (in a non-leap year). In terms of a delta, think of $n
|
|
Packit |
95306a |
as the number of days after Dec 31 00:00 of the previous year.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_DaysInYear>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$days = Date_DaysInYear($y);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Returns the number of days in the year (365 or 366)
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_DaysInMonth>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$days = Date_DaysInMonth($m,$y);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Returns the number of days in the month.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_WeekOfYear>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$wkno = Date_WeekOfYear($m,$d,$y,$first);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Figure out week number. $first is the first day of the week which is
|
|
Packit |
95306a |
usually 1 (Monday) or 7 (Sunday), but could be any number between 1 and 7
|
|
Packit |
95306a |
in practice.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
NOTE: This routine should only be called in rare cases. Use UnixDate with
|
|
Packit |
95306a |
the %W, %U, %J, %L formats instead. This routine returns a week between 0
|
|
Packit |
95306a |
and 53 which must then be "fixed" to get into the ISO-8601 weeks from 1 to
|
|
Packit |
95306a |
53. A date which returns a week of 0 actually belongs to the last week of
|
|
Packit |
95306a |
the previous year. A date which returns a week of 53 may belong to the
|
|
Packit |
95306a |
first week of the next year.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_LeapYear>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$flag = Date_LeapYear($y);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Returns 1 if the argument is a leap year
|
|
Packit |
95306a |
Written by David Muir Sharnoff <muir@idiom.com>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_DaySuffix>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$day = Date_DaySuffix($d);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Add `st', `nd', `rd', `th' to a date (i.e. 1st, 22nd, 29th). Works for
|
|
Packit |
95306a |
international dates.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_TimeZone>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$tz = Date_TimeZone;
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This determines and returns the local time zone. If it is unable to determine
|
|
Packit |
95306a |
the local time zone, the following error occurs:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
ERROR: Date::Manip unable to determine Time Zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
See the Date::Manip::TZ documentation (DETERMINING THE LOCAL TIME ZONE) for
|
|
Packit |
95306a |
more information.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_ConvTZ>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_ConvTZ($date,$from,$to);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This converts a date (which MUST be in the format returned by ParseDate)
|
|
Packit |
95306a |
from one time zone to another.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$from and $to each default to the local time zone. If they are given,
|
|
Packit |
95306a |
they must be any time zone or alias understood by Date::Manip.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If an error occurs, an empty string is returned.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_NextWorkDay>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_NextWorkDay($date,$off [,$time]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Finds the day $off work days from now. If $time is passed in, we must also
|
|
Packit |
95306a |
take into account the time of day.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If $time is not passed in, day 0 is today (if today is a workday) or the
|
|
Packit |
95306a |
next work day if it isn't. In any case, the time of day is unaffected.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If $time is passed in, day 0 is now (if now is part of a workday) or the
|
|
Packit |
95306a |
start of the very next work day.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_PrevWorkDay>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_PrevWorkDay($date,$off [,$time]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Similar to Date_NextWorkDay.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Date_NearestWorkDay>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = Date_NearestWorkDay($date [,$tomorrowfirst]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This looks for the work day nearest to $date. If $date is a work day, it
|
|
Packit |
95306a |
is returned. Otherwise, it will look forward or backwards in time 1 day
|
|
Packit |
95306a |
at a time until a work day is found. If $tomorrowfirst is non-zero (or if
|
|
Packit |
95306a |
it is omitted and the config variable TomorrowFirst is non-zero), we look
|
|
Packit |
95306a |
to the future first. Otherwise, we look in the past first. In other words,
|
|
Packit |
95306a |
in a normal week, if $date is Wednesday, $date is returned. If $date is
|
|
Packit |
95306a |
Saturday, Friday is returned. If $date is Sunday, Monday is returned. If
|
|
Packit |
95306a |
Wednesday is a holiday, Thursday is returned if $tomorrowfirst is non-nil
|
|
Packit |
95306a |
or Tuesday otherwise.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
For all of the functions which return a date, the format of the returned
|
|
Packit |
95306a |
date is governed by the Printable config variable. If a date is returned,
|
|
Packit |
95306a |
it is in the local time zone, NOT the time zone the date was parsed in.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 SEE ALSO
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip - main module documentation
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 LICENSE
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This script is free software; you can redistribute it and/or
|
|
Packit |
95306a |
modify it under the same terms as Perl itself.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 AUTHOR
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Sullivan Beck (sbeck@cpan.org)
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=cut
|