info > Date::Manip::DM5

📛 NAME

Date::Manip::DM5 – Date manipulation routines

🚀 Quick Reference

Use Case	Command	Description
Initialize / configure	Date_Init("VAR=VAL",...);	Set language, date format, time zone, holidays, etc.
Parse a human date	$date = ParseDate($string);	Convert text like "tomorrow at noon" into internal form.
Format a date for display	@date = UnixDate($date,@format);	Emulate date(1) formats (%Y, %m, %d, …).
Parse a time interval	$delta = ParseDateDelta($string);	Convert "+2 days 3 hours" into a delta structure.
Format a delta	$str = Delta_Format($delta,$dec,@format);	Express delta in hours, minutes, etc.
Define a recurring event	$recur = ParseRecur($string,...);	Create recurrence rules like "every 2nd Tuesday".
Compare two dates	$flag = Date_Cmp($date1,$date2);	Compare dates, respecting time zones.
Date arithmetic	$d = DateCalc($d1,$d2 [,$errref]);	Add/subtract dates and deltas, business mode possible.
Set a time component	$date = Date_SetTime($date,$hr,$min,$sec);	Change the time portion of a date.
Find previous/following	$date = Date_GetPrev($date,$dow,...);	Locate prior occurrence of a day or time.
Check holiday	$name = Date_IsHoliday($date);	Returns holiday name if date is a holiday.
Convert between time zones	$date = Date_ConvTZ($date,$from,$to);	Shift date between time zone definitions.
Work day handling	$flag = Date_IsWorkDay($date);	Test if date is a business/work day.

📝 SYNOPSIS

All public routines check that Date_Init has been called, and call it automatically if not. The internal routines (listed later) are faster but require explicit Date_Init and little error checking.

use Date::Manip;

$version = DateManipVersion;

Date_Init();
Date_Init("VAR=VAL","VAR=VAL",...);
@list = Date_Init();
@list = Date_Init("VAR=VAL","VAR=VAL",...);

$date = ParseDate(\@args);
$date = ParseDate($string);
$date = ParseDate(\$string);

@date = UnixDate($date,@format);
$date = UnixDate($date,@format);

$delta = ParseDateDelta(\@args);
$delta = ParseDateDelta($string);
$delta = ParseDateDelta(\$string);

@str = Delta_Format($delta,$dec,@format);
$str = Delta_Format($delta,$dec,@format);

$recur = ParseRecur($string,$base,$date0,$date1,$flags);
@dates = ParseRecur($string,$base,$date0,$date1,$flags);

$flag = Date_Cmp($date1,$date2);

$d = DateCalc($d1,$d2 [,$errref] [,$del]);

$date = Date_SetTime($date,$hr,$min,$sec);
$date = Date_SetTime($date,$time);

$date = Date_SetDateField($date,$field,$val [,$nocheck]);

$date = Date_GetPrev($date,$dow,$today,$hr,$min,$sec);
$date = Date_GetPrev($date,$dow,$today,$time);

$date = Date_GetNext($date,$dow,$today,$hr,$min,$sec);
$date = Date_GetNext($date,$dow,$today,$time);

$name = Date_IsHoliday($date);

$listref = Events_List($date);
$listref = Events_List($date0,$date1);

$date = Date_ConvTZ($date);
$date = Date_ConvTZ($date,$from);
$date = Date_ConvTZ($date,"",$to);
$date = Date_ConvTZ($date,$from,$to);

$flag = Date_IsWorkDay($date [,$flag]);

$date = Date_NextWorkDay($date,$off [,$flag]);

$date = Date_PrevWorkDay($date,$off [,$flag]);

$date = Date_NearestWorkDay($date [,$tomorrowfirst]);

# Internal (fast) routines – require explicit Date_Init:

