Date::M...ges5to6(3)

✨ Date::Manip::Changes5to6 ✨

okay bestie, buckle up — this is Date::Manip::Changes5to6, and it describes differences between 5.xx and 6.00. 💖

---

🦋 NAME 🦋

Date::Manip::Changes5to6 — describes differences between 5.xx and 6.00. that's the whole vibe, no cap.

---

🌸 SYNOPSIS 🌸

okay so Date::Manip 6.00 is a complete rethink and rewrite of Date::Manip. the team put in a huge amount of effort to make sure 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. it's primarily about 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 (at best) and totally inadequate to do true timezone operations. it's giving chaos.
• Parsing too complicated and unstructured — the parsing routines had grown very complicated, and overly permissive over time and were in need of a complete overhaul.
• Lacking OO model — Date::Manip 5.xx was written as a functional module, not an OO module, but date handling would lend itself very well to being OO with different classes to handle dates, deltas, and recurrences.

the OO model allows a lot of information to be stored with each date (such as time zone information) which is discarded in the functional interface.

• Too monolithic — the entire Date::Manip module was contained in one huge file. breaking up the module would make it much easier to deal with.

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

the following sections address how Date::Manip 6.00 differs from previous releases, and describes changes that might need to be made to your script in order to upgrade from 5.xx to 6.00.

⭐ the most important changes are marked with asterisks. iykyk.

---

🌈 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

the Date::Manip module has been broken up from one huge module into a large number of smaller more manageable modules. the main Date::Manip module is still present, and contains all of the functions from Date::Manip 5.xx (except that they now call functions from all the other modules to do the actual work). in general, the Date::Manip module from 6.00 is backwards compatible. ✨

a number of new modules have been created as well. these can be used directly, bypassing the main Date::Manip module. these include the following:

• Date::Manip::Base contains many basic date operations which may be used to do simple date manipulation tasks without all the overhead of the full Date::Manip module.
• Date::Manip::TZ contains time zone operations.
• handling dates, deltas, and recurrences are now done in Date::Manip::Date, Date::Manip::Delta, and Date::Manip::Recur.

all of these modules are object oriented, and are designed to be used directly, so if you prefer an OO interface over a functional interface, use these modules. 💖

(*) Intermediate data cached

in order to improve the performance of Date::Manip, many intermediate values are cached. this does impact the memory footprint of the module, but it has a huge impact on the performance of the module. 🔥

some types of data depend on the config variables used, and these are cached separately, and this cache is automatically cleared every time a config variable is set. as a result, it is best if you set all config variables at the start, and then leave them alone completely to get optimal use of cached data.

a side effect of all this is that the Memoize module should not be used in conjunction with Date::Manip.

in the version 5.xx documentation, it was mentioned that the Memoize module might be used to improve performance in some cases. this is no longer the case. it should not be used with Date::Manip, even if you use the functional interface instead of the OO interface. 😭

Taint safe

Date::Manip now contains no tainted data, and should run without problems with taint checking on provided you do not set additional methods for determining the system time zone using the curr_zone_methods function. 🧚

ideally, this should never be necessary. if it is necessary, I'd like to hear about it so that I can add whatever standard methods are needed to the built in list.

---

💜 TIME ZONE SUPPORT 💜

(*) Complete handling of time zones

the biggest problem with Date::Manip 5.xx was it's inability to correctly handle time zones and Daylight Saving Time. that is now fixed. version 6.00 includes support for every time zone included in the zoneinfo (aka Olson) database which includes the definitions of (hopefully) all of the time zones used in the world. 🌍 slay.

Individual time zones will no longer be added

prior to 5.55, time zones were added upon request. since 6.00 now supports a full set of standard time zones, I will no longer add in individual time zones (Date::Manip::TZ includes functionality for adding them yourself if they are needed). with Date::Manip now having full time zone support, I'm not interested in supporting my own time zone database.

however, I am interested in adding sets of time zones from various "standards". 👑

Date::Manip 6.00 includes time zones from the following standards:

