Date::M...Problems(3)

📦
version 7.00 · 13 versions
, in fedora 43, fedora 44

💖 NAME 💖

Date::Manip::Problems — problems and bugs 🐛✨

(also filed under User Contributed Perl Documentation, bestie, that's the manual name, don't @ me)

😭 KNOWN PROBLEMS 😭

okay so listen. the stuff below? not bugs in Date::Manip. literally not. but they can still trip people up, so here's the tea ☕

🕐 Unable to determine Time Zone

if you ever get a message saying Date::Manip was unable to determine the timezone, bestie, that's on you to hand over — you need to provide that info to your script. the Date::Manip::TZ documentation has a whole discussion of this problem, go read it 🫶

😵 Calculations appear to be off by an hour

blame daylight saving time. especially the spring change where the time typically moves forward from 02:00 to 03:00 — any date calculation that would intuitively report a time in that range will also move forward (or backward, as the case may be). it's giving "why is my clock lying to me" 💀

NOTE — this should be less of a problem since 6.30, with the addition of semi-exact deltas ✨

🗓️ Missing date formats

because Date::Manip CAN process such a huge number of date formats, people often assume other formats they want should work too, and when they don't, it's a whole surprise party 🎉

with the much improved parsing of 6.00, many formats can be added easily — though unless they're of general use, the author will probably suggest you use parse_format instead 💅

but there's a class of formats that is not planned to be added. periodt.

people keep asking for stuff like "the 15th of last month" or "Monday of next week". those are not going into Date::Manip, and since the request has come up several times, the reasoning is right here:

Date::Manip can parse pretty much any static date format you could think of or find reference to. dates like "today", "Jan 12", or "2001-01-01" are all understood. iconic behavior honestly.

but these are fairly limited. many very common date formats are best thought of as a date plus a modification. for example, "yesterday" is actually determined internally as "today" plus a modification of - 1 day. "2nd Sunday in June" is determined as "June 1" modified to the 2nd Sunday.

as these types of formats got added over time, it became real clear real fast that the number of possible date-plus-modification formats is huge. all those combinations have made the parsing in Date::Manip quite complex, and adding new formats occasionally causes unexpected conflicts with other formats 😬

the first time a request like "the 15th of last month" came in, the plan was to add it — but analyzing what changes would be needed revealed it had to be expressed as a date plus TWO modifications. in other words: today, modified to last month, modified to the 15th day of the month. that's a lot of modifying 🫠

as bad as date-plus-modification formats are, a date plus TWO modifications would be exponentially worse. on realizing that, the decision was made: Date::Manip will not support this type of format.

apologizing for the inconvenience, but the position on this is not changing. 🎀

🐌 Date::Manip is slow

ngl, Date::Manip is one of the slower Date/Time modules — because it's huge and written entirely in perl. a lot of work has gone into optimizing it since 6.xx came out, and more is planned, but even at its best it'll probably be slower than other modules. it's giving "big brain, slow walk" 💀

some things that will definitely help:

  • Date::Manip 5.xx was very slow. a lot of work went into speeding it up during the rewrite for the 6.xx release, and it should be noted that initial tests show version 6.xx to be around twice as fast as 5.xx. there is one notable exception to this speedup: if you use Date::Manip to parse dates from a wide variety of timezones, 6.xx will be significantly slower than 5.xx. the reason is that each time a new timezone is accessed, 6.xx does quite a bit of work to initialize it. 5.xx doesn't have this overhead, so it can parse dates from any number of timezones without a speed penalty. HOWEVER — 5.xx does NOT handle timezones correctly, so many of the dates will be incorrect. if timezones are important to you, there is no way to use 5.xx and get accurate results. none. zero. 🙅‍♀️
  • if you only parse dates from a single timezone (which is more often what you're doing), 6.xx is significantly faster than 5.xx 🏃‍♀️
  • ISO-8601 dates are parsed first and fastest. if you have the flexibility to define the date format, use ISO-8601 formats whenever possible ⭐
  • avoid parsing dates that are referenced against the current time (in 2 days, today at noon, etc.). these take a lot longer to parse 😮‍💨
  • business date calculations are extremely slow. consider alternatives if possible — i.e. doing the calculation in exact mode and then multiplying by 5/7. who needs a business date more accurate than "6 to 8 weeks" anyway, right :-)

