info > Date::Calc

🏷️ NAME

Date::Calc - Gregorian calendar date calculations

🚀 Quick Reference

Use CaseCommandDescription
Days in monthDays_in_Month($year,$month)Returns number of days in given month
Leap year checkleap_year($year)True if leap year, else false
Day of weekDay_of_Week($year,$month,$day)1 (Mon) .. 7 (Sun)
Current dateToday()Returns current (year,month,day)
Date differenceDelta_Days($y1,$m1,$d1, $y2,$m2,$d2)Signed days difference
Add daysAdd_Delta_Days($y,$m,$d, $offset)Add a days offset
ISO week numberWeek_of_Year($year,$month,$day)Returns (week, year)
Easter SundayEaster_Sunday($year)Date of Easter (1583-2299)
Date to textDate_to_Text($year,$month,$day[, $lang])Formatted date string

📜 MOTTO

Keep it small, fast and simple

📖 PREFACE

This package consists of a C library and a Perl module for all kinds of date calculations based on the Gregorian calendar, complying with ISO/R2015-1971, DIN1355 and partially ISO8601.

Year numbers from 1 up to the largest positive integer (≥32767) are supported, except for system-dependent POSIX import/export functions which are limited to roughly 1970–2038 (Unix) or 1904–2040 (MacOS Classic).

The Gregorian calendar is projected back to 1 A.D., even though it was introduced in 1582.

This is a toolbox – see recipes at the end for common solutions.

📝 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
    Decode_Language
    Decode_Date_EU
    Decode_Date_US
    Fixed_Window
    Moving_Window
    Compress
    Uncompress
    check_compressed
    Compressed_to_Text
    Date_to_Text
    Date_to_Text_Long
    English_Ordinal
    Calendar
    Month_to_Text
    Day_of_Week_to_Text
    Day_of_Week_Abbreviation
    Language_to_Text
    Language
    Languages
    Decode_Date_EU2
    Decode_Date_US2
    Parse_Date
    ISO_LC
    ISO_UC
);

use Date::Calc qw(:all);

Function signatures:

