info > DateTime::TimeZone

man perldoc info pydoc3 ri search

🗂️ NAME

DateTime::TimeZone — Time zone object base class and factory

🚀 Quick Reference

Use Case	Command	Description
📦 Create a time zone object	DateTime::TimeZone->new( name => 'America/Chicago' )	Returns a new time zone object for the given Olson name
⏱️ Get offset for a datetime	$tz->offset_for_datetime($dt)	Returns UTC offset in seconds (including DST)
🌐 Get all time zone names	DateTime::TimeZone->all_names()	Returns list of all Olson time zone names
🏷️ Get short name (EST, GMT)	$tz->short_name_for_datetime($dt)	Returns display abbreviation like "EST"
🔍 Check if a name is valid	DateTime::TimeZone->is_valid_name($name)	Returns boolean validity of time zone name
📂 List zones in a country	DateTime::TimeZone->names_in_country('us')	Returns zones for a two-letter ISO country code
🏠 Determine local time zone	DateTime::TimeZone->new( name => 'local' )	Attempts to auto-detect system's local time zone

📜 VERSION

version 2.51

📝 SYNOPSIS

use DateTime;
use DateTime::TimeZone;

my $tz = DateTime::TimeZone->new( name => 'America/Chicago' );

my $dt = DateTime->now();
my $offset = $tz->offset_for_datetime($dt);

📖 DESCRIPTION

This class is the base class for all time zone objects. A time zone is represented internally as a set of observances, each of which describes the offset from GMT for a given time period.

Note that without the DateTime module, this module does not do much. Its primary interface is through a DateTime object, and most users will not need to directly use DateTime::TimeZone methods.

🖥️ Special Case Platforms

• 🔧 Win32: Install DateTime::TimeZone::Local::Win32 to enable specifying a time zone of 'local' when creating a DateTime object.
• 🔧 HPUX: Install DateTime::TimeZone::HPUX for support for HPUX style time zones like 'MET-1METDST'.

⚙️ USAGE

This class has the following methods:

🆕 DateTime::TimeZone->new( name => $tz_name )

Given a valid time zone name, returns a new time zone blessed into the appropriate subclass. Subclasses are named for the given time zone, so that the time zone "America/Chicago" is the DateTime::TimeZone::America::Chicago class.

If the name is a "link" name in the Olson database, the object created may have a different name. For example, there is a link from the old "EST5EDT" name to "America/New_York".

When loading from the Olson database, the constructor checks the version of the loaded class against the current DateTime::TimeZone installation. If they do not match it will issue a warning.

Special name values:

• 🪶 "floating" — returns a DateTime::TimeZone::Floating object (no offset, always same time). Useful for calendaring applications (RFC 2445).
• 🌍 "UTC" — returns a DateTime::TimeZone::UTC object.
• 🔢 Offset string — converted to a number, returns a DateTime::TimeZone::OffsetOnly object.
• 🏠 "local" — attempts to determine the local time zone for the system. The method varies by OS:

• DateTime::TimeZone::Local::Unix
• DateTime::TimeZone::Local::Android
• DateTime::TimeZone::Local::hpux
• DateTime::TimeZone::Local::Win32
• DateTime::TimeZone::Local::VMS

If a local time zone is not found, an exception is thrown (stringifies to "Cannot determine local time zone"). Falling back to UTC is a reasonable alternative. When writing tests, avoid using local or set $ENV{TZ} to a known value.

⏱️ $tz->offset_for_datetime( $dt )

Given a DateTime object, returns the offset in seconds for the given datetime. Takes into account historical time zone information and DST. The offset is determined by looking at the object's UTC Rata Die days and seconds.

⏱️ $tz->offset_for_local_datetime( $dt )

Given a DateTime object, returns the offset in seconds using the local time's Rata Die days and seconds. Should only be used when the corresponding UTC time is not yet known, because local times can be ambiguous due to DST.

🌞 $tz->is_dst_for_datetime( $dt )

Returns true if the DateTime is currently in Daylight Saving Time.

🏷️ $tz->name

Returns the name of the time zone.

🏷️ $tz->short_name_for_datetime( $dt )

Returns the "short name" for the current observance and rule (e.g., "EST", "GMT"). Warning: Do not rely on these names for anything other than display. They are not official, and many are inventions of the Olson database maintainers. Names are not unique (e.g., "EST" exists at both -0500 and +1000/+1100).

🪶 $tz->is_floating

Returns a boolean indicating whether this object represents a floating time zone (RFC 2445).

🌍 $tz->is_utc

Indicates whether this object represents the UTC (GMT) time zone.

🔄 $tz->has_dst_changes

Indicates whether this zone has ever had a change to and from DST, either in the past or future.

🗺️ $tz->is_olson

Returns true if the time zone is a named time zone from the Olson database.

📂 $tz->category

Returns the part of the time zone name before the first slash (e.g., "America" for "America/Chicago").

✅ DateTime::TimeZone->is_valid_name($name)

Given a string, returns a boolean indicating whether the string is a valid time zone name (including aliases if using DateTime::TimeZone::Alias).