Olson zoneinfo database
all Microsoft Windows time zones
zones listed in RFC-822

if there are additional standards that include additional time zones not included here, please point me to them so they can be added. this could include published lists of time zone names supported on some operating system which have different names than the zoneinfo list.

Nonstandard time zone abbreviations removed

some of the individual standards that were added in the 5.xx series are not included in any of the standards listed above.

as of 6.00, only time zones from standards will be included in the distribution (others can be added by users using the functions described in Date::Manip::TZ to add aliases for existing time zones).

the following time zones were in Date::Manip 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 a large number of files and modules that are used to support time zones. 🎀

a series of modules are included which are auto-generated from the zoneinfo database. the Date::Manip::Zones, Date::Manip::TZ::*, and Date::Manip::Offset::* modules are all automatically generated and are not intended to be used directly. instead, the Date::Manip::TZ module is used to access the data stored there.

a separate time zone module (Date::Manip::TZ::*) is included for every single time zone. there is also a module (Date::Manip::Offset::*) for every different offset. all told, there are almost 1000 modules. these are included to make time zone handling more efficient. rather than calculating everything on the fly, information about each time zone and offset are included here which greatly speeds up the handling of time zones. these modules are only loaded as needed (i.e. only the modules related to the specific time zones you refer to are ever loaded), so there is no performance penalty to having them. 🦋

also included in the distribution are a script (tzdata) and additional module (Date::Manip::TZdata). these are used to automatically generate the time zone modules, and are of no use to anyone other than the maintainer of Date::Manip. they are included solely for the sake of completeness. if someone wanted to fork Date::Manip, all the tools necessary to do so are included in the distribution.

(*) Meaning of $::TZ and $ENV{TZ}

in Date::Manip 5.x, you could specify what time zone you wanted to work in using either the $::TZ or $ENV{TZ} variables.

Date::Manip 6.00 makes use of two different time zones: the actual local time zone the computer is running in (and which is used by the system clock), and a time zone that you want to work in. typically, these are the same, but they do not have to be. 🙈

as of Date::Manip 6.00, the $::TZ and $ENV{TZ} variables are used only to specify the actual local time zone.

in order to specify an alternate time zone to work in, use the SetDate or ForceDate config variables. 💅

✨ CONFIG FILES AND VARIABLES ✨

💖 (*) Date_Init handling of config variables

okay so bestie, the way config variables get handled? it changed a little bit. not a glow-up exactly, more like a subtle personality shift.

back in the day, whatever variables you passed into Date_Init would just steamroll the values from your config files. that's not how it works anymore. now the options to Date_Init get parsed in the order you list them, so check this out:

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

this would first set the DateFormat variable, and then read the config file DateManip.cnf. and if that config file happens to define a DateFormat too? yeah, it overrides the one you just passed in. rude, honestly.

so the proper way to override config files is to pass the config files in first, then any script-specific overrides after. like:

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

that's the vibe. order matters, periodt. 💅

🙈 Date_Init doesn't return the config variables

in Date::Manip::5.xx, Date_Init could hand you back the list of all config variables. not anymore, bestie, that functionality is gone. Date_Init is strictly for setting config variables now. it's giving "I have one job and I'm doing it." 💀

✨ (*) Config file options

so Date::Manip 5.xx had this whole concept of a global config file and a personal config file. and on top of that, the personal config file could be hunted down across a path of directories. all of that got specified with these config variables:

GlobalCnf
IgnoreGlobalCnf
PersonalCnf
PersonalCnfPath
PathSep

all of these are removed. bye 👋 instead, you get one single config variable:

ConfigFile

and it specifies config files, full stop — no distinction between global and personal. also, there's no path searching anymore. every file has to be given by a complete path. and finally, you can use any number of config files. so this is totally valid:

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

slay. 💖

🎀 Other config variables removed

these config variables got the boot:

TodayIsMidnight  Use DefaultTime instead.

ConvTZ           Use SetDate or ForceDate instead.

Internal         Use Printable instead.

DeltaSigns       Use the Date::Manip::Delta::printf
                 method to print deltas