$days = Days_in_Year($year,$month);
$days = Days_in_Month($year,$month);
$weeks = Weeks_in_Year($year);
if (leap_year($year)) ...
if (check_date($year,$month,$day)) ...
if (check_time($hour,$min,$sec)) ...
if (check_business_date($year,$week,$dow)) ...
$doy = Day_of_Year($year,$month,$day);
$days = Date_to_Days($year,$month,$day);
$dow = Day_of_Week($year,$month,$day);
$week = Week_Number($year,$month,$day);                # DEPRECATED
($week,$year) = Week_of_Year($year,$month,$day);       # RECOMMENDED
$week = Week_of_Year($year,$month,$day);               # DANGEROUS
($year,$month,$day) = Monday_of_Week($week,$year);
if (($year,$month,$day) = Nth_Weekday_of_Month_Year($year,$month,$dow,$n)) ...
($year,$week,$dow) = Standard_to_Business($year,$month,$day);
($year,$month,$day) = Business_to_Standard($year,$week,$dow);
$Dd = Delta_Days($year1,$month1,$day1, $year2,$month2,$day2);
($Dd,$Dh,$Dm,$Ds) = Delta_DHMS($year1,$month1,$day1, $hour1,$min1,$sec1, $year2,$month2,$day2, $hour2,$min2,$sec2);
($Dy,$Dm,$Dd) = Delta_YMD($year1,$month1,$day1, $year2,$month2,$day2);
($D_y,$D_m,$D_d, $Dh,$Dm,$Ds) = Delta_YMDHMS($year1,$month1,$day1, $hour1,$min1,$sec1, $year2,$month2,$day2, $hour2,$min2,$sec2);
($Dy,$Dm,$Dd) = N_Delta_YMD($year1,$month1,$day1, $year2,$month2,$day2);
($D_y,$D_m,$D_d, $Dhh,$Dmm,$Dss) = N_Delta_YMDHMS($year1,$month1,$day1, $hour1,$min1,$sec1, $year2,$month2,$day2, $hour2,$min2,$sec2);
($Dd,$Dh,$Dm,$Ds) = Normalize_DHMS($Dd,$Dh,$Dm,$Ds);
($year,$month,$day) = Add_Delta_Days($year,$month,$day, $Dd);
($year,$month,$day, $hour,$min,$sec) = Add_Delta_DHMS($year,$month,$day, $hour,$min,$sec, $Dd,$Dh,$Dm,$Ds);
($year,$month,$day) = Add_Delta_YM($year,$month,$day, $Dy,$Dm);
($year,$month,$day) = Add_Delta_YMD($year,$month,$day, $Dy,$Dm,$Dd);
($year,$month,$day, $hour,$min,$sec) = Add_Delta_YMDHMS($year,$month,$day, $hour,$min,$sec, $D_y,$D_m,$D_d, $Dh,$Dm,$Ds);
($year,$month,$day) = Add_N_Delta_YMD($year,$month,$day, $Dy,$Dm,$Dd);
($year,$month,$day, $hour,$min,$sec) = Add_N_Delta_YMDHMS($year,$month,$day, $hour,$min,$sec, $D_y,$D_m,$D_d, $Dhh,$Dmm,$Dss);
($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = System_Clock([$gmt]);
($year,$month,$day) = Today([$gmt]);
($hour,$min,$sec) = Now([$gmt]);
($year,$month,$day, $hour,$min,$sec) = Today_and_Now([$gmt]);
$year = This_Year([$gmt]);
($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = Gmtime([time]);
($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = Localtime([time]);
$time = Mktime($year,$month,$day, $hour,$min,$sec);
($D_y,$D_m,$D_d, $Dh,$Dm,$Ds, $dst) = Timezone([time]);
$time = Date_to_Time($year,$month,$day, $hour,$min,$sec);
($year,$month,$day, $hour,$min,$sec) = Time_to_Date([time]);
($year,$month,$day) = Easter_Sunday($year);
if ($month = Decode_Month($string[,$lang])) ...
if ($dow = Decode_Day_of_Week($string[,$lang])) ...
if ($lang = Decode_Language($string)) ...
if (($year,$month,$day) = Decode_Date_EU($string[,$lang])) ...
if (($year,$month,$day) = Decode_Date_US($string[,$lang])) ...
$year = Fixed_Window($yy);
$year = Moving_Window($yy);
$date = Compress($year,$month,$day);
if (($century,$year,$month,$day) = Uncompress($date)) ...
if (check_compressed($date)) ...
$string = Compressed_to_Text($date[,$lang]);
$string = Date_to_Text($year,$month,$day[,$lang]);
$string = Date_to_Text_Long($year,$month,$day[,$lang]);
$string = English_Ordinal($number);
$string = Calendar($year,$month[,$orthodox[,$lang]]);
$string = Month_to_Text($month[,$lang]);
$string = Day_of_Week_to_Text($dow[,$lang]);
$string = Day_of_Week_Abbreviation($dow[,$lang]);
$string = Language_to_Text($lang);
$lang = Language();
Language($lang);               # DEPRECATED
$oldlang = Language($newlang); # DEPRECATED
$max_lang = Languages();
if (($year,$month,$day) = Decode_Date_EU2($string[,$lang])) ...
if (($year,$month,$day) = Decode_Date_US2($string[,$lang])) ...
if (($year,$month,$day) = Parse_Date($string[,$lang])) ...
$lower = ISO_LC($string);
$upper = ISO_UC($string);
$string = Date::Calc::Version();

⚠️ IMPORTANT NOTES

📘 DESCRIPTION

🍳 RECIPES

  1. Compare two dates: 
    if (Date_to_Days($y1,$m1,$d1) > Date_to_Days($y2,$m2,$d2)) ...
  2. Check if a date lies in a range: 
    $lower = Date_to_Days($y1,$m1,$d1);
$upper = Date_to_Days($y2,$m2,$d2);
$date  = Date_to_Days($y,$m,$d);
if ($date >= $lower && $date <= $upper) { ... }
  3. Check if two date/times are within 12 hours: 
    @d2 = (Date_to_Days(@date2[0..2]), ($date2[3]*60+$date2[4])*60+$date2[5]);
@d3 = (Date_to_Days(@date3[0..2]), ($date3[3]*60+$date3[4])*60+$date3[5]);
# then compare...
  4. Verify age (over 18): 
    if (($year1+18 <=> $year2 || $month1 <=> $month2 || $day1 <=> $day2) <= 0) { ... }
  5. Week of month: 
    $week = int(($day + Day_of_Week($year,$month,1) - 2) / 7) + 1;
  6. Is a date the 1st/2nd/3rd… weekday of the month? 
    $n = int(Delta_Days(
    Nth_Weekday_of_Month_Year($year,$month,DOW,1),
    $date)/7)+1;
  7. Find Wednesday of the current week: 
    $dow_today = Day_of_Week(@today);
@wed = Add_Delta_Days(@today, 3 - $dow_today);
  8. Add a week offset to a business date: 
    @temp = Business_to_Standard($year,$week,$dow);
@temp = Add_Delta_Days(@temp, $weeks * 7);
($year,$week,$dow) = Standard_to_Business(@temp);
  9. Last / next Saturday: 
    $dow = Day_of_Week(@today);
if (6 == $dow) { @prev = Add_Delta_Days(@today,-7); @next = Add_Delta_Days(@today,7); }
elsif (6 > $dow) { @next = Add_Delta_Days(@today, 6-$dow); @prev = Add_Delta_Days(@next,-7); }
else { @prev = Add_Delta_Days(@today, 6-$dow); @next = Add_Delta_Days(@prev,7); }
  10. Last business day of a month (no holidays): 
    $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); }
  11. Convert Visual Basic DATETIME: 
    ($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);
  12. Send reminder day before first Friday of month: 
    $tomorrow = Date_to_Days(Today()) + 1;
$meeting_this = Date_to_Days(Nth_Weekday_of_Month_Year($y,$m,5,1));
$meeting_next = Date_to_Days(Nth_Weekday_of_Month_Year($y,$m+1,5,1));
if ($tomorrow == $meeting_this || $tomorrow == $meeting_next) { ... }
  13. Print date in a custom format: 
    printf("%.3s %02d-%.3s-%d\n",
    Day_of_Week_to_Text(Day_of_Week($y,$m,$d)),
    $d, Month_to_Text($m), $y);
  14. Iterate through a date range: 
    $j = Delta_Days(@start,@stop);
for $i (0..$j) { @date = Add_Delta_Days(@start,$i); ... }
  15. Create a list of dates in a range: 
    sub date_range {
    my(@date)=@_[0..2];
    my $i = Delta_Days(@_);
    my @list;
    while ($i-- >= 0) { push @list,[@date]; @date = Add_Delta_Days(@date,1) if $i>=0; }
    return @list;
}
  16. Difference in work days (no weekends, no holidays): 
    sub Delta_Business_Days {
    my($minus,$result,$dow1,$dow2,$diff);
    $result = Delta_Days(@date1,@date2);
    if ($result != 0) {
        if ($result < 0) { $minus=1; $result=-$result; $dow1=Day_of_Week(@date2); $dow2=Day_of_Week(@date1); }
        else { $dow1=Day_of_Week(@date1); $dow2=Day_of_Week(@date2); }
        $diff = $dow2 - $dow1;
        $temp = $result;
        if ($diff != 0) {
            if ($diff < 0) { $diff += 7; }
            $temp -= $diff;
            $dow1 += $diff;
            if ($dow1 > 6) { $result--; if ($dow1 > 7) { $result--; } }
        }
        if ($temp != 0) { $result -= ($temp/7)*2; }
    }
    return $minus ? -$result : $result;
}
  17. Normalize `Delta_YMDHMS` output to all positive:

    Use N_Delta_YMDHMS() instead. Older workaround shown here is obsolete.

🔗 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

⚠️ BEWARE

The deprecated function Language() uses a global variable. To avoid thread or module conflicts, always pass an explicit language parameter to language‑dependent functions.

🔢 VERSION

This man page documents Date::Calc version 6.4.

✍️ AUTHOR

Steffen Beyer
STBEY@cpan.org
http://www.engelschall.com/u/sb/download/

©️ COPYRIGHT

Copyright (c) 1995 - 2015 by Steffen Beyer. All rights reserved.

📜 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 of the "Artistic License" or the "GNU General Public License". The C library at the core of Date::Calc::XS can also be used under the "GNU Library General Public License".

See the files Artistic.txt, GNU_GPL.txt and GNU_LGPL.txt in the license subdirectory of this distribution.

⚠️ 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.

Date::Calc □✕
🏷️ NAME 🚀 Quick Reference 📜 MOTTO 📖 PREFACE 📝 SYNOPSIS ⚠️ IMPORTANT NOTES 📘 DESCRIPTION 🍳 RECIPES 🔗 SEE ALSO ⚠️ BEWARE 🔢 VERSION ✍️ AUTHOR ©️ COPYRIGHT 📜 LICENSE ⚠️ DISCLAIMER

Generated by phpman v4.9.26-5-g7740029 Author: Che Dong Under GNU General Public License
2026-08-25 05:20 @216.73.216.179
CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
Valid XHTML 1.0 Transitional!Valid CSS!