📋 DateTime::TimeZone->all_names

Returns a pre-sorted list of all time zone names (excluding link names). In scalar context returns an array reference, in list context returns an array.

📂 DateTime::TimeZone->categories

Returns a list of all time zone categories. In scalar context returns an array reference, in list context returns an array.

🔗 DateTime::TimeZone->links

Returns a hash of all time zone links, where keys are old deprecated names and values are new names. In scalar context returns a hash reference, in list context returns a hash.

🗂️ DateTime::TimeZone->names_in_category( $category )

Given a valid category, returns a list of names in that category, without the category portion. For example, "America" category returns "Chicago", "Kentucky/Monticello", "New_York". In scalar context returns an array reference, in list context returns an array.

🌐 DateTime::TimeZone->countries()

Returns a sorted list of all valid country codes (lower-case) that can be passed to names_in_country(). Note: "uk" is an alias for "gb" and is not a valid ISO country code. Use Locale::Country for code-to-name conversion.

🌍 DateTime::TimeZone->names_in_country( $country_code )

Given a two-letter ISO3166 country code (any case), returns a list of time zones used in that country. The list is ordered vaguely based on geography and population. In scalar context returns an array reference, in list context returns an array.

🔢 DateTime::TimeZone->offset_as_seconds( $offset )

Given an offset as a string, returns the number of seconds represented. Returns undef if $offset is not in range "-99:59:59" to "+99:59:59". The offset is expected to match either /^([\+\-])?(\d\d?):(\d\d)(?::(\d\d))?$/ or /^([\+\-])?(\d\d)(\d\d)(\d\d)?$/. If you want to specify hours as a single digit, each element must be separated by a colon.

🔤 DateTime::TimeZone->offset_as_string( $offset, $sep )

Given an offset as a number, returns the offset as a string. Returns undef if $offset is not in range "-359999" to 359999. An optional separator can be provided between the hours, minutes, and seconds portions.

💾 Storable Hooks

This module provides freeze and thaw hooks for Storable so that the huge data structures for Olson time zones are not actually stored in the serialized structure. If you subclass DateTime::TimeZone, you will inherit its hooks, so test the interaction with Storable.

🔄 LOADING TIME ZONES IN A PRE-FORKING SYSTEM

If you are running an application that does pre-forking (e.g., with Starman), try to load all the time zones you'll need in the parent process. Time zones are loaded on-demand, so loading them once in each child will waste memory that could otherwise be shared.

🏆 CREDITS

This module was inspired by Jesse Vincent's work on Date::ICal::Timezone, and written with much help from the datetime@perl.org list.

📚 SEE ALSO

datetime@perl.org mailing list

The tools directory of the DateTime::TimeZone distribution includes two scripts: parse_olson and tests_from_zdump. Run with --help for usage.

🛟 SUPPORT

Support is provided via the datetime@perl.org email list.

Bugs may be submitted at https://github.com/houseabsolute/DateTime-TimeZone/issues.

📦 SOURCE

The source code repository for DateTime-TimeZone can be found at https://github.com/houseabsolute/DateTime-TimeZone.

💝 DONATIONS

If you'd like to thank the author, consider making a donation via PayPal. Donations may not directly increase development speed, but are appreciated. Send money to autarch@urth.org or use the button at https://www.urth.org/fs-donation.html.

✍️ AUTHOR

Dave Rolsky <autarch@urth.org>

🙌 CONTRIBUTORS

• Alexey Molchanov <alexey.molchanov@gmail.com>
• Alfie John <alfiej@fastmail.fm>
• Andrew Paprocki <apaprocki@bloomberg.net>
• Bron Gondwana <brong@fastmail.fm>
• Daisuke Maki <dmaki@cpan.org>
• David Pinkowitz <dave@pinkowitz.com>
• Iain Truskett <deceased>
• Jakub Wilk <jwilk@jwilk.net>
• James E Keenan <jkeenan@cpan.org>
• Joshua Hoblitt <jhoblitt@cpan.org>
• Karen Etheridge <ether@cpan.org>
• karupanerura <karupa@cpan.org>
• kclaggett <kclaggett@proofpoint.com>
• Matthew Horsfall <wolfsage@gmail.com>
• Mohammad S Anwar <mohammad.anwar@yahoo.com>
• Olaf Alders <olaf@wundersolutions.com>
• Peter Rabbitson <ribasushi@cpan.org>
• Tom Wyant <wyant@cpan.org>

📄 COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by Dave Rolsky.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

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

perl v5.32.1 2021-10-22 DateTime::TimeZone(3pm)

🗂️ NAME 🚀 Quick Reference 📜 VERSION 📝 SYNOPSIS 📖 DESCRIPTION ⚙️ USAGE 🔄 LOADING TIME ZONES IN A PRE-FORKING SYSTEM 🏆 CREDITS 📚 SEE ALSO 🛟 SUPPORT 📦 SOURCE 💝 DONATIONS ✍️ AUTHOR 🙌 CONTRIBUTORS 📄 COPYRIGHT AND LICENSE