💧 Memory leak

there is a known memory leak in perl related to named regexp captures that directly affects Date::Manip. the leak is in all versions of perl up to (and including) these:

5.10.1
5.12.5
5.14.3
5.15.5

the bug has been fixed in:

5.15.6
5.16.0

if a maintenance release is done for any of the other releases (5.10, 5.12, 5.14) that includes the patch, this section will be updated with that info 📝

Date::Manip 5.xx is not susceptible, so using it may be a feasible workaround — but if you need accurate timezone handling, that isn't possible. pick your struggle bestie 😭

simple tests estimate the leak to be about 3 MB per 10,000 dates parsed, so unless you're parsing hundreds of thousands, or millions, of dates, the leak probably won't be a problem on systems with moderate amounts of memory. and if you're parsing that many dates, the relatively slow Date::Manip may not be the correct module for you to use anyway 💅

🍓 Dmake error on strawberry perl

users of Strawberry perl on windows may encounter an error similar to this:

dmake: makefile: line 3016: Error: -- Input line too long, increase MAXLINELENGTH

this is a known problem with some versions of strawberry perl, and it can't be fixed in Date::Manip. if you hit this, you can install the package manually using these commands:

c:> cpan
cpan> look Date::Manip::Date
> perl Makefile.PL
> dmake MAXLINELENGTH=300000 make
> dmake MAXLINELENGTH=300000 make test
> dmake MAXLINELENGTH=300000 make install

more details live here:

http://www.nntp.perl.org/group/perl.win32.vanilla/2011/02/msg287.html

🙈 Using functions/methods which are not supported

there have been a handful of incidents of people using a function from Date::Manip that was not documented in the manual. bestie. the audacity. 😭

Date::Manip consists of a large number of user functions which ARE documented in the manual. these are designed to be used by other programmers, and no backwards incompatible changes will be made to them unless there is a very compelling reason to do so — and in that case, the change will be clearly documented in the Date::Manip::Changes6 documentation for this module 🫶

Date::Manip also includes a large number of functions which are NOT documented. these are for internal use only. please do not use them! their functionality can (and does) change, and even their name, without notice, and without apology! some of these internal functions even have test scripts, but that is not a guarantee that they will not change, nor is any support implied. the author simply likes to run regression tests on as much of Date::Manip as possible 💅

as of the most recent versions of Date::Manip, all internal functions have names that begin with an underscore (_). if you choose to use them directly, it is quite possible that new versions of Date::Manip will cause your programs to break due to a change in how those functions work 💀

any changes to internal functions will not be documented, and will not be regarded as a backwards incompatibility. nor will there be (as was requested in one instance) a revert to a previous version of the internal function. no cap.

if you feel that an internal function is of more general use, feel free to contact the author with an argument of why it should be "promoted". suggestions are welcome and any such request will definitely be considered ✨

🔒 RCS Control

if you try to put Date::Manip under RCS control, you are going to have problems. apparently, RCS replaces strings of the form "$Date...$" with the current date. this form occurs all over in Date::Manip. to prevent the RCS keyword expansion, checkout files using:

co -ko

