Time::TZ -- object-oriented TZ settings
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);
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.
TZ
$ENV{'TZ'}
Time::TZ
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).
$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.
choose
tz_known
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.
new
fallback
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.
name
$bool = Time::TZ->tz_known ($str)
Return true if TZ setting $str is known to the system (the C library etc).
$str
$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.
localtime
gmtime
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');
$str = $tz->tz()
Return the TZ string of $tz.
$tz
$str = $tz->name()
Return the name of $tz, or undef if none set.
undef
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.
$subr
$tz->tz
call
$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.
$time_t
time()
my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = $tz->localtime;
Tie::TZ, "%ENV" in perlvar, Time::localtime, DateTime::TimeZone
http://user42.tuxfamily.org/tie-tz/index.html
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/>.
To install Tie::TZ, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Tie::TZ
CPAN shell
perl -MCPAN -e shell install Tie::TZ
For more information on module installation, please visit the detailed CPAN module installation guide.