NAME

Time::Zone - Perl extension for converting time_t values to local time and back

SYNOPSIS

  use Time::Zone;

  my($tzo) = Time::Zone->new({ zone => "Europe/Paris" });

DESCRIPTION

Time::Zone reads tzfile(5) files and then provides methods which allow you to translate time_t values into timezone local time values and back again. (it even gets things right when you ask for a local time spec to be translated back, and the time occurs twice in that zone (eg during a backward jump) or the time doesn't occur at all (during a forward jump))

EXPORT

None by default - Time::Zone provides an OO interface.

METHODS

Note that not all the methods are documented here - just the ones intended for external use - if it isn't documented here, there are no guarantees as to its interface or even continued existence.

Time::Zone->new( OPT_HASH )

Returns a Time::Zone object. OPT_HASH is a hash reference, which can take the following keys:

zone

The name of the timezone you want loaded. If none is specified, /etc/localtime and <tzdir>/localtime are tried in turn.

tzdir

The name of the tzfile(5) directory. Defaults to /usr/local/zoneinfo, which should be the right place on any modern unixoid system. If you are stuck on a machine which doesn't have this, or has an out-of-date or broken tzfile(5) dataset, you can always copy the tzfiles onto the machine in question, and set this option to point at them.

fix_year

Tells mktime to expect years as offsets from 1900, and kludge them up accordingly. Note that this does not effect any other methods.

Also, note that this does not have any effect when mktime is passed a data structure like that returned by time

human_month

Tells mktime to expect months in the 1-12 range, instead of the 0-11 range. Does not effect any other methods.

Also, note that this does not have any effect when mktime is passed a data structure like that returned by time

$obj->set_zone( ZONE )

Set the default timezone to ZONE.

$obj->`get_zone()`

Return the current default timezone.

$obj->tzinfo( TIME_T [, ZONE] )

Return a tzinfo hash reference, for the time_t value TIME_T, containing the following key/value pairs:

dst: Boolean - whether or not we are in daylight savings time.
offset: The offset in seconds (including any leap seconds in effect) from UTC
etla: The appropriate time zone abbreviation to use.

If ZONE is supplied, set the default zone to ZONE before proceeding.

$obj->time( TIME_T [, ZONE] )

Returns a time hash reference, for TIME_T, in the default timezone, which contains the following key/value pairs:

sec: seconds [0 - 59]
min: Minutes [0 - 59]
hour: Hours [0 - 23]
mday: Day of the month [1 - 31]
mon: Month [0-11]
year: Year - 1900
wday: Day of the Week [0 - 6] (maps to Sun - Sat)
yday: Day of the Year [0 - 366]
dst: Boolean - Daylight Saving Time flag.
mm: Month 1 - 12
yyyy: Year
etla: Time zone acronym. (usu 3-4 letters)

If ZONE is supplied, set the default zone to that before proceeding.

$obj->utczone( TIME_T [, ZONE] )

Is the ZONE (or the default zone, if ZONE is not supplied) one of the many names by which UTC (Universal Coordinate Time) is known? ( The UTC zone has, by definition, no time shifts and no leap seconds. )

Note that, unlike other methds which take a ZONE argument, utczone does not set the default timezone for the object it is called on.

This is entirely because I'm too lazy to make the other methods work this way. So there.

$obj->mktime( ZONE, LOCAL_TIME )

Returns a time_t value for LOCAL_TIME, where ZONE is a timezone name, or something false, and localtime is one of:

A time structure, as returned by the time method: Note that in this case only one of the yyyy or year, and only one of the mon or mm key value pairs, needs to be set. ( And the etla field need not be set either ). The dst flag field may be set, but is only important when a time occurs twice in a zone ( eg during a backward shift overlap ).
An array (6 elements, in gmtime() order): Note: see the fix_year and human_month options new
An array reference (6 elements, in gmtime() order): Note: see the fix_year and human_month options new

If ZONE is something true, the default zone is set to ZONE before proceeding.

There are a couple of ``interesting'' cases that mktime needs to deal with - the exact behaviour of mktime in these cases is controlled by the mktime_strict option. Note that even if mktime calculates a time_t value of 0, it will return ZERO_TRUE, so a FALSE (or even false) return value will always indicate an error.

mktime_strict = TRUE

If a time does not occur at all in the zone in question (eg due to a forward shift that traverses the time in question), mktime returns FALSE.

If a time occurs twice, and mktime cannot determine which time you required, it will return FALSE.

mktime_strict = FALSE

If a time does not occur at all in the zone in question, mktime will return the time_t value corresponding to the transition time.

If a time occurs twice, and mktime cannot determine which time you required, ( ie mktime was not called with a time structure ), then mktime will return a list consisting of both time_t values.

AUTHOR

Vivek Dasmohapatra, <vivek@etla.org>