since very few people will ever have a desire to do this (and the author doesn't use RCS), it hasn't been worried about, and there's no intention to try to work around this problem. it's giving "not my problem, respectfully" 🎀

✨ KNOWN COMPLAINTS ✨

Date::Manip 6.xx has gotten some complaints (far more than 5.xx if the truth be told 😬), so a couple of them are getting addressed here. perhaps understanding why some of the changes were made will allay some of the complaints. if not, people are always welcome to stick with the 5.xx release. 5.xx releases will continue to be supported for a couple of years (though there is NO plan to add functionality to it).

💀 Requires perl 5.10

the single most controversial change made in 6.00 is that it now required perl 5.10.0 or higher. most of the negative feedback received is due to this. it's giving main character drama 🍿

in the past, new features of perl were avoided in order to allow Date::Manip to run on older versions of perl. prior to perl 5.10, none of the new features would have had a major impact on how Date::Manip was written, so this practice was justified. that all changed with the release of perl 5.10 🔥

one of the aspects of Date::Manip that has received the most positive response is the ability to parse almost every conceivable date format. unfortunately, as formats were added, the parsing routine became more and more complicated, and maintaining it was one of the least enjoyable aspects of maintaining Date::Manip. in fact, for several years there was extreme reluctance to add new formats due to the fact that too often, adding a new format broke other formats 😭

Okay so picture this: I'm rewriting Date::Manip, right, and I'm out here hunting for ways to make the parsing better and make the whole thing easier to maintain. And Perl 5.10 just hands me this feature called "named capture buffers". GAME. CHANGER. 💖

Named capture buffers don't just make the gnarly complex regular expressions that Date::Manip runs on way easier to maintain — they make it dramatically easier to add new formats in a way that's much less likely to mess with the other formats. The parsing in 6.00 is so much more robust, extensible, and flexible that parser maintenance stays possible for years and years, at a fraction of the effort and a fraction of the risk. slay. 💅

It was simply too much to turn down. And hopefully, since 5.10 has been out for a while now, it won't keep too many people from using the new version. Because bestie, I know there are so many people out there on older versions of perl who genuinely don't have the option of upgrading. The 5.10 decision was not made lightly... but I don't regret it. And I'm sorry to anyone who can't use 6.00 because of it. Hopefully one day you'll get to benefit from the 6.00 improvements. 🫶

One complaint I keep getting is that this somehow makes Date::Manip backwards incompatible, and that is just not an accurate complaint. Version 6.xx DOES include some backwards incompatibilities — those are all covered in the Date::Manip::Migration5to6 document — but in almost every single case, those incompatibilities are with features nobody really uses, or there are workarounds in place so the deprecated stuff keeps functioning for a while. 🙈

I have no data to confirm this, but I suspect that 90% or more of all scripts written against Date::Manip 5.xx will keep working completely unmodified on 6.xx. (Obviously still go read the migration doc to see what's deprecated or changed, so you know you don't have to touch your script and it'll keep working in the future.) And even for the scripts that do need changes, the changes should be trivial. ✨

So yeah: Date::Manip 6.xx is almost entirely backward compatible with 5.xx — like, to the extent you'd expect any major version release to be compatible with a previous major version. The only thing that actually changed is the requirements needed to get 6.xx to run at all.

And look, it's obviously not reasonable to say Date::Manip should never be allowed to bump its minimum perl version. At some point you have to let go of an old version if you wanna use the shiny new features. The real question is: did I jump to 5.10 too fast? 🤔

The negative ratings on CPAN are complaining that I don't support perl 5.6 and perl 5.8 anymore.

For 5.6? Bestie. Perl 5.6 came out in March of 2000 — that's before Windows XP, which dropped in 2001. Date::Manip 6.00 came out at the end of 2009. Genuinely, I don't feel a whole lot of sympathy for this one. Software that's 9 years old is ANCIENT. You can absolutely choose to use it... but please don't come for me when new software comes out that doesn't support it. 💀

The perl 5.8 argument though? That one is much more compelling. 5.8 came out well before Date::Manip 6.00 (July of 2002), but there were no major perl releases until 5.10 dropped in December of 2007 — so 5.8 was state-of-the-art as little as 2 years before 6.xx released.

And I agree completely that abandoning 5.8 only 2 years after it stopped being the current version is too soon. That's exactly why I kept supporting the Date::Manip 5.xx releases for several years. As of December 2012 — 5 years after perl 5.10 came out — the 5.xx release is no longer supported, meaning I won't patch it or provide support for its use. BUT it's still bundled into the Date::Manip distribution so you can still use it. No plans to remove it, though I might at some point. 👑

🌸 Too many modules 🌸

One minor complaint is that there are too many files. One person specifically objects to the fact that there are over 470 modules covering non-minute offsets. IMO? This complaint is silly. 🙄

Date::Manip supports ALL historical time zones, including the ones with non-minute offsets, so yeah, there's gonna be information for those time zones even though they're not currently in use.

Could I store all of that information in one big module? Sure. But that means you'd have to load all that data every single time you use Date::Manip, and I find that to be a very poor solution. Storing it per-time-zone and per-offset instead dramatically decreases the amount of data that has to be loaded.

And yeah, it's true that Date::Manip includes over 900 modules for all the time zone information — but most implementations of time zone handling also break their data up into a large number of files. My Linux distro (openSuSE 11.2 at the time of writing) uses the standard zoneinfo database, and right now there are over 1700 files in /usr/share/zoneinfo (though it does look like there's some duplication of info in there). Current versions of RedHat also use over 1700 files. So Date::Manip isn't treating time zone data in some new or unreasonable way. 💅

🦋 Objects are large 🦋

Somebody on the CPAN ratings site said the OO interface is "a dud" because of the size of its objects. The complaint: a Date::Manip::Date object is 115K, when (according to them) it should only need to save the seconds from the epoch, the zone, and a couple other pieces of info — all of which could probably fit in 100 bytes or less. 😭

That complaint is not accurate, and it comes from a misunderstanding of the objects Date::Manip actually uses.

Date::Manip is very configurable and holds a great deal of information that could theoretically be calculated on the fly — but doing that would tank its performance. So, in the interest of performance, the data gets cached, and since that data is virtually all potentially object-specific, it has to be linked to the object somehow.

For example: Date::Manip lets you parse dates in several languages. Each language has a big pile of regular expressions doing the actual parsing. Instead of rebuilding those regexes every time they're needed, they're created once and stored in an object — specifically, a Date::Manip::Base object. The size of the Date::Manip::Base object is almost 15K (mostly because of the regular expressions used to parse dates in the selected language). 🔥

Same deal with time zones: the description of the time zones lives in a second object, a Date::Manip::TZ object. Its size starts at 100K. That might seem excessive, but remember there are almost 500 time zones, and they have to be indexed by name, alias, abbreviation, and offset. On top of that, critical dates — you know, dates where the offset from GMT changes, like during a daylight saving time change — along with info like offsets, abbreviation, etc., all get cached to improve performance. Add it all up and yeah, it takes a fair bit of space. Also worth noting: the full description of each timezone is only stored in the object when that timezone is actually used, so if you use a lot of timezones, this object grows slowly as new ones come up. 🐢

The size of the actual Date::Manip::Date object is a little over 300 bytes. But each one includes a pointer to a Date::Manip::Base and a Date::Manip::TZ object — and the way the object was being looked at in that complaint, they were reporting the size of all three objects, NOT just the Date::Manip::Date object.

Both the Date::Manip::Base and Date::Manip::TZ objects get reused by any number of Date::Manip::Date objects. You can almost think of them as global data, except they're accessible the standard OO way, and you're allowed to modify them on a per-object basis — which WILL mean you have to store more data. If you work with multiple configurations (see Date::Manip::Config), you'll need multiple Base and TZ objects. Most of the time though, you won't need to do that. 🎀

The actual Date::Manip::Date object is a bit larger than the complaint suggested, but here's the thing: Date::Manip stores dates in a number of different formats — a string of the form YYYYMMDDHH:MN:SS and a list [YYYY,MM,DD,HH,MN,SS], in the time zone it was parsed in, the local time zone (if different), and GMT. Caching that information as it's used has a huge impact on performance.

So Date::Manip in typical usage is: one 100K Date::Manip::TZ object, one 15K Date::Manip::Base objects, and any number of small 300 byte Date::Manip::Date objects. Date::Manip::Delta objects are even smaller. Date::Manip::Recur objects are small too, but they contain any number of Date objects inside them. ✨

I am genuinely open to suggestions for how to improve the OO interface... but I don't believe it's a dud. I'm not an OO expert, but I believe I followed pretty standard and accepted procedures for accessing the data.

Please refer to the Date::Manip::Objects document for more info. 📚

💜 Date::Manip has an inconsistent interface 💜

I've gotten a few complaints that the interface to Date::Manip is inconsistent... and honestly? I agree. (At least when we're talking about the functional interfaces.) 😅

