info > Date::Manip::Changes5to6

man perldoc info pydoc3 ri search

🏷️ NAME

Date::Manip::Changes5to6 - describes differences between 5.xx and 6.00

🚀 Quick Reference

Use Case	Command / Behavior	Description
Set alternate time zone	Date_Init("SetDate=America/New_York")	Use SetDate or ForceDate config instead of $::TZ
Override config from files	Date_Init("ConfigFile=...", "DateFormat=...")	List script overrides after config files in Date_Init
"today" now midnight	ParseDate("today") → 00:00:00	Use "now" for current time; "today" gives start of day
Default time for parsed dates	Date_Init("DefaultTime=curr")	Controls whether a date without time defaults to 00:00:00 or current time
Stricter parsing	"01//03/75" → no valid date	Only well‑formed date delimiters accepted; no concatenated words
Convert time zones	Date_ConvTZ($date, $from, $to)	3‑argument form only; $from/$to default to local zone
Parse Apache log entry	$date->parse_format($line)	Use OO parse_format instead of old auto‑detection
Approximate deltas changed	DateCalc("Jan 10 1996 noon", "Jan 7 1998 noon")	Result may use mixed signs (+2:0:-0:3:0:0:0) instead of +1:11:4:0:0:0:0

📝 SYNOPSIS

Date::Manip 6.00 represents a complete rethink and rewrite of Date::Manip. A great deal of effort was made to make sure that 6.00 is almost backwards compatible with 5.xx whenever feasible, but some functionality has changed in backwards incompatible ways. Other parts have been deprecated and will be removed at some point in the future.

This document describes the differences between the 5.xx series and version 6.00. This page primarily describes technical details, most of which do not impact how Date::Manip is used in scripts. If you want to make sure that a script which ran with 5.xx will run with 6.xx, refer to the Date::Manip::Migration5to6 document.

🔎 OVERVIEW

The Date::Manip 5.xx series suffered from several weaknesses. These included:

• 🌍 Poor time zone support – Time zone support in 5.xx was broken. Determining a time zone, and understanding daylight saving time changes was incomplete and totally inadequate.
• 🔀 Parsing too complicated and unstructured – The parsing routines had grown very complicated and overly permissive.
• 🧩 Lacking OO model – Date::Manip 5.xx was written as a functional module, not an OO module. The OO model allows a lot of information to be stored with each date.
• 🧱 Too monolithic – The entire module was contained in one huge file.

Date::Manip 6.00 is a complete rewrite to address these and other issues.

🔄 GENERAL CHANGES

• (*) 💎 Requires perl 5.10.0 – Please see the Date::Manip::Problems document for a discussion of this problem. It's in the KNOWN COMPLAINTS section.
• (*) 🧩 Breaking into smaller modules – Date::Manip module has been broken up from one huge module into a large number of smaller more manageable modules. The main module is still present and backwards compatible. New OO modules:
  • Date::Manip::Base – basic date operations
  • Date::Manip::TZ – time zone operations
  • Date::Manip::Date, Date::Manip::Delta, Date::Manip::Recur – OO date, delta, recurrence handling
• (*) 💾 Intermediate data cached – Many intermediate values are cached to improve performance. This impacts memory footprint but greatly speeds up operations. The Memoize module should not be used with Date::Manip 6.00.
  Config‑dependent data is cached separately; the cache is cleared whenever a config variable is set. Set all config variables at the start for best performance.
• 🛡️ Taint safe – Date::Manip now contains no tainted data and should run with taint checking on, provided you don't add custom methods for determining the system time zone via curr_zone_methods.

🕒 TIME ZONE SUPPORT

• (*) 🌐 Complete handling of time zones – The biggest problem with Date::Manip 5.xx was its inability to correctly handle time zones and Daylight Saving Time. Version 6.00 includes support for every time zone in the zoneinfo (Olson) database.
• 🚫 Individual time zones will no longer be added – Since 6.00 supports a full set of standard time zones, I will no longer add individual time zones. Date::Manip::TZ includes functionality for adding them yourself if needed.
  Supported standards:
  • Olson zoneinfo database
  • all Microsoft Windows time zones
  • zones listed in RFC‑822
  If other standards with different naming exist, please point me to them so they can be added.
