Date-Calc
view release on metacpan or search on metacpan
lib/Date/Calc.pod view on Meta::CPAN
=head1 NAME
Date::Calc - Gregorian calendar date calculations
=head1 MOTTO
Keep it small, fast and simple
=head1 PREFACE
This package consists of a C library and a Perl module (which uses
the C library, internally) for all kinds of date calculations based
on the Gregorian calendar (the one used in all western countries today),
thereby complying with all relevant norms and standards: S<ISO/R 2015-1971>,
S<DIN 1355> and, to some extent, S<ISO 8601> (where applicable).
(See also http://www.engelschall.com/u/sb/download/Date-Calc/DIN1355/
for a scan of part of the "S<DIN 1355>" document (in German)).
The module of course handles year numbers of 2000 and above correctly
("Year 2000" or "Y2K" compliance) -- actually all year numbers from 1
to the largest positive integer representable on your system (which
is at least 32767) can be dealt with.
This is not true, however, for the import/export functions in this
package which are an interface to the internal POSIX date and time
functions of your system, which can only cover dates in the following
ranges:
01-Jan-1970 00:00:00 GMT .. 19-Jan-2038 03:14:07 GMT [Unix etc.]
01-Jan-1904 00:00:00 LT .. 06-Feb-2040 06:28:15 LT [MacOS Classic]
(LT = local time)
Note that this package projects the Gregorian calendar back until the
year S<1 A.D.> -- even though the Gregorian calendar was only adopted
in 1582, mostly by the Catholic European countries, in obedience to the
corresponding decree of Pope S<Gregory XIII> in that year.
Some (mainly protestant) countries continued to use the Julian calendar
(used until then) until as late as the beginning of the 20th century.
Finally, note that this package is not intended to do everything you could
ever imagine automagically for you; it is rather intended to serve as a
toolbox (in the best of UNIX spirit and traditions) which should, however,
always get you where you want to go.
See the section "RECIPES" at the bottom of this document for solutions
to common problems!
If nevertheless you can't figure out how to solve a particular problem,
please let me know! (See e-mail address at the end of this document.)
=head1 SYNOPSIS
use Date::Calc qw(
Days_in_Year
Days_in_Month
Weeks_in_Year
leap_year
check_date
check_time
check_business_date
Day_of_Year
Date_to_Days
Day_of_Week
Week_Number
Week_of_Year
Monday_of_Week
Nth_Weekday_of_Month_Year
Standard_to_Business
Business_to_Standard
Delta_Days
Delta_DHMS
Delta_YMD
Delta_YMDHMS
N_Delta_YMD
N_Delta_YMDHMS
Normalize_DHMS
Add_Delta_Days
Add_Delta_DHMS
Add_Delta_YM
Add_Delta_YMD
Add_Delta_YMDHMS
Add_N_Delta_YMD
Add_N_Delta_YMDHMS
System_Clock
Today
Now
Today_and_Now
This_Year
Gmtime
Localtime
Mktime
Timezone
Date_to_Time
Time_to_Date
Easter_Sunday
Decode_Month
Decode_Day_of_Week
lib/Date/Calc.pod view on Meta::CPAN
$string = English_Ordinal($number);
Calendar
$string = Calendar($year,$month[,$orthodox[,$lang]]);
Month_to_Text
$string = Month_to_Text($month[,$lang]);
Day_of_Week_to_Text
$string = Day_of_Week_to_Text($dow[,$lang]);
Day_of_Week_Abbreviation
$string = Day_of_Week_Abbreviation($dow[,$lang]);
Language_to_Text
$string = Language_to_Text($lang);
Language
$lang = Language();
Language($lang); # DEPRECATED
$oldlang = Language($newlang); # DEPRECATED
Languages
$max_lang = Languages();
Decode_Date_EU2
if (($year,$month,$day) = Decode_Date_EU2($string[,$lang]))
Decode_Date_US2
if (($year,$month,$day) = Decode_Date_US2($string[,$lang]))
Parse_Date
if (($year,$month,$day) = Parse_Date($string[,$lang]))
ISO_LC
$lower = ISO_LC($string);
ISO_UC
$upper = ISO_UC($string);
Version
$string = Date::Calc::Version();
=head1 IMPORTANT NOTES
(See the section "RECIPES" at the bottom of this document for
solutions to common problems!)
=over 2
=item *
"Year 2000" ("Y2K") compliance
The upper limit for any year number in this module is only given
by the size of the largest positive integer that can be represented
in a variable of the C type "int" on your system, which is at least
32767, according to the ANSI C standard (exceptions see below).
In order to simplify calculations, this module projects the gregorian
calendar back until the year S<1 A.D.> -- i.e., back B<BEYOND> the
year 1582 when this calendar was first decreed by the Catholic Pope
S<Gregory XIII>!
Therefore, B<BE SURE TO ALWAYS SPECIFY "1998" WHEN YOU MEAN "1998">,
for instance, and B<DO NOT WRITE "98" INSTEAD>, because this will
in fact perform a calculation based on the year "98" A.D. and
B<NOT> "1998"!
An exception from this rule are the functions which contain the
word "compress" in their names (which can only handle years between
1970 and 2069 and also accept the abbreviations "00" to "99"), and
the functions whose names begin with "Decode_Date_" (which translate
year numbers below 100 using a technique known as "moving window").
If you want to convert a two-digit year number into a full-fledged,
four-digit (at least for some years to come C<;-)>) year number,
use the two functions "Fixed_Window()" and "Moving_Window()"
(see their description further below).
Note also that the following import/export functions (which are
interfaces to the POSIX functions "time()", "gmtime()", "localtime()"
and "mktime()" or (the last two) substitutes for the BSD function
"timegm()" and the POSIX function "gmtime()") have a very limited
range of representable dates (in contrast to all other functions
in this package, which cover virtually any date including and
after S<January 1st 1 A.D.>):
System_Clock()
Today()
Now()
Today_and_Now()
This_Year()
Gmtime()
Localtime()
Mktime()
Timezone()
Date_to_Time()
Time_to_Date()
These functions can only deal with dates in the range from
S<01-Jan-1970 00:00:00 GMT> to S<19-Jan-2038 03:14:07 GMT>
(the latter limit is only authoritative on S<32 bit> systems,
however, and can (in principle, through a few code changes)
be extended somewhat C<:-)> on S<64 bit> systems).
On MacOS Classic, the valid range of dates is between
(both included) S<01-Jan-1904 00:00:00> (local time)
to S<06-Feb-2040 06:28:15> (local time).
Note further that the function "Easter_Sunday()" can only
be used for years in the range 1583 to 2299.
=item *
POSIX functions
Note that the following functions
Gmtime()
Localtime()
Mktime()
lib/Date/Calc.pod view on Meta::CPAN
I.e., "C<Days_in_Month(1998,1)>" returns "C<31>", "C<Days_in_Month(1998,2)>"
returns "C<28>", "C<Days_in_Month(2000,2)>" returns "C<29>",
"C<Days_in_Month(1998,3)>" returns "C<31>", and so on.
=item *
C<$weeks = Weeks_in_Year($year);>
This function returns the number of weeks in the given year "C<$year>",
i.e., either "C<52>" or "C<53>".
=item *
C<if (leap_year($year))>
This function returns "true" ("C<1>") if the given year "C<$year>" is
a leap year and "false" ("C<0>") otherwise.
=item *
C<if (check_date($year,$month,$day))>
This function returns "true" ("C<1>") if the given three numerical
values "C<$year>", "C<$month>" and "C<$day>" constitute a valid date,
and "false" ("C<0>") otherwise.
=item *
C<if (check_time($hour,$min,$sec))>
This function returns "true" ("C<1>") if the given three numerical
values "C<$hour>", "C<$min>" and "C<$sec>" constitute a valid time
(C<0 E<lt>= $hour E<lt> 24>, C<0 E<lt>= $min E<lt> 60> and
C<0 E<lt>= $sec E<lt> 60>), and "false" ("C<0>") otherwise.
=item *
C<if (check_business_date($year,$week,$dow))>
This function returns "true" ("C<1>") if the given three numerical
values "C<$year>", "C<$week>" and "C<$dow>" constitute a valid date
in business format, and "false" ("C<0>") otherwise.
B<Beware> that this function does B<NOT> compute whether a given date
is a business day (i.e., Monday to Friday)!
To do so, use "C<(Day_of_Week($year,$month,$day) E<lt> 6)>" instead.
=item *
C<$doy = Day_of_Year($year,$month,$day);>
This function returns the (relative) number of the day of the given date
in the given year.
E.g., "C<Day_of_Year($year,1,1)>" returns "C<1>",
"C<Day_of_Year($year,2,1)>" returns "C<32>", and
"C<Day_of_Year($year,12,31)>" returns either "C<365>" or "C<366>".
The day of year is sometimes also referred to as the Julian day (or date),
although it has nothing to do with the Julian calendar, the calendar which
was used before the Gregorian calendar.
In order to convert the number returned by this function back into a
date, use the function "C<Add_Delta_Days()>" (described further below),
as follows:
$doy = Day_of_Year($year,$month,$day);
($year,$month,$day) = Add_Delta_Days($year,1,1, $doy - 1);
=item *
C<$days = Date_to_Days($year,$month,$day);>
This function returns the (absolute) number of the day of the given date,
where counting starts at the 1st of January of the year S<1 A.D.>
I.e., "C<Date_to_Days(1,1,1)>" returns "C<1>", "C<Date_to_Days(1,12,31)>"
returns "C<365>", "C<Date_to_Days(2,1,1)>" returns "C<366>",
"C<Date_to_Days(1998,5,1)>" returns "C<729510>", and so on.
This is sometimes also referred to (not quite correctly) as the Julian
date (or day). This may cause confusion, because also the number of the
day in a year (from 1 to 365 or 366) is frequently called the "Julian day".
More confusing still, this has nothing to do with the Julian calendar,
which was used B<BEFORE> the Gregorian calendar.
The Julian calendar was named after famous Julius Caesar, who had
instituted it in Roman times. The Julian calendar is less precise than
the Gregorian calendar because it has too many leap years compared to
the true mean length of a year (but the Gregorian calendar also still
has one day too much every 5000 years). Anyway, the Julian calendar was
better than what existed before, because rulers had often changed the
calendar used until then in arbitrary ways, in order to lengthen their
own reign, for instance.
In order to convert the number returned by this function back into
a date, use the function "C<Add_Delta_Days()>" (described further
below), as follows:
$days = Date_to_Days($year,$month,$day);
($year,$month,$day) = Add_Delta_Days(1,1,1, $days - 1);
=item *
C<$dow = Day_of_Week($year,$month,$day);>
This function returns the number of the day of week of the given date.
The function returns "C<1>" for Monday, "C<2>" for Tuesday and so on
until "C<7>" for Sunday.
Note that in the Hebrew calendar (on which the Christian calendar is based),
the week starts with Sunday and ends with the Sabbath or Saturday (where
according to the Genesis (as described in the Bible) the Lord rested from
creating the world).
In medieval times, Catholic Popes have decreed the Sunday to be the official
day of rest, in order to dissociate the Christian from the Hebrew belief.
It appears that this actually happened with the Emperor Constantin, who
converted to Christianity but still worshipped the Sun god and therefore
moved the Christian sabbath to the day of the Sun.
Nowadays, the Sunday B<AND> the Saturday are commonly considered (and
used as) days of rest, usually referred to as the "week-end".
Consistent with this practice, current norms and standards (such as
S<ISO/R 2015-1971>, S<DIN 1355> and S<ISO 8601>) define the Monday
as the first day of the week.
=item *
C<$week = Week_Number($year,$month,$day);>
This function returns the number of the week the given date lies in.
If the given date lies in the B<LAST> week of the B<PREVIOUS> year,
"C<0>" is returned.
If the given date lies in the B<FIRST> week of the B<NEXT> year,
"C<Weeks_in_Year($year) + 1>" is returned.
=item *
C<($week,$year) = Week_of_Year($year,$month,$day);>
This function returns the number of the week the given date lies in,
as well as the year that week belongs to.
I.e., if the given date lies in the B<LAST> week of the B<PREVIOUS> year,
"C<(Weeks_in_Year($year-1), $year-1)>" is returned.
If the given date lies in the B<FIRST> week of the B<NEXT> year,
"C<(1, $year+1)>" is returned.
Otherwise, "C<(Week_Number($year,$month,$day), $year)>" is returned.
=item *
C<$week = Week_of_Year($year,$month,$day);>
In scalar context, this function returns just the week number. This
allows you to write "C<$week = Week_of_Year($year,$month,$day);>"
instead of "C<($week) = Week_of_Year($year,$month,$day);>" (note
the parentheses around "C<$week>").
If the given date lies in the B<LAST> week of the B<PREVIOUS> year,
"C<Weeks_in_Year($year-1)>" is returned.
If the given date lies in the B<FIRST> week of the B<NEXT> year,
"C<1>" is returned.
lib/Date/Calc.pod view on Meta::CPAN
in the given or currently selected language, and "yyyy" is the number of
the year in full length.
The exact format of the output string depends on the given or currently
selected language. In the original distribution of this package, these
formats are defined as follows:
1 English : "Wwwwww, Mmmmmm ddth yyyy"
2 French : "Wwwwww dd mmmmmm yyyy"
3 German : "Wwwwww, den dd. Mmmmmm yyyy"
4 Spanish : "Wwwwww, dd de mmmmmm de yyyy"
5 Portuguese : "Wwwwww, dia dd de mmmmmm de yyyy"
6 Dutch : "Wwwwww, dd mmmmmm yyyy"
7 Italian : "Wwwwww, dd Mmmmmm yyyy"
8 Norwegian : "wwwwww, dd. mmmmmm yyyy"
9 Swedish : "wwwwww, dd mmmmmm yyyy"
10 Danish : "wwwwww, dd. mmmmmm yyyy"
11 Finnish : "wwwwww, dd. mmmmmmta yyyy"
12 Hungarian : "dd. Mmmmmm yyyy., wwwwww"
13 Polish : "Wwwwww, dd Mmmmmm yyyy"
14 Romanian : "Wwwwww dd Mmmmmm yyyy"
(You can change these formats in the file "DateCalc.c" before
building this module in order to suit your personal preferences.)
If the given input values do not constitute a valid date, a fatal
"not a valid date" error occurs.
In order to capitalize the day of week at the beginning of the string
in Norwegian, use "C<ucfirst(Date_to_Text_Long($year,$month,$day,8));>".
(See the section "RECIPES" near the end of this document for
an example on how to print dates in any format you like.)
=item *
C<$string = English_Ordinal($number);>
This function returns a string containing the (english) abbreviation
of the ordinal number for the given (cardinal) number "C<$number>".
I.e.,
0 => '0th' 10 => '10th' 20 => '20th'
1 => '1st' 11 => '11th' 21 => '21st'
2 => '2nd' 12 => '12th' 22 => '22nd'
3 => '3rd' 13 => '13th' 23 => '23rd'
4 => '4th' 14 => '14th' 24 => '24th'
5 => '5th' 15 => '15th' 25 => '25th'
6 => '6th' 16 => '16th' 26 => '26th'
7 => '7th' 17 => '17th' 27 => '27th'
8 => '8th' 18 => '18th' 28 => '28th'
9 => '9th' 19 => '19th' 29 => '29th'
etc.
=item *
C<$string = Calendar($year,$month[,$orthodox[,$lang]]);>
This function returns a calendar of the given month in the given year
(somewhat similar to the UNIX "C<cal>" command), in the given or currently
selected language (see further below for details about the multi-language
support of this package).
Example:
print Calendar(1998,5);
This will print:
May 1998
Mon Tue Wed Thu Fri Sat Sun
1 2 3
4 5 6 7 8 9 10
11 12 13 14 15 16 17
18 19 20 21 22 23 24
25 26 27 28 29 30 31
If the optional boolean parameter "C<$orthodox>" is given and true,
the calendar starts on Sunday instead of Monday.
=item *
C<$string = Month_to_Text($month[,$lang]);>
This function returns the name of the given month in the given or currently
selected language (see further below for details about the multi-language
support of this package).
If the given month lies outside of the valid range from "C<1>" to "C<12>",
a fatal "month out of range" error will occur.
=item *
C<$string = Day_of_Week_to_Text($dow[,$lang]);>
This function returns the name of the given day of week in the given or
currently selected language (see further below for details about the
multi-language support of this package).
If the given day of week lies outside of the valid range from "C<1>" to "C<7>",
a fatal "day of week out of range" error will occur.
=item *
C<$string = Day_of_Week_Abbreviation($dow[,$lang]);>
This function returns the special abbreviation of the name of the given
day of week, B<IF> such special abbreviations have been defined for the
given or currently selected language (see further below for details
about the multi-language support of this package).
(In the original distribution of this package, this was only true for
Portuguese. Starting with version 5.1, abbreviations for Polish have
also been introduced. Starting with version 5.7, the abbreviations for
Portuguese have been disabled. So Polish is currently the only language
to define such special abbreviations.)
If not, the first three letters of the name of the day of week in the
given or currently selected language are returned instead.
If the given day of week lies outside of the valid range from "C<1>"
to "C<7>", a fatal "day of week out of range" error will occur.
Currently, this table of special abbreviations is only used by the
functions "C<Date_to_Text()>" and "C<Calendar()>", internally.
=item *
C<$string = Language_to_Text($lang);>
This function returns the name of any language supported by this package
when the internal number representing that language is given as input.
The original distribution supports the following fourteen languages:
1 ==> English (default)
2 ==> Français (French)
3 ==> Deutsch (German)
4 ==> Español (Spanish)
lib/Date/Calc.pod view on Meta::CPAN
This will print something like:
Today is: Sun 12-Apr-1998
Last Saturday was: Sat 11-Apr-1998
Next Saturday will be: Sat 18-Apr-1998
=item 10)
How can I calculate the last business day (payday!) of a month?
Solution #1 (holidays B<NOT> taken into account):
use Date::Calc qw( Days_in_Month Day_of_Week Add_Delta_Days );
$day = Days_in_Month($year,$month);
$dow = Day_of_Week($year,$month,$day);
if ($dow > 5)
{
($year,$month,$day) =
Add_Delta_Days($year,$month,$day, 5-$dow);
}
Solution #2 (holidays taken into account):
This solution expects a multi-dimensional array "C<@holiday>", which
contains all holidays, as follows: "C<$holiday[$year][$month][$day] = 1;>".
(See the description of the function "C<Easter_Sunday()>" further above for
how to calculate the moving (variable) christian feast days!)
Days which are not holidays remain undefined or should have a value of zero
in this array.
use Date::Calc qw( Days_in_Month Add_Delta_Days Day_of_Week );
$day = Days_in_Month($year,$month);
while (1)
{
while ($holiday[$year][$month][$day])
{
($year,$month,$day) =
Add_Delta_Days($year,$month,$day, -1);
}
$dow = Day_of_Week($year,$month,$day);
if ($dow > 5)
{
($year,$month,$day) =
Add_Delta_Days($year,$month,$day, 5-$dow);
}
else { last; }
}
Solution #3 (holidays taken into account, more comfortable,
but requires Date::Calendar(3) and Date::Calc::Object(3)):
use Date::Calc::Object qw( Today Add_Delta_YM Date_to_Text_Long );
use Date::Calendar::Profiles qw($Profiles);
use Date::Calendar;
$calendar = Date::Calendar->new( $Profiles->{'DE-BW'} );
@today = Today();
@nextmonth = Add_Delta_YM(@today[0,1],1, 0,1);
$workaround = $calendar->add_delta_workdays(@nextmonth,+1);
$payday = $calendar->add_delta_workdays($workaround,-2);
print "Pay day = ", Date_to_Text_Long($payday->date()), "\n";
The "workaround" is necessary due to a bug in the method
"add_delta_workdays()" when adding a negative number of
workdays.
=item 11)
How do I convert a MS Visual Basic "DATETIME" value into its date
and time constituents?
use Date::Calc qw( Add_Delta_DHMS Date_to_Text );
$datetime = "35883.121653";
($Dd,$Dh,$Dm,$Ds) = ($datetime =~ /^(\d+)\.(\d\d)(\d\d)(\d\d)$/);
($year,$month,$day, $hour,$min,$sec) =
Add_Delta_DHMS(1900,1,1, 0,0,0, $Dd,$Dh,$Dm,$Ds);
printf("The given date is %s %02d:%02d:%02d\n",
Date_to_Text($year,$month,$day), $hour, $min, $sec);
This prints:
The given date is Tue 31-Mar-1998 12:16:53
Since I do not have or use Visual Basic, I can't guarantee that
the number format assumed here is really the one used by Visual
Basic - but you get the general idea. C<:-)>
Moreover, consider the following:
Morten Sickel <Morten.Sickel@nrpa.no> wrote:
I discovered a bug in Excel (2000): Excel thinks that 1900 was
a leap year. Users should use 31-Dec-1899 as the date to add
an Excel date value to in order to get the correct date.
I found out on the web that this bug originated in Lotus 123,
which made 29-Feb-1900 an "industrial standard". MS chose to
keep the bug in order to be compatible with Lotus 123. But
they have not mentioned anything about it in the help files.
=item 12)
How can I send a reminder to members of a group on the day
before a meeting which occurs every first Friday of a month?
use Date::Calc qw( Today Date_to_Days Add_Delta_YMD
Nth_Weekday_of_Month_Year );
($year,$month,$day) = Today();
$tomorrow = Date_to_Days($year,$month,$day) + 1;
$dow = 5; # 5 = Friday
$n = 1; # 1 = First of that day of week
lib/Date/Calc.pod view on Meta::CPAN
#!perl
use strict;
use Date::Calc qw(Today Delta_YMD Add_Delta_YM Delta_Days Date_to_Text);
my($sign,$delta);
my $today = [Today()];
my $target = [2005,1,1];
if (Delta_Days(@$today,@$target) < 0)
{
$sign = "since";
$delta = Normalize_Delta_YMD($target,$today);
}
else
{
$sign = "until";
$delta = Normalize_Delta_YMD($today,$target);
}
print "Today is ", Date_to_Text(@$today), "\n";
printf
(
"%d year%s, %d month%s, %d day%s %s %s\n",
$delta->[0], (($delta->[0]==1)?'':'s'),
$delta->[1], (($delta->[1]==1)?'':'s'),
$delta->[2], (($delta->[2]==1)?'':'s'),
$sign,
Date_to_Text(@$target)
);
sub Normalize_Delta_YMD
{
my($date1,$date2) = @_;
my(@delta);
@delta = Delta_YMD(@$date1,@$date2);
while ($delta[1] < 0 or $delta[2] < 0)
{
if ($delta[1] < 0) { $delta[0]--; $delta[1] += 12; }
if ($delta[2] < 0)
{
$delta[1]--;
$delta[2] = Delta_Days(Add_Delta_YM(@$date1,@delta[0,1]),@$date2);
}
}
return \@delta;
}
Note that for normalizing just a time vector, you can use the built-in
function "Normalize_DHMS()". However, this will yield either all positive
B<OR> all negative values, B<NOT> all positive values as above.
=back
=head1 SEE ALSO
Date::Calc::Util(3), Date::Calc::Object(3),
Date::Calendar(3), Date::Calendar::Year(3),
Date::Calendar::Profiles(3).
"The Calendar FAQ":
http://www.tondering.dk/claus/calendar.html
by Claus Tondering <claus@tondering.dk>
=head1 BEWARE
When you are using the (deprecated) function "Language()", the language
setting is stored in a global variable.
This may cause conflicts between threads or modules running concurrently.
Therefore, in order to avoid such conflicts, NEVER use the function
"Language()", but ALWAYS pass a language parameter to the functions
which are language-dependent.
=head1 VERSION
This man page documents "Date::Calc" version 6.4.
=head1 AUTHOR
Steffen Beyer
mailto:STBEY@cpan.org
http://www.engelschall.com/u/sb/download/
=head1 COPYRIGHT
Copyright (c) 1995 - 2015 by Steffen Beyer. All rights reserved.
=head1 LICENSE
This package is free software; you can use, modify and redistribute
it under the same terms as Perl itself, i.e., at your option, under
the terms either of the "Artistic License" or the "GNU General Public
License".
The C library at the core of the module "Date::Calc::XS" can, at your
discretion, also be used, modified and redistributed under the terms
of the "GNU Library General Public License".
Please refer to the files "Artistic.txt", "GNU_GPL.txt" and
"GNU_LGPL.txt" in the "license" subdirectory of this distribution
for any details!
=head1 DISCLAIMER
This package is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the "GNU General Public License" for more details.
( run in 0.630 second using v1.01-cache-2.11-cpan-0d23b851a93 )