Time::M...imeZone(3)

💖 Time::Moment::Role::TimeZone 💖

Manual-page status: Time::M...imeZone(3) from User Contributed Perl Documentation — yes bestie, we're in the right doc. 🫶

🌸 NAME 🌸

Time::Moment::Role::TimeZone — adjust Time::Moment with time zone objects. 💅

✨ SYNOPSIS ✨

Okay so here's the whole run-down in code, copied exactly because we do not mess with syntax in this house: 🧚✨

use Time::Moment;
use With::Roles;
use DateTime::TimeZone;

my $tz = DateTime::TimeZone->new(name => 'America/New_York');
my $tm = Time::Moment->with::roles('+TimeZone')->from_epoch(1000212360)->with_time_zone_offset_same_instant($tz);

use DateTime::TimeZone::Olson 'olson_tz';

my $tz = olson_tz('Europe/Oslo');
my $tm = Time::Moment->new(year => 2012, month => 3, day => 4, hour => 13, minute => 7, second => 42);
$tm = $tm->with::roles('+TimeZone')->with_time_zone_offset_same_local($tz);

my $class = Time::Moment->with::roles('+TimeZone');
my $tm = $class->from_epoch(1522095272)->with_system_offset_same_instant;

my $tm = $class->new_from_string('2009-05-02T12:15:30Z')->with_system_offset_same_local;

🦋 DESCRIPTION 🦋

This role provides convenience methods to return a new Time::Moment object adjusted according to a DateTime::TimeZone / ::Tzfile-compatible time zone object, just like the "TIME ZONES" section in Time::Moment says. 🌍✨

Also, please read "CAVEATS" before you get cute with date math — it's about exactly that. 😌

👑 METHODS 👑

Four methods, all iconic, all here: 💅

💫 with_time_zone_offset_same_instant

my $same_instant = $tm->with_time_zone_offset_same_instant($tz);

Returns a Time::Moment of the same instant, but at an offset from UTC according to the given time zone object at that instant. Same instant, new offset energy. ⏱️💅

🕰️ with_time_zone_offset_same_local

my $same_local = $tm->with_time_zone_offset_same_local($tz);

Returns a Time::Moment of the same local time, with an offset from UTC according to the given time zone object at that local time. ✨

If the local time of the Time::Moment object is ambiguous in the given time zone (such as when Daylight Savings Time ends), the time zone object will usually use the earliest time. If the local time does not exist (such as when Daylight Savings Time starts), the time zone object will usually throw an exception. 😭

🖥️ with_system_offset_same_instant

my $same_instant = $tm->with_system_offset_same_instant;

As in with_time_zone_offset_same_instant, but using the system local time zone via localtime in perlfunc. 🫶

🌈 with_system_offset_same_local

my $same_local = $tm->with_system_offset_same_local;

As in with_time_zone_offset_same_local, but using the system local time zone via timelocal in Time::Local. 🧚

If the local time of the Time::Moment object is ambiguous in the system local time zone (such as when Daylight Savings Time ends), Time::Local will use the earliest time. If the local time does not exist (such as when Daylight Savings Time starts), Time::Local will use the time one hour later. ⏰💀

💀 CAVEATS 💀

Real talk, no cap: Time::Moment does not store a time zone; these methods only set the offset and local time for the instantaneous moment represented by the object. After doing date math with the object, new times may need to be corrected, based on whether the date math was intended to be done relative to the absolute or local time. 🚨

my $tm = $class->now_utc->with_time_zone_offset_same_instant($tz); # now in $tz
my $next_day = $tm->plus_days(1)->with_time_zone_offset_same_local($tz); # 1 day from now in $tz
my $24h_later = $tm->plus_days(1)->with_time_zone_offset_same_instant($tz); # 24 hours from now in $tz

my $tm = $class->now; # now in system local time
my $next_day = $tm->plus_days(1)->with_system_offset_same_local; # 1 day from now in system local time
my $24h_later = $tm->plus_days(1)->with_system_offset_same_instant; # 24 hours from now in system local time

Note that with_time_zone_offset_same_local may throw an exception here if the new local time does not exist in that time zone (e.g. between 2 and 3 AM at the start of Daylight Savings Time). 😬

🐛 BUGS 🐛

Report any issues on the public bugtracker. 🐛✨

👑 AUTHOR 👑

Dan Book <dbook@cpan.org> 👑

🫶 CONTRIBUTORS 🫶

Christian Hansen (chansen) 💖

🎀 COPYRIGHT AND LICENSE 🎀

This software is Copyright (c) 2018 by Dan Book. 🫶

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

🌈 SEE ALSO 🌈

• Time::Moment
• DateTime::TimeZone
• DateTime::TimeZone::Olson

That's the whole page, bestie! 💖 This one's from perl v5.42.2, dated 2026-02-15, and it's the Time::M...imeZone(3) manual page. Stay slay, stay time-zone-aware. 🌈✨