Module:...DateTime(3)

💖 NAME 💖

okay bestie, welcome to the Module::Generic::DateTime(3) page from the User Contributed Perl Documentation ✨ This is Module::Generic::DateTime — a DateTime wrapper with enhanced features, and she's literally serving convenience 💅

✨ SYNOPSIS ✨

Here's the whole vibe in code, exactly as written 🫶

use Module::Generic::DateTime;

my $dt = DateTime->new;
my $gdt = Module::Generic::DateTime->new( $dt );
# or directly will instantiate a default DateTime value based on DateTime->now
my $gdt = Module::Generic::DateTime->new;

# Now you can do operations that are not normally possible with DateTime
# Compare a dt object with a unix timestamp
if( $gdt > time() )
{
    # do something
}
elsif( $gdt < '2020-03-01 07:12:10+0900' )
{
    # do something
}
# and of course, comparison with other dt works as before
elsif( $gdt >= $dt )
{
    # do something
}

# Remove 10 seconds from time object
$gdt -= 10;
# Add 5 seconds and get a new object
my $dt2 = $gdt + 5;

# Get the difference as an interval between two objects
my $interval = $dt1 - $dt2;
# DateTime::Duration are represented by Module::Generic::DateTime::Interval
# and extra manipulations are possible
# Add 7 seconds
$int += 7;
# Change the days
$int->days( 5 );
# or using lvalue
$int->days = 5;
# or multiply everything (years, months, weeks, days, hours, minutes, seconds and nanoseconds) in the interval by 2
$int *= 2
# Multiply one interval by another:
my $new_interval = $int1 * $int2;
# or multiply with assignment
$int1 *= $int2;
# Then add the interval to the datetime object
$dt += $int;

🎀 VERSION 🎀

v0.6.2 — periodt.

🌸 DESCRIPTION 🌸

Module::Generic::DateTime is a thin wrapper around DateTime to provide additional features as exemplified above.

It also enables the DateTime object to be thawed and frozen and converted to JSON with the respective methods STORABLE_freeze, STORABLE_thaw, TO_JSON.

All other method calls not in this API are passed to DateTime using AUTOLOAD with the added benefit that, if a method called triggers a fatal exception, it is caught using Nice::Try try-catch block and an error is set and return is returned instead. lowkey iconic error handling 😭👑

🛠️ CONSTRUCTOR 🛠️

new

Provided with an optional DateTime object and this returns a new instance of Module::Generic::DateTime.

If no DateTime object was provided, this will instantiate one implicitly and set the formatter to stringify it to an iso8601 string, such as: 2022-03-08T14:22:10+0000. By default the instantiated DateTime object use the default time zone, which is GMT. You can change the time zone afterward using set_time_zone in DateTime:

$dt->set_time_zone( 'Asia/Tokyo' );

from_epoch

my $d = Module::Generic::DateTime->from_epoch( epoch => $unix_timestamp );

Instantiate a new Module::Generic::DateTime using the DateTime method from_epoch. Any parameters are passed through to from_epoch in DateTime.

If a DateTime error occurs, it will be caught and an error will be set and undef will be returned.

now

my $d = Module::Generic::DateTime->now;

Instantiate a new Module::Generic::DateTime using the DateTime method now. Any parameters are passed through to now in DateTime.

If a DateTime error occurs, it will be caught and an error will be set and undef will be returned.

🧚 METHODS 🧚

as_string

This is an alias to stringify.

datetime

Sets or gets the underlying DateTime object.

op

This method is called to overload the following operations:

• "" stringification
• bool
• ">" greater than
• ">=" greater or equal than
• "<" lower than
• "<=" lower or equal than
• "==" euqal — that's exactly how the doc spells it, bestie 💀
• "!=" not equal
• "-" minus
• "+" plus

op_minus_plus

This method handles cases of overloading for minus and plus.

🦋 SERIALISATION 🦋

Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE, THAW, STORABLE_freeze and STORABLE_thaw.

Additionally, upon loading Module::Generic::DateTime, it will ensure the following DateTime modules also have a FREEZE and THAW subroutines if not defined already:

• DateTime
• DateTime::TimeZone
• DateTime::TimeZone::OffsetOnly
• DateTime::Locale::FromData
• DateTime::Locale::Base

🧵 THREAD & PROCESS SAFETY 🧵

Module::Generic::DateTime is designed to be fully thread-safe and process-safe, ensuring data integrity across Perl ithreads and mod_perl’s threaded Multi-Processing Modules (MPMs) such as Worker or Event. It relies on Module::Generic::Global for thread-safe storage of shared state and employs synchronisation mechanisms to prevent data corruption and race conditions. no cap 🧵✨

Synchronisation Mechanisms

• Shared State — The module uses Module::Generic::Global to cache the availability of the system’s local timezone in the local_tz namespace, storing a boolean (0 or 1) indicating whether the local timezone is supported. This repository is :shared when CAN_THREADS is true (Perl supports ithreads), protected by lock in perlfunc for Perl threads or APR::ThreadRWLock for mod_perl threaded MPMs without threads. In non-threaded environments, the repository is shared across processes, requiring no additional synchronisation.
• DateTime Operations — Methods like op and op_minus_plus perform timezone checks and DateTime operations, which are thread-safe as they rely on Module::Generic::Global’s synchronisation. The underlying DateTime module is thread-safe for most operations, and this module ensures no shared mutable state is accessed without proper locking.

Context Key Isolation

The local_tz namespace uses a class-level key (<class>), where class is Module::Generic::DateTime. This ensures timezone support is cached across processes, with no thread-specific granularity needed, as timezone availability is a global property. The key format enables cross-process sharing, and threaded environments (HAS_THREADS true) maintain isolation via Module::Generic::Global’s synchronisation.

mod_perl Considerations

• Prefork MPM — Data is cross-process, requiring no additional synchronisation, as all processes share the same local_tz repository.
• Threaded MPMs (Worker/Event) — The local_tz repository is shared across threads and processes, protected by Module::Generic::Global’s synchronisation. Users should call Module::Generic::Global-`cleanup_register> in mod_perl handlers to clear the repository after requests, preventing memory leaks in long-running processes.
• Thread-Unsafe Functions — Avoid Perl functions like localtime, readdir, srand, or operations like chdir, umask, chroot in threaded MPMs, as they may affect all threads. Consult perlthrtut (http://perldoc.perl.org/perlthrtut.html) and mod_perl documentation (https://perl.apache.org/docs/2.0/user/coding/coding.html#Thread_environment_Issues) for details.

Thread-Safety Considerations

The module’s thread-safety relies on:

• Shared Repository — The local_tz namespace is initialised as :shared when CAN_THREADS is true, ensuring safe access across threads and processes.
• Locking — lock in perlfunc or APR::ThreadRWLock protects all read/write operations to the repository.
• Immutable State — Beyond local_tz, the module avoids shared mutable state, relying on DateTime’s thread-safe operations.

In environments where %INC manipulation (e.g., by forks) emulates threads, HAS_THREADS and IN_THREAD may return true. This is generally safe, as forks provides a compatible tid method, but users in untrusted environments should verify $INC{'threads.pm'} points to the actual threads module.

For maximum safety, users running mod_perl with threaded MPMs should ensure Perl is compiled with ithreads and explicitly load threads, or use Prefork MPM for single-threaded operation.

👀 SEE ALSO 👀

• Module::Generic
• Module::Generic::DateTime::Interval
• DateTime
• DateTime::Format::Strptime
• DatetTime::TimeZone — yes, exactly like that; the extra “t” is in the doc, bestie 🙈

💌 AUTHOR 💌

Jacques Deguest <jack@deguest.jp> — say hi, bestie 🫶

©️ COPYRIGHT & LICENSE ©️

Copyright (c) 2000-2024 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself. slay 💅

---

okay that's the whole page, bestie 💖 this one came from perl v5.42.2, dated 2026-02-15, and the manual is Module:...DateTime(3). bye bestie, go compare some timestamps ✨🦋