NAME

Time::Str::TimeZone - cached lookup of IANA and local timezones

SYNOPSIS

use Time::Str::TimeZone qw(timezone);

my $tz    = timezone('Europe/Stockholm');  # a Time::TZif object
my $local = timezone('local');             # the system timezone

Time::Str::TimeZone->reset;                # drop cached zones

DESCRIPTION

Resolves timezone names to timezone objects (Time::TZif) and caches them, so repeated lookups of the same name return the same object.

The zone database directory is located once, on first use, via Time::Str::Util::find_tzdb_directory; set the TZDIR environment variable to override it.

FUNCTIONS

timezone

my $tz = timezone($name);

Returns the timezone object for $name, which must be a valid IANA Time Zone Database name (e.g. 'Europe/Stockholm') or the special name 'local'.

For 'local', the system timezone is resolved via Time::Str::Util::find_local_timezone (honoring TZ, then /etc/localtime); the result may therefore be a Time::TZif::POSIX object when TZ holds a POSIX rule.

The returned object is cached, so a later change to TZ or /etc/localtime is not reflected until "reset" is called.

Croaks if $name is not a valid IANA name, if the zone database directory cannot be located, or if the named zone (or the system timezone) cannot be resolved.

timezone is exported on request:

use Time::Str::TimeZone qw(timezone);

METHODS

reset

Time::Str::TimeZone->reset;

Clears the cache of resolved timezones (and the remembered database directory), so the next lookup re-resolves from scratch. Useful after TZ or the zone database changes within a running process.

PROVIDERS

Lookups are dispatched through a provider, the package named in $Time::Str::TimeZone::PROVIDER (by default this package). The public timezone and reset calls are thin wrappers over the provider's locate and flush methods:

$PROVIDER->locate($name)

Returns the timezone object for $name, or croaks. Responsible for any caching.

$PROVIDER->flush

Discards whatever locate has cached.

A replacement provider must implement both methods and return objects that provide the offset_for_local and offset_for_utc methods used elsewhere in Time::Str.

SEE ALSO

Time::TZif, Time::TZif::POSIX, Time::Str::Util