$day = Date_DayOfWeek($m,$d,$y);
$secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
$secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
$days = Date_DaysSince1BC($m,$d,$y);
$day = Date_DayOfYear($m,$d,$y);
($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
$days = Date_DaysInYear($y);
$days = Date_DaysInMonth($m,$y);
$wkno = Date_WeekOfYear($m,$d,$y,$first);
$flag = Date_LeapYear($y);
$day = Date_DaySuffix($d);
$tz = Date_TimeZone();

📚 ROUTINES

🔹 Date_Init

Date_Init();
Date_Init("VAR=VAL","VAR=VAL",...);
@list = Date_Init();
@list = Date_Init("VAR=VAL","VAR=VAL",...);

Normally, Date_Init is called automatically by other routines. Call explicitly only to change configuration. Strings are of the form "VAR=VAL". In list context, returns current config values (suitable for later restoration).

Example – switch to French with non‑US date order:

Date_Init("Language=French","DateFormat=non-US");

To restore state later, prepend "EraseHolidays=1" if needed.

📅 ParseDate

$date = ParseDate(\@args);
$date = ParseDate($string);
$date = ParseDate(\$string);

Extracts a date from an array reference (shifts used elements) or from a string. Useful for processing command‑line arguments. The core parsing is done by ParseDateString.

🔍 ParseDateString

$date = ParseDateString($string);

Parses a single string into an internal date. Handles many formats (ISO 8601, US/European, relative, etc.).

⏱️ Time Specification

A time is [at] HH:MN [am|pm] [Zone], optionally with seconds :SS and fractional seconds (ignored). 12‑hour mode requires AM/PM. Zone follows the time.

📆 ISO 8601 Formats

YYYYMMDDHHMNSSF...
YYYYMMDDHHMNSS
YYYYMMDDHHMN
YYYYMMDDHH
YY-MMDDHHMNSSF...
YY-MMDDHHMNSS
YY-MMDDHHMN
YY-MMDDHH
YYYYMMDD
YYYYMM
YYYY
YY-MMDD
YY-MM
YY
YYYYwWWD      ex.  1965-W02-2
YYwWWD
YYYYDOY       ex.  1965-045
YYDOY

Dashes are optional except where shown. T may separate date and time. Time zone can be any Date::Manip‑understood zone.

🇺🇸🇪🇺 Other Common Formats

Formats using month names (mmm) and numeric parts separated by space, / or . (dash may conflict with ISO). Month/day order depends on DateFormat variable.

MM/DD  **
MM/DD/YY  **
MM/DD/YYYY  **

mmmDD       DDmmm                   mmmYYYY/DD     mmmYYYY
mmmDD/YY    DDmmmYY     DD/YYmmm    YYYYmmmDD      YYYYmmm
mmmDDYYYY   DDmmmYYYY   DDYYYYmmm   YYYY/DDmmm

🗣️ Relative / Natural‑Language Formats

• "first Sunday in June 1996 at 14:00"
• "Sunday week 22 1995"
• "22nd Sunday at noon"
• "next Friday at noon"
• "next month"
• "in 3 weeks at 12:00"
• "3 weeks later" / "3 weeks ago"
• "Friday in 2 weeks" / "in 2 weeks on Friday"
• "last day of October"
• "Friday" (current week)
• "12th", "1st" (current month)
• "epoch SECS" (seconds since 1970‑01‑01 GMT)

Words like “in”, “at”, “of” are ignored. Year is optional; defaults to current year.

📌 Recognized Strings

• "today", "now"
• "yesterday", "tomorrow"
• "noon" (12:00), "midnight" (00:00)

📋 Important Notes

• Case‑insensitive.
• 2‑digit years expanded using YYtoYYYY logic (default: CURR‑89 to CURR+10).
• Day‑of‑week is checked; mismatches cause a search for a valid date (may yield unexpected results in array context).
• Midnight = 00:00:00, noon = 12:00:00. 24:00 is turned into 00:00 next day.
• Internal format returned: YYYYMMDDHH:MM:SS (modifiable via Internal variable).

🖨️ UnixDate

@date = UnixDate($date,@format);
$date = UnixDate($date,@format);

Takes a date and one or more format strings, returns formatted strings.

📐 Format Specifiers

• Year: %y (00‑99), %Y (0001‑9999)
• Month: %m (01‑12), %f (" 1"‑"12"), %b/%h (abbrev), %B (full)
• Day: %j (001‑366), %d (01‑31), %e (" 1"‑"31"), %v (abbrev with spaces), %a (abbrev), %A (full), %w (1=Mon‑7=Sun), %E (suffix)
• Hour: %H (00‑23), %k (" 0"‑"23"), %i (" 1"‑"12"), %I (01‑12), %p (AM/PM)
• Minute, Second, Zone: %M, %S, %Z ("EDT"), %z ("+0100")
• Epoch: %s (seconds since 1970 GMT), %o (same in current zone)
• Combined: %c, %C/%u, %g, %D, %x, %l (ls‑style), %r, %R, %T/%X, %V, %Q, %q, %P, %O, %F, %K
• ISO‑8601 week/year: %G (year, week starts Mon), %W (week number Mon), %L (year, Sun), %U (week number Sun), %J (%G-W%W-%w)
• Literals: %n (newline), %t (tab), %% (percent)

The %l format mimics ls -l: %b %e %H:%M within 6 months, else %b %e %Y.

For week numbers, use (%W,%G) or (%U,%L) to avoid year‑boundary errors.

Negative %s and %o values are possible for pre‑epoch dates.

🔧 ParseDateDelta

$delta = ParseDateDelta(\@args);
$delta = ParseDateDelta($string);
$delta = ParseDateDelta(\$string);

Parses a time delta (duration). Recognised forms:

+Yy +Mm +Ww +Dd +Hh +MNmn +Ss        (any order, separated by space)
+Y:+M:+W:+D:+H:+MN:+S                   (colon separated, 2‑7 fields)
mixed: 4 hour 3:-2

Units: y (year), m (month), w (week), d (day), h (hour), mn (minute), s (second). “in” is ignored; “ago” reverses sign. Normalised output forces all‑positive or all‑negative, separately for year/month and day/hour/minute/second segments.

🔣 Delta_Format

@str = Delta_Format($delta [,$mode], $dec,@format);
$str = Delta_Format($delta [,$mode], $dec,@format);

Formats a delta value. Two‑character format codes: %Xv (value of field X), %Xd (field X and smaller expressed in units of X), %Xh (field X and larger in units of X), %Xt (total delta in units of X). X is y,M,w,d,h,m,s (case‑sensitive).

Exact mode (default) keeps year/month and day/time segments separate. Approximate mode (pass "approx" as second argument) uses 1 year = 365.25 days, 1 month = 1/12 year.

🔁 ParseRecur

$recur = ParseRecur($string [,$base,$date0,$date1,$flags]);
@dates = ParseRecur($string [,$base,$date0,$date1,$flags]);

Defines recurring events. The full specification is freq*flags*base*date0*date1. Frequency description: Y:M:W:D:H:MN:S, with exactly one asterisk to separate interval and specific values. Values after asterisk can be single, range (2‑5), or comma‑separated list; negative numbers count from the end.

Examples:

1:2*3:4:5:6:7           every 1 year 2 months, on the 3rd day of 4th week at 05:06:07
0:0:0:2*12:30:0         every 2 days at 12:30
0:0:0:1*2,4,6:0:0       every day at 02:00, 04:00, 06:00
1*12:0:24:0:0:0*FW1     Christmas (observance)

Day field after asterisk can mean day‑of‑week, day‑of‑month, or day‑of‑year depending on the surrounding fields. Week and month contexts alter interpretation.

Flags (case‑insensitive): PDn, PTn, NDn, NTn (previous/next day of week), FDn, BDn, FWn, BWn, CWD, CWN, CWP, NWD, PWD, DWD, EASTER. Another way to define “every Tuesday” etc. is via English phrases, which set default base/date0/date1.

⚖️ Date_Cmp

$flag = Date_Cmp($date1,$date2);

Compares two dates, considering time zones. (Currently a wrapper around cmp, but future‑proof.)

🔢 DateCalc

$d = DateCalc($d1,$d2 [,\$err] [,$mode]);

Adds dates and/or deltas. If two dates → delta; if two deltas → delta; if date+delta → date. Modes: 0 (exact, default), 1 (approximate, shows years/months), 2 (business, uses holidays/work hours), 3 (exact business delta). Keywords “approximately”, “business”, “exactly” in the arguments can override mode. Error reference \$err receives 1/2/3 on failure. Returns nothing on error.

⏰ Date_SetTime

$date = Date_SetTime($date,$hr,$min,$sec);
$date = Date_SetTime($date,$time);

Sets the time portion of a date. Accepts "HH:MM:SS" or separate arguments.

🔨 Date_SetDateField

$date = Date_SetDateField($date,$field,$val [,$nocheck]);

Sets a single field (y, m, d, h, mn, s). With $nocheck true, validity is not enforced.

⏪ 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);

