Date::M...Objects(3)

💅 NAME 💅

Date::Manip::Objects — a full tour of the various Date::Manip objects, and how they all link up 💖

(psst, you're reading the Date::Manip::Objects(3) page from the User Contributed Perl Documentation collection 🫶)

---

✨ SYNOPSIS ✨

okay so the Date::Manip package isn't one single module, it's a whole squad — several modules, and each one does its thing on a specific class of objects. This document is basically the group chat where we explain how all those modules vibe together 🌸

---

🎀 DESCRIPTION 🎀

Date::Manip is made up of these primary modules, bestie:

🌸 Date::Manip::Obj

Date::Manip::Obj is not meant to be used directly, okay? It's the base class for literally every other Date::Manip class described below.

It holds functions that all of these classes inherit, so if you wanna understand every method available to any of the classes below, you gotta include the ones documented in the Date::Manip::Obj class too. iykyk ✨

🌸 Date::Manip::Base

Date::Manip::Base handles the basic operations: basic date operations, managing configuration options, handling the definitions used in different languages, etc.

Here's the thing though — a Date::Manip::Base object does not, by itself, contain any date information. Nope. Instead it holds configuration information which decides how the Date::Manip package performs date operations. All that configuration info is documented in the Date::Manip::Config document.

And there's one more property of the Base object that's very important. When it's doing basic date operations, some intermediate results get cached in the object, and that leads to significant performance increases in later operations. So bestie, it's important to reuse the object as much as possible instead of creating new Date::Manip::Base objects all the time. It's giving efficiency 💅

A lot of the info in this document is about exactly that issue, and it tells you how to create the various higher-level objects so you get the most efficient reuse of this cached data.

Because all the other objects depend on a Base object, a Base object is embedded in all of them, and the same Base object can be shared by any number of objects to achieve maximum performance 🔥

🌸 Date::Manip::TZ

Date::Manip::TZ adds time zone support. It's used to verify date and time zone information, convert dates from one time zone to another, and handle all daylight saving time transitions.

Just like the Base object, a great deal of information gets cached in the TZ object. That includes lists of all time zones, offsets, and abbreviations for all time zones. It also includes a more detailed description of every time zone that's actually been used.

A TZ object relies on a Base object — and a Base object is always embedded in a TZ object, no exceptions. And all the higher level objects (the ones listed next) depend on both a Base and a TZ object, so a TZ object is embedded in them.

To get maximum performance and minimize memory usage, a TZ object can be shared by any number of higher level objects, and honestly it's desirable to reuse the same TZ object as often as you possibly can. periodt 🌟

🌸 Date::Manip::Date / Date::Manip::Delta / Date::Manip::Recur

These are the primary modules for all your high level date operations.

• Date::Manip::Date does operations on dates (which includes a date, time, and time zone).
• Date::Manip::Delta does operations with deltas (amounts of time).
• Date::Manip::Recur does operations on recurring events.

As I said up there, each of these high level classes relies on both a TZ object and a Base object, so a TZ object is embedded in each one (and that TZ object has a Base object embedded in it — it's turtles all the way down 🐢).

A Date::Manip::Date object contains a single date, so to work with multiple dates you're gonna need multiple Date::Manip::Date objects. But to make the most effective use of the cached information in the Base object, the same TZ object can be embedded in each of the higher level objects.

Same goes for multiple Date::Manip::Delta and Date::Manip::Recur objects ✨

There are also many secondary modules, including:

• Date::Manip::TZ_Base
• Date::Manip::TZdata
• Date::Manip::Zones
• Date::Manip::Lang::*
• Date::Manip::TZ::*
• Date::Manip::Offset::*

None of these are intended to be used directly, bestie. Hands off 🙈

---

🦋 WORKING WITH DATE::MANIP OBJECTS (SINGLE CONFIGURATION) 🦋

By far the most common way people use Date::Manip is: set one local time zone, parse dates in one language, and have every other configuration parameter set to a single value that never changes over the course of the program.

Whenever that's your situation, you can use the methods listed in this section to create any number of Date::Manip objects. It'll automatically optimize the use of cached data so you get the best performance 💖

If you do need to work with multiple different configurations (like parsing dates from multiple languages), please refer to the next section, "WORKING WITH DATE::MANIP OBJECTS (MULTIPLE CONFIGURATION)".

💜 Working with high level objects

The most common situation is one where you need one or more high level objects (Date, Delta, or Recur objects). On top of that, you might also wanna use the lower level (Base or TZ) objects.

First thing you should do is create your initial object. Create the highest level object you'll be using. For example, if you'll be working with dates, create the first date object with:

   $date = new Date::Manip::Date;

Next step is to set the configuration values. Use the config method to do that:

   $date->config(ARGS);

You can call the config method later, but it's strongly suggested that you set the configuration soon after the initial object is created and not alter it later. Every single time you alter the configuration, some of the cached data gets cleared, so for optimal performance you don't wanna alter the configuration if you can help it 😭

Additional high-level objects can be created with these calls:

   $date2 = $date->new_date();
   $delta = $date->new_delta();
   $recur = $date->new_recur();

To access the embedded Date::Manip::TZ and Date::Manip::Base objects, use these calls:

   $tz    = $date->tz();
   $base  = $date->base();

💜 Working with low level objects only

If you'll only be working with low level objects, create them with one of these calls:

   $tz    = new Date::Manip::TZ;
   $base  = new Date::Manip::Base;

To get the base object embedded in a Date::Manip::TZ object, use:

   $base  = $tz->base();

For a more complete description of the methods used here, go check out the Date::Manip::Obj document 🫶

---

🌈 WORKING WITH DATE::MANIP OBJECTS (MULTIPLE CONFIGURATION) 🌈

Sometimes it's useful to have multiple sets of configurations. To do that, you have to create multiple Date::Manip::Base objects (each one with its own set of configuration options), and then create new Date::Manip objects with the appropriate Date::Manip::Base object embedded in them.

Possible reasons include:

💜 Parsing multiple languages

A Date::Manip::Base object includes information about a single language. If you need to parse dates from two (or more) languages, you need a Date::Manip::Base object for each one. You could do it like this:

   $date_eng1 = new Date::Manip::Date;
   $date_eng1->config("language","English");

   $date_spa1 = new Date::Manip::Date;
   $date_spa1->config("language","Spanish");

Any additional Date::Manip objects created from the first one will work with English. Additional objects created from the second one will work in Spanish. Slay, bilingual icon 💅

💜 Business modes for different countries and/or businesses

If you're doing business mode calculations (see Date::Manip::Calc) for two different businesses that have different holiday lists, work weeks, or business days, you can create different objects which read different config files (see Date::Manip::Config) with the appropriate description of each one.

The primary issue when you're dealing with multiple configurations is that you, the programmer, have to manually keep track of which Date::Manip objects work with each configuration. For example, look at these lines:

   $date1 = new Date::Manip::Date [$opt1,$val1];
   $date2 = new Date::Manip::Date $date1, [$opt2,$val2];
   $date3 = new Date::Manip::Date $date1;
   $date4 = new Date::Manip::Date $date2;

The first line creates 3 objects: a Date::Manip::Base object, a Date::Manip::TZ object, and a Date::Manip::Date object. That Date::Manip::Base object has the configuration set to contain the value(s) passed in as the final list reference argument.

The second line creates 3 new objects (a second Date::Manip::Base object, a second Date::Manip::TZ object, and a second Date::Manip::Date object). Since a list reference containing config variables is passed in, a new Date::Manip::Base object is created, rather than reusing the first one. That second Date::Manip::Base object contains all the config from the first, plus the config variables passed in in the list reference argument.

The third line creates another Date::Manip::Date object which uses the first Date::Manip::Base and Date::Manip::TZ objects embedded in it.

The fourth line creates another Date::Manip::Date object which uses the second Date::Manip::Base and Date::Manip::TZ objects embedded in it.

Most of the time there'll only ever be one set of configuration options in play, so all this complexity is really for a very special — and not widely used — bit of functionality. But now you know it exists, bestie 👑

heads up: this page isn't done yet, there's more coming in part 2 🌸

✨ WORKING WITH DATE::MANIP OBJECTS (ADDITIONAL NOTES) ✨

---

🎀 object reuse 🎀

okay bestie, listen, this is the most important little habit ever: if you wanna make another Date::Manip object, you pass a previously created object in as the first argument. that way the same Base object gets embedded in both of them, so the cached intermediate results get reused to the max, and your performance is so much better. like:

$date1 = new Date::Manip::Date;
$date2 = new Date::Manip::Date $date1;

this matters for two reasons and both of them are lowkey huge.

first: memory usage. the Date::Manip::Base object is quite large. it stores a big ol' pile of precompiled regular expressions for language parsing, and as you do date operations, intermediate results get cached so they can be reused later to improve performance. and the Date::Manip::TZ object? even bigger — it's got info about all known time zones indexed several different ways (by offset, by abbreviation, etc.). and as time zones actually get used, a description of all of the time change rules gets loaded and added to this object too.

so because these objects are so big, reusing them is the whole vibe — do not be out here creating a million copies of them. 💀 and just so you know: because these objects are embedded in each of the high level objects (Date::Manip::Date, for example), it makes those objects look quite large.

second reason: performance. since intermediate results are cached in there, lots of date operations only need to be done once, and then they can be reused any number of times. essentially it's doing the same function as the Memoize module, but in a more efficient manner. Memoize caches results for function calls. for Date::Manip, that would often work, but if you change a config variable, the return value may change, so Memoize could cause things to break. plus Memoize caches primarily at the function level, whereas Date::Manip stores cached intermediate results wherever a performance increase is seen. every time the author considers caching a result, he runs a test to see if it increases performance. if it doesn't, or it doesn't make a significant impact, it doesn't get cached.

and because the caching is quite finely tuned, it's much more efficient than using a generic (though useful) tool like Memoize. periodt. 💅

---

🦋 configuration changes 🦋

general rule, bestie: only pass in configuration options when the first object is created. in other words, this whole behavior is discouraged:

$date = new Date::Manip::Date;
$date->config(@opts);

... do some stuff

$date->config(@opts);

... do some other stuff

why? because some of the cached results are configuration specific, so when a configuration change is made, some of the cached data has to be thrown out, which means those results gotta get recalculated. 🙈

if you really need to change configuration in the middle of execution, it's certainly allowed of course — no one's stopping you — but if you can define the configuration once, right after the object is first created, and then leave the configuration alone, performance will be optimized. ✨

---

😭 BUGS AND QUESTIONS 😭

please refer to the Date::Manip::Problems documentation for info on submitting bug reports or questions to the author. they wanna hear from you fr fr 🫶

---

👑 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. slay. 💖

---

⭐ AUTHOR ⭐

Sullivan Beck (https://github.com/SBECK-github/)

---

and that's the whole page, bestie!! 🎀 this was rendered from perl v5.42.3, dated 2026-09-01 — yes the footer says Date::M...Objects(3) but you and me both know what it really is 💅 go forth and reuse your objects, mwah 🦋💜