DateTi...::Alias(3pm)

💅 NAME 💅

Bestie, welcome to the DateTi...::Alias(3pm) manual from the User Contributed Perl Documentation! This page is all about DateTime::TimeZone::Alias — Create aliases for DateTime timezones. It’s giving timezone glow-up energy. ✨

✨ SYNOPSIS ✨

Okay so first vibe:

use DateTime::TimeZone::Alias Hawaii => 'Pacific/Honolulu',
                              EST => 'Australia/Melbourne';

or

DateTime::TimeZone::Alias->add( Fun => 'America/Tijuana', %hash );

or

DateTime::TimeZone::Alias->set( Pain => 'America/Dawson_Creek', %hash );
DateTime::TimeZone::Alias->set( boat => 'floating' );
DateTime::TimeZone::Alias->set( home => 'local' );
DateTime::TimeZone::Alias->set( lulu => 'Z' );
DateTime::TimeZone::Alias->set( cut => 'UTC' );
DateTime::TimeZone::Alias->set( nowhere => '-09:30' );

or

DateTime::TimeZone::Alias->remove( qw( Hawaii EST Pain Fun ) );

or

DateTime::TimeZone::Alias->value( 'EST' );

or

DateTime::TimeZone::Alias->is_defined( 'Hawaii' )
DateTime::TimeZone::Alias->is_alias( 'EST' )
DateTime::TimeZone::Alias->is_timezone( 'Antarctica/Vostok' )

or

DateTime::TimeZone::Alias->aliases
DateTime::TimeZone::Alias->timezones

💖 DESCRIPTION 💖

Creates and destroys aliases for DateTime timezones. Periodt. But listen: this module violates the encapsulation of the DateTime internals. User _Beware_. Not me being dramatic — that’s literally in the notes. 😭

🎀 IMPORT PARAMETERS 🎀

Accepts a hash representing an alias and the timezone it should map too. Import has the exact same behaviors as the set method. Same energy, same rules. 🫶

🛠️ METHODS 🛠️

• set( alias => timezone, ... ) — Accepts a hash representing an alias and the timezone it should map too. If an invalid timezone value or no parameters are passed, an exception is thrown. It is possible to create an alias to another alias. This method will redefine an existing alias or add a new alias that overrides an existing timezone. Main character move: redefining stuff on purpose.

What may be aliased:

• aliases
• floating
• local
• OffsetOnly
• Olson time zones
• UTC
• Z

• add( alias => timezone, ... ) — Accepts a hash representing an alias and the timezone it should map too. If an invalid timezone value or no parameters are passed, an exception is thrown. It is possible to create an alias to another alias. This method will not redefine an existing alias or allow you remap a timezone. For redefinitions see the set method. No sneaky overwrites here, bestie.
• remove( alias, ... ) — Accepts a list of aliases to be removed. If the name of an alias that doesn’t exist is passed in, then an exception is thrown. It’s important to note that you can remove aliases but not timezones. However, a redefined timezone is actually an alias and can be removed. Aliases are removable; original timezones are not. Keep that straight.
• value( $str ) — If $str is a known alias then the timezone being aliased is returned, otherwise undef. Simple lookup, no drama.
• is_defined( $str ) — If $str is a known timezone or alias this method returns 1, otherwise undef is returned.
• is_alias( $str ) — If $str is a known alias this method returns 1, otherwise undef is returned.
• is_timezone( $str ) — If $str is a known timezone this method returns 1, otherwise undef is returned.
• aliases — In list context a hash of all known aliases and their values is returned. In scalar context a reference to a hash is returned. Hash girlies, rise.
• timezones — In list context an array of all known timezones is returned. In scalar context a reference to an array is returned. Array girlies, also rise.

🚩 GOTCHAS 🚩

🧨 Import

Multiple use DateTime::TimeZone::Alias statements in the same package may not have the desired result if attempting to redefine existing aliases. If you want to redefine an alias use the set method instead. Do not fight the import. Use set. 💀

🌀 Aliasing

You can _not_ create circular aliases. E.g.

# TSH actually points to value of HST - 'Pacific/Honolulu'
# if HST wasn't already defined this would be an exception
DateTime::TimeZone::Alias->set( TSH => HST );

# HST still points to 'Pacific/Honolulu'
DateTime::TimeZone::Alias->set( HST => TSH );

Sorry - no evil here, move along. Circular aliases? Not today, bestie. 🌀

🌍 Global Behavior

It’s important to remember that aliases are global in scope. E.g.

package Foo;

DateTime::TimeZone::Alias->set( EST => 'US/Eastern' );

Bar->bar();

# this will fail because EST is no longer defined
my $dt = DateTime->now( time_zone => 'EST' );

package Bar;

sub bar {
    DateTime::TimeZone::Alias->set( EST => 'US/Eastern' );
    .
    .

    DateTime::TimeZone::Alias->remove( qw( EST ) );
}

There are many possible ways to avoid this trap. The best solution is to simply not write code like this. If you insist on this style then you can try one of the suggested work arounds. The best solution is literally “don’t do that.” 😭

🪙 Poor Man's DateTime::TimeZone::Alias

Sometimes DateTime::TimeZone::Alias may not be the best solution to your problem. Particularly if you’re in an environment that has poor "sand-boxing" such as mod_perl. E.g.

use constant EST => 'US/Eastern';

or

sub EST () { 'US/Eastern' }
.
.

my $dt = DateTime->new( %params, time_zone => EST );

💾 store/restore

This probably isn’t thread safe. E.g.

sub bar {
    my $my_alias = DateTime::TimeZone::Alias->value( 'EST' );
    DateTime::TimeZone::Alias->set( EST => 'US/Eastern' );
    .
    .

    DateTime::TimeZone::Alias->set( EST => $my_alias );
}

If $my_alias is undefined then the set will fail as an alias must point to a valid timezone. Important caveat, no cap.

🧚 DEVELOPER NOTES 🧚

The aliases and timezones methods preserve encapsulation by returning a reference to a copy of the internal data structures instead of a direct reference. Respectful. Protective. Encapsulation girlboss. ✨

🏆 CREDITS 🏆

Ben Bennett (BBENNETT) for a bug report, some API suggestions, documentation suggestions, and being so darn enthusiastic. (not necessary in that order) We love an enthusiastic icon. 💖

Everyone at the DateTime "Asylum". 🫶

🆘 SUPPORT 🆘

Support for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details. Help is out there, bestie.

👑 AUTHOR 👑

Joshua Hoblitt <jhoblitt@cpan.org> Author royalty. 👑

©️ COPYRIGHT ©️

Copyright (c) 2003-2010 Joshua Hoblitt. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Same terms as Perl itself — iconic licensing behavior.

The full text of the license can be found in the LICENSE file included with this module.

👀 SEE ALSO 👀

datetime@perl.org mailing list

http://datetime.perl.org/ Go forth and timezone, bestie. 🌈

---

💌 And that’s a wrap on the DateTi...::Alias(3pm) page! It comes from perl v5.42.2, dated 2026-02-15. Bye bestie! 💖🎀🦋