Finds the previous occurrence of a given day‑of‑week or time. $dow can be name (Fri) or number (1‑7). $curr determines handling when date matches: 0 → previous week, 1 → same day, 2 → strictly before. If $dow is undef, finds previous matching time (like a digital clock).

⏩ Date_GetNext

Same as Date_GetPrev but forward.

🎊 Date_IsHoliday

$name = Date_IsHoliday($date);

Returns holiday name or undef. Empty string for unnamed holidays.

📋 Events_List

$ref = Events_List($date);
$ref = Events_List($date ,0      [,$flag]);
$ref = Events_List($date0,$date1 [,$flag]);

Returns a list of events defined in the config file’s Events section. In the first form, returns events active at that instant. With range, returns changes. $flag controls format: 0 → list of (date, [events]), 1 → tally per event, 2 → tally with unique combinations.

🌐 Date_ConvTZ

$date = Date_ConvTZ($date);
$date = Date_ConvTZ($date,$from);
$date = Date_ConvTZ($date,"",$to [,$errlev]);
$date = Date_ConvTZ($date,$from,$to [,$errlev]);

Converts between time zones. Defaults use ConvTZ config variable. $errlev: 0 → die, 1 → warn, 2 → silent return.

🏢 Date_IsWorkDay

$flag = Date_IsWorkDay($date [,$flag]);