• 🗑️ Nonstandard time zone abbreviations removed – The following time zones were in 5.xx but not in 6.00:
  • 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 saving
  • SWT +0100 Swedish Winter
  • MESZ +0200 Middle European Summer
  • FST +0200 French Summer
  • METDST +0200 An alias for MEST used by HP‑UX
  • EETDST +0300 An alias for eest used by HP‑UX
  • EETEDT +0300 Eastern Europe, USSR Zone 1
  • 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
  • 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
• 📦 A lot of support modules and files – Date::Manip now includes many automatically generated modules (over 1000) to represent every time zone and offset. They are loaded on demand, so there is no performance penalty. The distribution also includes the tzdata script and Date::Manip::TZdata module used to generate these, included for completeness.
• (*) 🔄 Meaning of $::TZ and $ENV{TZ} – In 5.x, these variables set the working time zone. In 6.00 they are used only to specify the actual local time zone of the system. To specify an alternate working time zone, use the SetDate or ForceDate config variables.

⚙️ CONFIG FILES AND VARIABLES

• (*) 📝 Date_Init handling of config variables – Options to Date_Init are parsed in order, so put config‑file arguments first, then script‑specific overrides:

  Date_Init("ConfigFile=DateManip.cnf","DateFormat=Other")

• 🚫 Date_Init doesn't return config variables – In 5.xx, Date_Init could return the list of all config variables. That functionality is gone; Date_Init is only for setting variables.
• (*) 🗂️ Config file options – The old GlobalCnf, IgnoreGlobalCnf, PersonalCnf, PersonalCnfPath, and PathSep variables have been removed. Use the single variable ConfigFile with a full path. Multiple config files can be specified:

  Date_Init("ConfigFile=./Manip.cnf","ConfigFile=/tmp/Manip.cnf")

• 🗑️ Other config variables removed:
  • TodayIsMidnight → Use DefaultTime
  • ConvTZ → Use SetDate or ForceDate
  • Internal → Use Printable
  • DeltaSigns → Use Date::Manip::Delta::printf method
  • UpdateCurrTZ – no longer necessary
  • IntCharSet → Replaced by Encoding config variable