UpdateCurrTZ     With real time zone handling in
                 place, this is no longer necessary

IntCharSet      This has been replaced with better support for
                international character sets. The Encoding config
                variable may be used instead.

🦋 Other config variables deprecated

these ones are deprecated and will be removed in some future version, so like, don't get attached:

TZ              Use SetDate or ForceDate instead.

🌸 Holidays

back in the day, holidays could be defined as a "Date + Delta" or "Date - Delta" string. these predate recurrences and they add a whole bunch of complexity to how holidays get handled. since recurrences are a much better way to define holidays, the "Date + Delta" and "Date - Delta" strings are no longer supported. not me mourning the old ways... actually no, it's fine, recurrences ate. 💅

💜 TZ replaced (and enhanced)

the SetDate and ForceDate variables — which, fun fact, include all the functionality of the deprecated TZ variable — are much improved, and it's all described over in the Date::Manip::Config documentation.

and since it now handles time changes correctly (letting time changes happen in the alternate time zone, which is the whole point), parsed results might be different than in 5.x. but honestly? since 5.x didn't have proper time zone handling at all, this is a good thing. upgrade behavior, no cap. 🔥

---

🗓️ DATE PARSING AND OPERATIONS 🗓️

⭐ (*) today, tomorrow, yesterday

so in 5.xx, the words "today", "tomorrow", and "yesterday" meant: the time right now, 24 hours in the future, and 24 hours in the past. respectively. simple, right?

as of 6.00? these are treated strictly as date strings, so they are the current day, the day before, or the day after at the time 00:00:00. midnight energy only. 🌙

and the string "now" still refers to the current date and time. "now" stays winning. ✨

🌈 ISO 8601 formats

a couple of the date formats from Date::Manip 5.xx were beefing with ISO 8601 formats in the spec. those are documented in the Date::Manip::Date documentation.

dates are now parsed according to the spec (though a couple extensions were made, and those are also documented in the Date::Manip::Date documentation, bestie, go read it).

now here's one change versus Date::Manip 5.xx that comes from a possible misinterpretation of the standard. in Date::Manip, there's a small amount of ambiguity in how the Www-D date formats are understood. so the date:

1996-w02-3

might be interpreted two different ways:

1. as Wednesday (day 3) of the 2nd week of 1996, or
2. as the 3rd day of the 2nd week of 1996 (which would be Tuesday if the week begins on Sunday)

since the spec only works with weeks that begin on day 1, the two are always equivalent in the spec, and the language of the spec doesn't clearly indicate one interpretation over the other. so it's genuinely ambiguous, not us being messy. 🙈

but here's the thing — Date::Manip supports weeks starting on days other than day 1 (Monday), so the two interpretations are not equivalent anymore.

in Date::Manip 5.xx, the date was interpreted as Wednesday of the 2nd week. but now? I believe the other interpretation (3rd day of the week) is the one the spec actually intended. and bonus: if you use that interpretation, it's easy to get the other one.

so if 1996-w02-3 means the 3rd day of the 2nd week, then to get Wednesday (day 3) of the week, you use these two Date::Manip::Date methods:

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

the first call grabs the 1st day of the 2nd week, and the second call grabs the next Wednesday. cute and efficient. 💅

if 1996-w02-3 were interpreted as Wednesday of the 2nd week, then getting the 3rd day of the week would take significantly more work. so yeah.

in Date::Manip 6.00, the date will now be parsed as the 3rd day of the 2nd week.

💀 (*) Parsing is now more rigid

the philosophy in Date::Manip 5.xx when it came to parsing dates was basically "if there's any conceivable way to find a valid date in the string, do so." which sounds generous but it was giving... chaos. as a result, strings that did not look like they could contain a valid date often would. 💀

this showed up in two ways:

• first, a lot of punctuation was just ignored. for example, the string "01 // 03 -. 75" was the date 1975-01-03. ma'am?? 😭
• second, a lot of word breaks were optional, and it was often acceptable to run strings together. for example, the delta "in5seconds" would have worked.

