Date::Manip::Misc(3)

📦

version 7.00 · 13 versions

7.00 · fedora 43, fedora 44 (latest)
6.980.0 · opensuse-leap 16.0
6.85 · centos-stream 9
6.94 · centos-stream 10
6.99 · alpine 3.24
7.00 · arch rolling
6.99 · ubuntu stonking
6.98 · fedora 43
6.86 · ubuntu jammy
6.99 · fedora 44
6.95 · ubuntu noble
6.91 · debian bookworm
6.98 · debian trixie, ubuntu questing, ubuntu resolute

💖 Date::Manip::Misc 💖

okay bestie, welcome to the miscellaneous information page for Date::Manip — it lives in the User Contributed Perl Documentation section and the manual page is literally called Date::Manip::Misc(3). It's the ~lore~ page: should you even use this module, Y2K tea, what dates it can handle, and the future plans. Let's get into it 🫶

✨ NAME ✨

Date::Manip::Misc — Miscellaneous information about Date::Manip 💅

💭 SHOULD I USE DATE::MANIP 💭

So if you go poking around CPAN you'll find a whole bunch of Date and Time packages, and the real question is: is Date::Manip the one for you? Ngl, that's not a trivial question to answer — it totally depends on what you're trying to do. 🙈

Date::Manip is for sure one of the most powerful of the Date modules (the other main contender being the DateTime suite of modules). The author is trying to build a library that can do _EVERY_ conceivable date/time manipulation you'll run into in everyday life dealing with the Gregorian calendar. As far as the author knows, it'll do everything any other date module will do that works with the Gregorian calendar, plus there's a bunch of features Date::Manip has that other modules just... don't. 💅

But bestie, there's a tradeoff in being able to do "everything"... and that tradeoff is primarily in terms of performance. Date::Manip is written entirely in Perl and is the largest of the date modules. Other modules tend to be faster, and modules written in C are significantly faster than their Perl counterparts (at least if they're done right). Even though the author is working on making Date::Manip faster, it will never be as fast as other modules. And before anyone asks — Date::Manip will never be translated to C (at least by the author). The author writes C because they have to, and writes Perl because they like to. Date::Manip is something they do because it interests them, not something they're paid for. 😭

If you're gonna be using the module where performance is an important factor, and you're doing a fairly small set of simple date operations over and over again, you should carefully examine the other date modules to see if they'll meet your needs.

Also heads up: Date::Manip does NOT provide functionality for working with alternate calendars like the Chinese or Hebrew calendars, so if that's what you need, you definitely need to look elsewhere (the DateTime suite, probably). 🚫

On the other hand, if you want one solution for all your date needs, don't need peak speed, or you're trying to do more exotic date operations — Date::Manip is for you, periodt. Operations on things like business dates, foreign language dates, holidays and other recurring events, complete timezone handling, etc. are available more-or-less exclusively in Date::Manip. At the very least, if you want to do these operations it'll require using several other modules, each with its own interface. Also, when you work with Date::Manip, you work with one author and one module. Meanwhile the DateTime suite currently consists of almost 100 modules and 75 authors. 😳

And bonus tea: the author is making significant performance improvements in Date::Manip. It'll never be as fast as some of the other perl modules, but it's already competitive enough for most purposes, and the author keeps looking for places to improve performance, so performance should improve over time. ⭐

🕰️ YEAR 2000 AND YEAR 2007 DST CHANGE 🕰️

Did Date::Manip have any problems with Y2K compliance? Did it have any problems with the revised daylight saving time changes made in 2007? Let's discuss 👑

So even though Date::Manip will parse many date strings (including dates with 2-digit years), internally they're stored as a 4 digit year, and all operations are performed using this internal representation — so Date::Manip had no problems with the Y2K issue. Of course, applications written which stored the year as 2 digits (whether or not they used Date::Manip) may have had problems, but they were not because of this module. 🙅

Similarly for the 2007 changes in daylight saving time made in the United States, Date::Manip was not affected. Date::Manip makes use of the current time zone, but it gets that information from the operating system the application is running on. If the operating system knows about the new daylight saving time rules... so does Date::Manip. slay ✨

📅 WHAT DATES ARE DATE::MANIP USEFUL FOR? 📅