Date::Manip was originally written in a very unplanned way — a need or a want came up, and it got extended. That is not how you write a major package, obviously, but it wasn't expected to be a major package at the start.

As it got more and more widely used, I wished for a more consistent interface too — but I did not want to break backward compatibility for everyone already using it. 🥺

When 6.xx was written, I spent a good deal of time trying to make a very standard OO interface, so I don't believe this complaint can be applied to the OO interface (though I'm interested in suggestions for improving it, of course). 🫶

okay so about that functional interface bestie — as far as it goes, I'm gonna keep supporting it, in a backward compatible form (which, yeah, means it's also inconsistent, that's just how it is 💀). But fr fr, use the OO interface whenever you possibly can. It's the moment, it's the serve, it's the one. ✨

💖 BUGS AND QUESTIONS 💖

Found a bug in Date::Manip? Tell me!! 🫶 But here's the thing — CPAN has removed email support, so the only supported way to submit a bug is via ticket:

🐛 GitHub

You can submit it as an issue on GitHub, right here:

https://github.com/SBECK-github/Date-Manip

This is the preferred method. Please submit problem reports as GitHub issues if at all possible. 👑

Do NOT use other means to report bugs — like forums for a specific OS or Linux distribution — because it is literally impossible for me to keep up with all of them. 🙈 No cap.