Returns 1 if date is a work day. Second argument non‑zero checks work hours as well.

➡️ Date_NextWorkDay

$date = Date_NextWorkDay($date,$off [,$flag]);

Steps forward $off work days. Non‑zero flag respects time of day.

⬅️ Date_PrevWorkDay

Similar, backward.

🎯 Date_NearestWorkDay

$date = Date_NearestWorkDay($date [,$tomorrowfirst]);

Finds nearest work day. If date is work day, returns it. Otherwise looks forward first if $tomorrowfirst is true (or config TomorrowFirst).

📦 Internal Routines (Fast)

These skip most error checks and require explicit Date_Init. They receive numeric arguments.

$day = Date_DayOfWeek($m,$d,$y);           # 1=Mon, 7=Sun
$secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);   # seconds since epoch local
$secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s); # seconds since epoch GMT
$days = Date_DaysSince1BC($m,$d,$y);               # days since Dec 31, 1BC
$day = Date_DayOfYear($m,$d,$y);                   # 001-366
($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);   # day of year -> date
$days = Date_DaysInYear($y);                        # 365 or 366
$days = Date_DaysInMonth($m,$y);                    # days in month
$wkno = Date_WeekOfYear($m,$d,$y,$first);          # week number (0‑53)
$flag = Date_LeapYear($y);                          # 1 if leap year
$day = Date_DaySuffix($d);                          # 'st','nd','rd','th'
$tz = Date_TimeZone();                              # local time zone abbreviation

For Date_WeekOfYear, prefer UnixDate with %W, %U, etc., because the raw result may need adjustment for ISO‑8601.

🕒 TIME ZONES

Date::Manip 5.xx supports the following time zone specifications. Daylight saving time is **not** handled reliably; that will be fixed in version 6.xx.

🌍 RFC‑822 Zones

• Universal: GMT, UT
• US zones: EST, EDT, CST, CDT, MST, MDT, PST, PDT
• Military: A–Z (except J)
• Numeric: +HHMM, -HHMM, +HH:MM, +HH, -HH:MM, -HH

🕰️ Legacy Abbreviations (backward compatibility)

• IDLW (-1200) International Date Line West
• NT (-1100) Nome
• SAT (-0400) Chile
• CLDT (-0300) Chile Daylight
• AT (-0200) Azores
• MEWT (+0100) Middle European Winter
• MEZ (+0100) Middle European
• FWT (+0100) French Winter
• GB (+0100) GMT with daylight savings
• SWT (+0100) Swedish Winter
• MESZ (+0200) Middle European Summer
• FST (+0200) French Summer
• METDST (+0200) An alias for MEST
• EETDST (+0300) / EETEDT (+0300) Eastern Europe
• BT (+0300) Baghdad
• IT (+0330) Iran
• ZP4 (+0400) USSR Zone 3
• ZP5 (+0500) USSR Zone 4
• IST (+0530) Indian Standard
• ZP6 (+0600) USSR Zone 5
• AWST (+0800) Australian Western Standard
• ROK (+0900) Republic of Korea
• AEST (+1000) Australian Eastern Standard
• ACDT (+1030) Australian Central Daylight
• CADT (+1030) Central Australian Daylight
• AEDT (+1100) Australian Eastern Daylight
• EADT (+1100) Eastern Australian Daylight
• NZT (+1200) New Zealand
• IDLE (+1200) International Date Line East

All other time zone abbreviations are taken from the Olson/zoneinfo database (see Date::Manip::DM5abbrevs). Some abbreviations are ambiguous; only the most common mapping is available.

Date::Manip tries to determine the local time zone from $Date::Manip::TZ, $ENV{TZ}, the Unix date command, $main::TZ, /etc/TIMEZONE, or /etc/timezone. Use Date_Init to set TZ if automatic detection fails.

The STD#DST format is allowed for the TZ variable but not when parsing a date. Also recognised: US/Pacific, US/Mountain, US/Central, US/Eastern, Canada/Pacific, …

⚙️ CUSTOMIZING DATE::MANIP

Configuration can be set in Manip.pm, a global config file, a personal config file, or via Date_Init. The personal config file is named .DateManip.cnf (Unix) or Manip.cnf (Windows). Search path defined by PersonalCnfPath.

A config file consists of assignment lines (VARIABLE = VALUE) and sections starting with *Section. Comments begin with #.

📋 DATE::MANIP VARIABLES

• IgnoreGlobalCnf – skip the global config file.
• EraseHolidays – clears all holiday definitions (useful before loading a new set).
• PathSep – regex for separating paths (default : on Unix, ; on Win32).
• GlobalCnf – full path to a global config file.
• PersonalCnf – name of personal config file.
• PersonalCnfPath – colon/semicolon separated paths to search.
• Language – currently supported: English, French, Swedish, German, Dutch, Polish, Spanish, Portuguese, Romanian, Italian, Russian, Turkish, Danish.
• DateFormat – "US" (month‑first) or anything else (day‑first).
• TZ – local time zone (e.g. "EST5EDT").
• ConvTZ – time zone to convert all parsed dates into; "IGNORE" disables conversion.
• Internal – 0 = YYYYMMDDHH:MN:SS, 1 = YYYYMMDDHHMNSS.
• FirstDay – 1 (Monday) to 7 (Sunday); default 1 (ISO 8601).
• WorkWeekBeg, WorkWeekEnd – first and last day of work week (1‑7).
• WorkDay24Hr – treat work day as 24 hours (ignore WorkDayBeg/End).
• WorkDayBeg, WorkDayEnd – start/end times of working hours.
• TomorrowFirst – when finding nearest work day, look forward first (default 1).
• DeltaSigns – force a sign on every delta component (for backward compatibility).
• Jan1Week1 – ignore ISO 8601 week numbering, treat week containing Jan 1 as week 1.
• YYtoYYYY – how to expand 2‑digit years: integer N → CURR‑N … CURR+(99‑N); "C" → current century; "C##" → specific century; "C####" → 100‑year range.
• UpdateCurrTZ – re‑check time zone on every parse (performance penalty).
• IntCharSet – 1 uses international characters (e.g. accents in month names).
• ForceDate – force “now” to a fixed date for testing (YYYY-MM-DD-HH:MN:SS).
• TodayIsMidnight – if true, “today” means midnight instead of now.

🎉 HOLIDAY SECTION

Holiday definitions in the config file:

*Holiday
DATE = HOLIDAY_NAME

DATE can be:

• “Date” (e.g. 1/1) – every year on that date.
• “Date +/- Delta” (fourth Thu in Nov + 1 day)
• “Recur” (1*12:0:24:0:0:0*FW1)

Use recurrences to handle observed holidays. Business mode keywords are allowed in the Date or Delta. To avoid overwriting identical recurrences, make them unique by adding an ignored flag or a leading zero.

Example:

1*12:0:24:0:0:0*FW1  = Christmas
1*12:0:25:0:0:0*FW1  = Boxing
# or
1*12:0:24:0:0:0*FW1  = Christmas
01*12:0:24:0:0:0*FW1 = Boxing

📅 EVENTS SECTION

Events are defined similarly but do not affect business calculations:

*Events
EVENT = NAME

EVENT can be:

• Date* or Recur* (midnight‑midnight, 24h).
• Date or Recur (exact time, 1 hour duration).
• Date ; Date, Date ; Delta, Recur ; Delta (start and end/duration).
• Date ; Delta ; Delta or Recur ; Delta ; Delta (start and end offset from base).

⚠️ KNOWN PROBLEMS

• Unable to determine Time Zone: set TZ variable (e.g. "EST5EDT") via Date_Init or environment.
• Missing date formats: see Date::Manip::Problems.
• Windows getpwnam/getpwuid complaints: set $ENV{OS} to Windows_NT or Windows_95 before use Date::Manip.
• Speed: ISO‑8601 dates parse fastest; avoid relative dates when performance matters. Business calculations are slow.
• Sorting: call Date_Init explicitly before sorting with ParseDate. Better, parse once and sort with cmp, then reformat. (Memoize can speed repeated parsing.)
• RCS keyword expansion: checkout files with co -ko to avoid $Date...$ substitution.

🐛 KNOWN BUGS

• Daylight Saving Time: not handled correctly; conversions across DST changes may be off by one hour. Time zones are treated as fixed offsets. This will be addressed in version 6.xx.
• Some time zone abbreviations are ambiguous; only one mapping is provided.

🐞 BUGS AND QUESTIONS

Refer to Date::Manip::Problems for reporting guidance.

🔗 SEE ALSO

Date::Manip – main module documentation

©️ LICENSE

This software is free; you can redistribute and/or modify it under the same terms as Perl itself.

✍️ AUTHOR

Sullivan Beck (sbeck AT cpan.org)

perl v5.32.1 2021‑11‑20 Date::Manip::DM5(3pm)