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).

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 whether the system timezones are 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

In the GNU C Library, a bad TZ setting makes localtime come out as GMT, so the test is that $str gives localtime different from gmtime on one of a range of values through the year (so it can be the same as GMT during daylight savings, or non daylight savings). Zones "GMT" and "UTC" are always considered known.

Comparing against GMT is no good for places like "Africa/Accra" which are known but are just GMT. The suggestion is not to use choose but just put it in unconditionally,

    my $acc = Time::TZ->new (tz => 'Africa/Accra');

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 method 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 such arguments, 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 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/>.