with Date::Manip 6.00, parsing still tries to find a valid date in the string, but it uses a more rigidly defined set of allowed formats which should more closely match how dates would actually be expressed in real life. the punctuation allowed is more rigidly defined, and word breaks are required.

so "01/03/75" will work, but "01//03/75" and "01/03-75" won't. also "in5seconds" will no longer work, though "in 5 seconds" will work. space out your words, bestie. 🌸

these changes serve to simplify some of the regular expressions used in parsing dates, as well as simplifying the parsing routines. they also help recognize actual dates as opposed to typos — it was way too easy to pass in garbage and get a date out. no more garbage-in-garbage-out, we fixed the vibe check. ✨

🎀 Support dropped for a few formats

support got dropped for a few very uncommon (probably never used) formats. these include (with Jan 3, 2009 as an example):

DD/YYmmm      03/09Jan
DD/YYYYmmm    03/2009Jan
mmmYYYY/DD    Jan2009/03
YYYY/DDmmm    2009/03Jan

mmmYYYY       Jan2009
YYYYmmm       2009Jan

the last two are no longer supported since they're incomplete.

with the exception of the incomplete forms, these could be added back in with very little effort. so if there's ever a request to do so, I probably will. lowkey keeping the door open. 🫶

🦋 No longer parses the Apache format

Date::Manip 5.xx supported the format:

DD/mmm/YYYY:HH:MN:SS

which is used in apache logs. but due to the stricter parsing, this format is no longer supported directly. however — plot twist — the parse_format method may be used to parse the date directly from an apache log line with no need to extract the date string beforehand. iconic workaround, honestly. 💅

🌙 Date_PrevWorkDay behavior

the behavior of Date_PrevWorkDay changed slightly.

the starting date is checked. if $timecheck was non-zero, the check failed if the date was not a business date, or if the time was not during business hours. if $timecheck was zero, the check failed if the date was not a business date, but the time was ignored.

in 5.xx, if the check failed and $timecheck was non-zero, day 0 was defined as the start of the next business day. but if $timecheck was zero, day 0 was defined as the previous business day at the same time.

in 6.xx, if the check fails and $timecheck is non-zero, the behavior is the same as before. if $timecheck is zero, day 0 is defined as the next business day at the same time.

so day 0 is now always the same — where before, day 0 meant two different things depending on whether $timecheck was zero or not. consistency?? we love to see it. 👑

⭐ (*) Default time

in Date::Manip 5.xx, the default times for dates were handled in an inconsistent manner. per the Date::Manip::Date documentation: if you parse a date from the "Common date formats" section, in Date::Manip 5.xx, and no time was included, it defaulted to "00:00:00". but if you parsed a date from the "Less common formats" section, the default time was the current time. make it make sense. 😭

so running a program on Jun 5, 2009 at noon that parsed the following dates gave the following return values:

Jun 12     =>  Jun 12, 2009 at 00:00:00
next week  =>  Jun 12, 2009 at 12:00:00

this behavior is changed and now relies on the config variable DefaultTime. if DefaultTime is "curr", the default time for any date that includes no information about the time is the current time. otherwise, the default time is midnight. pick your fighter. 🌙

💜 %z format

in Date::Manip 5.xx, the %z format would give an offset in the form: -0500. now it gives it in the form: -05:00:00. glow-up fr fr. ✨

💖 DELTAS 💖

Dropped mixed style delta parsing

ok so back in Date::Manip 5.xx, a parsed delta could show up in the delta style:

1:2:3

or in a language-specific expanded form:

1 hour 2 minutes 3 seconds

or in a mixed form:

1 hour 2:3

The mixed form? GONE. 💀 The author lowkey doubts it ever got much use irl, and honestly dropping it makes the parsing way simpler. bye bestie 👋

Approximate date/date calculations

In Date::Manip 5.xx, the approximate delta between these two dates:

Jan 10 1996 noon
Jan  7 1998 noon

was +1:11:4:0:0:0:0 (or 1 year, 11 months, 4 weeks). But as of Date::Manip 6.00, that same delta is +2:0:-0:3:0:0:0 (or 2 years minus 3 days). ✨

