NAME

Time::TZ -- object-oriented TZ settings

SYNOPSIS

use Time::TZ;
$auck = Time::TZ->new (tz => 'Pacific/Auckland');

$frank = Time::TZ->new (name     => 'Frankfurt',
                        choose   => [ 'Europe/Frankfurt',
                                      'Europe/Berlin' ],
                        fallback => 'CET-1CEDT,M3.5.0,M10.5.0/3');

@parts = $auck->localtime($timet);

DESCRIPTION

This is an object-oriented approach to TZ environment variable settings, ie. $ENV{'TZ'}. A Time::TZ object holds a TZ string and has methods to make calculations in that zone by temporarily changing the TZ environment variable (see Tie::TZ). See examples/time-tz.pl in the sources for complete program.

The advantage of this approach is that it needs only a modest amount of code and uses the same system timezones as other programs. Of course what system timezones are available and whether they're up-to-date etc is another matter, and switching TZ for each calculation can be disappointingly slow (for example in the GNU C Library).

FUNCTIONS

$tz = Time::TZ->new (key=>value, ...)

Create and return a new TZ object. The possible key/value parameters are

tz        TZ string
choose    arrayref of TZ strings
fallback  TZ string
name      free-form name string

If choose is given then the each TZ string in the array is checked and the first known to the system is used (see tz_known below). choose is good if a place has different settings on different systems or new enough systems.

my $brem = Time::TZ->new (choose => [ 'Europe/Bremen',
                                      'Europe/Berlin' ]);

If none of the choose settings are known then new croaks. If you supply a fallback then it just carps and uses that fallback value.

my $brem = Time::TZ->new (choose => [ 'Europe/Bremen',
                                      'Europe/Berlin' ],
                          fallback => 'CET-1');

The name parameter is not used for any timezone calculations, it's just a handy way to keep a human-readable placename with the object.

$bool = Time::TZ->tz_known ($str)

Return true if TZ setting $str is known to the system (the C library etc).

$bool = Time::TZ->tz_known ('EST+10');          # true
$bool = Time::TZ->tz_known ('some bogosity');   # false

The way this works is unfortunately rather system dependent. The "name+/-offset" forms are always available, as are "GMT" and "UTC". On a GNU system place names are checked under /usr/share/zoneinfo. Otherwise a check is made to see if $str gives localtime different from gmtime on one of a range of values through the year.

The time check works for the GNU C Library where a bad timezone comes out as GMT, but might not be enough elsewhere. Place names the same as GMT are no good of course, and if the system makes a bogus zone come out as say the default local time then they won't be detected (unless that local time happens to be GMT too). If wrong, the suggestion for now is not to use choose but put in a setting unconditionally,

my $acc = Time::TZ->new (tz => 'SomeWhere');

Object Methods

$str = $tz->tz()

Return the TZ string of $tz.

$str = $tz->name()

Return the name of $tz, or undef if none set.

Time Operations

ret = $tz->call ($subr)

ret = $tz->call ($subr, $arg, ...)

Call $subr with the TZ environment variable temporarily set to $tz->tz. The return value is the return from $subr, with the same scalar or array context as the call itself.

$tz->call (sub { print "the time is ",ctime() });

my $year = $tz->call (\&Date::Calc::This_Year);

Arguments are passed on to $subr. For an anonymous sub there's no need for that, but they can be good for a named sub,

my @ret = $tz->call (\&foo, 1, 2, 3);

@lt = $tz->localtime ()

@lt = $tz->localtime ($time_t)

Call localtime (see "localtime" in perlfunc) in the given $tz timezone. $time_t is a value from time(), or defaults to the current time(). The return is the usual list of 9 localtime values.

my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)
      = $tz->localtime;

SEE ALSO

Tie::TZ, "%ENV" in perlvar, Time::localtime, DateTime::TimeZone

HOME PAGE

http://user42.tuxfamily.org/tie-tz/index.html

COPYRIGHT

Copyright 2007, 2008, 2009, 2010, 2011, 2019, 2020 Kevin Ryde

Tie-TZ is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Tie-TZ is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Tie-TZ. If not, see <http://www.gnu.org/licenses/>.