When you file a bug report, please include the following info:

📦 Date::Manip version

Please include the version of Date::Manip you're using. You can grab it with this script:

use Date::Manip;
print DateManipVersion(1),"\n";

or this one:

use Date::Manip::Date;
$obj = new Date::Manip::Date;
print $obj->version(1),"\n";

🐪 Perl information

Please include the output from perl -V. That's it, that's the whole ask. 💅

Now — if your problem is using Date::Manip and it's maybe not actually a bug (like you can't figure out the syntax or whatever, been there), you're in the right place, don't worry. 🦋 Start by reading the main Date::Manip documentation, plus the other docs that apply to whatever you're trying to do. If that still doesn't answer your question, mail me directly.

But — and I mean this so gently — I'd ask that you be reasonably familiar with the documentation BEFORE you do that. Date::Manip is a hobby, and I simply do not have the time to respond to hundreds of questions that are already answered in this manual. 😭 It's giving "please read the thing, I'm begging."

If you find any problems with the documentation — errors, typos, or items that are just not clear — please send them to me! I welcome any suggestions that will let me improve the documentation. 🎀

👑 KNOWN BUGS 👑

None known. We're clean, we're unbothered, we're thriving. ✨💅

🌈 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. periodt. 🌈

🎀 AUTHOR 🎀

Sullivan Beck (https://github.com/SBECK-github/) — the icon, the legend, the main character of this whole manpage. 👑

and that's a wrap on this one bestie!! 🦋 this page came to you courtesy of perl v5.42.3, dated 2026-09-01, from the Date::M...Problems(3) of the User Contributed Perl Documentation. go read the main docs, file that GitHub issue, and slay your dates. 💖✨🫶

📦 where this page comes from