Yes, this gives you mixed-sign deltas, and no, that's not a glitch — it's actually how more people would naturally think about the delta. Bonus: it's MUCH easier and faster to calculate. slay 🔥

Approximate relationships in deltas

When printing parts of deltas back in Date::Manip 5.xx, the approximate relationship used was 1 year = 365.25 days. That's the correct value for the Julian calendar, but for the Gregorian calendar a better value is 365.2425 — and that's the one used in version 6.00. 🌈

Old style formats

The formats used in the printf command are slightly different than in the old Delta_Format command.

The old formats are described in the Date::Manip::DM5 manual, and the new ones live in the Date::Manip::Delta manual.

The new formats are so much more flexible and the author literally encourages you to switch over — but at this point, the old style formats are officially supported for the Delta_Format command. periodt 💅

At some point, the old style formats may be deprecated (and removed at some point beyond that), but for now, they are not.

🚨 Important: the old formats are NOT available using the printf method. no cap.

---

🎀 RECURRENCES 🎀

The day field meaning changed in a few recurrences

So the value of the day field can refer to several different things, including the day of week number (Monday=1 to Sunday=7), day of month (1-31), day of year (1-366), etc.

In Date::Manip 5.xx, it could also refer to the nth day of the week (i.e. 1 being the 1st day of the week, -1 being the last day of the week). That meaning is no longer used in 6.xx.

For example, this recurrence:

1*2:3:4:0:0:0

used to refer to the 3rd occurrence of the 4th day of the week in February.

Now the meaning has changed to refer to the 3rd occurrence of day 4 (Thursday) in February. Which is honestly a much more useful type of recurrence. 👑

And because of that change, this related recurrence:

1*2:3:-1:0:0:0

is invalid. 🙈 Negative numbers may be used to refer to the nth day of the week, but NOT when referring to the day of week numbers.

Recurrence range now inclusive

Previously, the list of dates implied by the recurrence were on or after the start date, but before the end date.

This has been changed so that the dates may be on or before the end date. inclusive era fr fr 🫶

Dropped support for a couple English recurrences

Date::Manip 5.xx claimed support for a recurrence like:

every 2nd day in June [1997]

In actuality, this recurrence is not practical to calculate. 😭 It requires a base date which might imply June 1,3,5,... in 1997 but June 2,4,6 in 1998.

On top of that, the recurrence does not fit the mold for other recurrences that are an approximate distance apart. This type of recurrence has a number of closely spaced events with 11-month gaps between groups.

The author no longer considers this a valid recurrence, and support is now dropped for this string.

Also dropped, for a similar reason:

every 6th Tuesday [in 1999]

Other minor recurrence changes

Previously, ParseRecur would supply default dates if the start or end were missing. This is no longer done. 🚫

---

✨ DATE::MANIP FUNCTIONS ✨

The Date::Manip module contains the same functions that Date::Manip 5.xx had (though the OO modules do all the work now 💅). In general, the routines behave the same as before, with the following exceptions:

Date_ConvTZ

Previously, Date_ConvTZ took 1 to 4 arguments and used the local time zone and the ConvTZ config variable to fill in missing arguments.

Now, the Date_ConvTZ function only supports a 3 argument call:

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

If $from is not given, it defaults to the local time zone. If $to is not given, it defaults to the local time zone.

The optional 4th argument ($errlevel) is no longer supported. If there is an error, an empty string is returned.

DateCalc

In Date::Manip 5.xx, it was recommended that you pass arguments to ParseDate or ParseDateDelta. That is not recommended with 6.00, since it is much more intelligent about handling the arguments — and you'll just end up parsing the date/delta twice. 💀

---

🦋 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 (https://github.com/SBECK-github/)

---

and that's a wrap on this whole page bestie!! 🎀✨ this doc ships with perl v5.42.3 and was dated 2026-09-01, so if you ever need to cite it, that's your tea. go forth and manipulate your dates. mwah 💅🫶