• ⚠️ Other config variables deprecated – TZ (use SetDate or ForceDate) will be removed in a future version.
• 🎉 Holidays – The old "Date + Delta" style holiday definitions are no longer supported. Use recurrences instead.
• ✨ TZ replaced (and enhanced) – SetDate and ForceDate now include the old TZ functionality with correct time‑change handling. Parsed results may differ from 5.x (which is good, because 5.x didn't handle time zones properly).

📅 DATE PARSING AND OPERATIONS

• (*) 🌞 today, tomorrow, yesterday – In 6.00 these are treated strictly as date strings (i.e., the current day at 00:00:00). The word "now" still refers to the current date and time.

  # 5.xx: "today" = 24 hours from now
  # 6.xx: "today" = start of the current day

• 📏 ISO 8601 formats – Some date formats conflicted with the ISO 8601 specification. Dates are now parsed according to the spec (with a few documented extensions). One key change: the date 1996-w02-3 is now interpreted as the 3rd day of the 2nd week (instead of Wednesday of the 2nd week). To get Wednesday (day 3) of that week, use:

  $err   = $date->parse("1996-w02-1");
  $date2 = $date->next(3,1);

• (*) 🔒 Parsing is now more rigid – Punctuation and word boundaries are strictly enforced. For example, "01//03/75" and "in5seconds" will no longer parse (use "01/03/75" and "in 5 seconds"). This simplifies regular expressions and reduces false positives on garbage input.
• 🚫 Support dropped for a few formats – Very uncommon formats like DD/YYmmm, mmmYYYY, etc. are no longer supported. These could be re‑added if requested.
• 📄 No longer parses the Apache format – The DD/mmm/YYYY:HH:MN:SS format is not directly supported, but the parse_format method can parse an Apache log line without pre‑extracting the date.
• 📆 Date_PrevWorkDay behavior – When $timecheck is zero, day 0 is now always defined as the next business day at the same time (previously it was the previous business day). This makes day 0 consistent regardless of $timecheck.
• (*) ⏰ Default time – Previously the default time for a parsed date depended on the format section. Now it's controlled by the DefaultTime config variable. If DefaultTime="curr", any date without time defaults to the current time; otherwise it defaults to midnight.

  # With DefaultTime="midnight":
  #   "Jun 12"     -> Jun 12, 2009 at 00:00:00
  #   "next week"  -> Jun 12, 2009 at 00:00:00

• 🕐 %z format – The %z format now yields -05:00:00 instead of -0500.

⏳ DELTAS

• 🚫 Dropped mixed style delta parsing – Mixed forms like "1 hour 2:3" are no longer supported. Use either a fully numeric (1:2:3) or fully language‑specific (1 hour 2 minutes 3 seconds) delta.
• 📊 Approximate date/date calculations – The approximate delta between Jan 10 1996 noon and Jan 7 1998 noon is now +2:0:-0:3:0:0:0 (2 years minus 3 days) instead of +1:11:4:0:0:0:0. This matches how most people think about such deltas and is much faster to calculate.
• 🔢 Approximate relationships in deltas – The approximate year length changed from 365.25 days (Julian) to 365.2425 days (Gregorian).
• 📝 Old style formats – The old Delta_Format command still supports the old format strings (though the new printf method uses a slightly different format). The old formats are not available via printf.

🔁 RECURRENCES

• 📅 Day field meaning changed – When the day field refers to day‑of‑week number, negative values are no longer allowed (e.g., -1 for last day of week). Recurrence 1*2:3:4:0:0:0 now means the 3rd occurrence of day 4 (Thursday) in February, not the 3rd occurrence of the 4th day of the week. 1*2:3:-1:0:0:0 is now invalid.
• 🔚 Recurrence range now inclusive – Dates are now allowed to be on or before the end date (previously before only).
• 🚫 Dropped support for a couple English recurrences – Recurrences like "every 2nd day in June [1997]" and "every 6th Tuesday [in 1999]" are no longer supported because they are impractical to calculate and break the approximate‑distance model.
• 🧹 Other minor recurrence changes – ParseRecur no longer supplies default dates if the start or end is missing.

📦 DATE::MANIP FUNCTIONS

The Date::Manip module contains the same functions as 5.xx (though the OO modules do all the work now). Changes:

• Date_ConvTZ – Only the 3‑argument form is supported: Date_ConvTZ($date, $from, $to). Both $from and $to default to the local time zone. The optional 4th argument ($errlevel) is removed; on error an empty string is returned.
• DateCalc – It is no longer recommended to pre‑parse arguments with ParseDate / ParseDateDelta; the function handles arguments intelligently, and pre‑parsing would cause double work.

🐛 BUGS AND QUESTIONS

Please refer to the Date::Manip::Problems documentation for information on submitting bug reports or questions to the author.

🔗 SEE ALSO

Date::Manip - main module documentation

📜 LICENSE

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

✍️ AUTHOR

Sullivan Beck (sbeck AT cpan.org)

🏷️ NAME 🚀 Quick Reference 📝 SYNOPSIS 🔎 OVERVIEW 🔄 GENERAL CHANGES 🕒 TIME ZONE SUPPORT ⚙️ CONFIG FILES AND VARIABLES 📅 DATE PARSING AND OPERATIONS ⏳ DELTAS 🔁 RECURRENCES 📦 DATE::MANIP FUNCTIONS 🐛 BUGS AND QUESTIONS 🔗 SEE ALSO 📜 LICENSE ✍️ AUTHOR