Date::Manip applies to the Gregorian calendar. It does not support alternative calendars (Hebrew, Mayan, etc.) so if you want to use an alternative calendar, you'll need to look elsewhere. 🦋

The Gregorian calendar is a relatively recent innovation. Prior to it, the Julian calendar was in use. The Julian calendar defined leap years as every 4th year, which led to significant calendar drift over time (since a year is NOT 365.25 days long). It was replaced by the Gregorian calendar which improved the definition of leap years, and at that point the calendar was adjusted appropriately.

Date::Manip extrapolates the Gregorian calendar back to the year 0001 AD and forward to the year 9999 AD, but that doesn't necessarily mean the results are useful. As the world adopted the Gregorian calendar, the dates using the Julian calendar had to be changed to fit to account for the drift that had occurred. As such, the dates produced by Date::Manip in an era where the Julian calendar was in use do not accurately reflect the dates actually in use. In historical context, the Julian calendar was in use until 1582 when the Gregorian calendar was adopted by the Catholic church. Protestant countries did not accept it until later; Germany and Netherlands in 1698, British Empire in 1752, Russia in 1918, etc. Date::Manip is therefore not equipped to truly deal with historical dates prior to about 1600, and between 1600 and 1900, the calendar varied from country to country. 😭

A second problem is that the Gregorian calendar is itself imperfect and at some point may need to be corrected (though it's not clear that this will happen... drift may now be accounted for using leap seconds which means that the Gregorian calendar may be useful indefinitely). No attempt is made to correct for the problems in the Gregorian calendar for a couple reasons. First is that the author's great great great grandchildren will be long dead before this begins to be a problem, so it's not an immediate concern. Secondly, and even more importantly, the author doesn't know what the correction will be (if any) or when it will be implemented, so it can be safely ignored. 💅

There's some limitation on how dates can be expressed such that Date::Manip can handle them correctly. Date::Manip stores the year internally as a 4-digit number. This is obviously not a limit due to the Gregorian calendar, but a way to store the dates internally was needed, and the 4-digit year was chosen. The author realizes that the 4-digit limitation does create a time when it will break (quite similar to those who chose a 2-digit representation set themselves up for the Y2K problem). Frankly, it's not too concerning since that date is 8000 years in the future! Date::Manip won't exist then. Perl won't exist then. And it's quite possible that the Gregorian calendar won't exist then. That's a much different situation than the Y2K choice in which programmers chose a representation that would break within the lifetime of the programs they were writing. 🫶

Given the 4-digit limitation, Date::Manip definitely can't handle BC dates, or dates past Dec 31, 9999. So Date::Manip works (in theory) during the period Jan 1, 0001 to Dec 31, 9999. There are a few caveats:

🌍 Gregorian calendar issue 🌍

In practical terms, Date::Manip deals with the Gregorian calendar, and is most useful in the period that that calendar has been, or will be, in effect. As explained above, the Gregorian calendar came into universal acceptance in the early 1900's, and it should remain in use for the foreseeable future.

So... in practical terms, Date::Manip is probably useful from around 1900 through several thousand years from now. ✨

📆 First/last week 📆

In one part of the code (calculating week-of-year values), Date::Manip references dates one week after and one week before the date actually being worked on. As such, dates during the first week in the year 0001 fail (because a week before is in the year 1 BC), and those in the last week in the year 9999 fail (because a week later is in 10,000). 😭

No effort will be made to correct this because the added functionality is simply not that important (to the author), especially since the Gregorian calendar doesn't really apply in either instance. To be absolutely safe, Date::Manip works as described in this manual during the period Feb 1, 0001 to Nov 30, 9999, and only dates within that range are supported (i.e. if you submit a bug using a date that is not in that range, the author will consider themselves free to ignore it). 💀

⏱️ Leap seconds ⏱️

Date::Manip does NOT make use of the leap seconds in calculating time intervals, so the difference between two times may not be strictly accurate due to the addition of a leap second.

🔢 Three-digit years 🔢

Date::Manip will parse both 2- and 4-digit years, but it will NOT handle 3 digit years. So, if you store the year as an offset from 1900 (which is 3 digits long as of the year 2000), these will NOT be parseable by Date::Manip. Since the perl functions localtime and gmtime DO return the year as an offset from 1900, the output from these will need to be corrected (probably by adding 1900 to the result) before they can be passed to any Date::Manip routine. 👑

🔮 FUTURE IDEAS 🔮

A number of changes are being considered for future inclusion in Date::Manip. As a rule, the changes listed below are not finalized, and are open to discussion. 👀

🗣️ Rewrite parsing for better language support 🗣️

Currently, all of Date::Manip's parsing is based on English language forms of dates, even if the words have been replaced by the equivalent in some other language.

The author is considering rewriting the parsing routines in order to allow date forms that might be used in other languages but do not have a common English equivalent, and to account for the fact that some English formats may not have an equivalent in another language. 🌈

🎯 Adding granularity 🎯

The granularity of a time basically refers to how accurate you wish to treat a date. For example, if you want to compare two dates to see if they're identical at a granularity of days, then they only have to occur on the same day. At a granularity of an hour, they have to occur within an hour of each other, etc.

Not sure how useful this would be, but it's one of the oldest unimplemented ideas, so it's not being discarded completely. 💖

💖 ACKNOWLEDGMENTS 💖

Okay so bestie, real talk: there are SO many people who have contributed to Date::Manip over the years and I gotta thank them. The biggest contributions have literally come in the form of suggestions and bug reports from users. I tried my absolute best to include the name of every person who first suggested each improvement or first reported each bug — those are all tucked into the Date::Manip::Changes5 and Date::Manip::Changes6 documents. The list is just too long to fit here, but I appreciate every single one of y'all's help. 🫶

A bunch of people have also made suggestions or reported bugs that are not mentioned in those documents. That includes suggestions that never got implemented, and people who made a suggestion or bug report that someone else already made. For those whose suggestions haven't been implemented yet, they'll get added to the appropriate Changes document when (if) their suggestions get implemented. I keep every single suggestion I've ever received, no cap, and I periodically go back through the unimplemented ones to see if it's something I'm interested in. So even suggestions from years ago might still show up in future versions of Date::Manip, and the original requester gets attributed at that point (some of the changes made to Date::Manip 6.00 were based on suggestions 10 years old which never fit in with version 5.xx, but which I knew I wanted to implement). And for everyone who sent in requests/reports that someone else already made — thank you too. I'd much rather have a suggestion made twice than not at all. fr fr.

Thanks to Alan Cezar and Greg Schiedler for paying me to implement the Events_List routine. They gave me the idea, and then were willing to pay me for my time to get it implemented quickly. iconic behavior honestly. 💅

I'd also like to thank a couple of authors. Date::Manip has gotten some really good press in a couple of books, and since no one's paying me to write Date::Manip, seeing my module get a good review in a book written by someone else really makes my day. My thanks to Nate Padwardhan and Clay Irving (Programming with Perl Modules -- part of the O'Reilly Perl Resource Kit); and Tom Christiansen and Nathan Torkington (The Perl Cookbook). Also, thanks to any other authors who've written about Date::Manip whose books I haven't seen. 📚✨

I'd also like to thank the people who are maintaining the zoneinfo database (and who replied quickly to several inquiries). you're doing the lord's work, truly. 🌍

I have borrowed from other modules. I originally borrowed the code for determining if a year was a leap year from code written by David Muir Sharnoff. I borrowed many of the original date printf formats from code written by Terry McGonigal as well as the Solaris date command. More recently, I borrowed the code to do time zone registry lookups on Windows from the DateTime-TimeZone module, though I rewrote it to work better with Date::Manip. 🦋

🐛 BUGS AND QUESTIONS 🐛

Please refer to the Date::Manip::Problems documentation for information on submitting bug reports or questions to the author. we love a good bug report, bestie. 💌

👀 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 the whole page, bestie!! 🎀 this lil doc is from perl v5.42.3, dated 2026-09-01, and it's the Date::Manip::Misc(3) manpage. go forth and manipulate some dates, you gorgeous genius. 💖✨

📦 where this page comes from

fedora 43: perl-Date-Manip 7.00-1.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
fedora 44: perl-Date-Manip 7.00-1.fc44 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms