/ 
Time-Tzfile-0.04
River stage zero No dependents
/ Time::Tzfile

NAME

Time::Tzfile - read binary tzfiles into Perl data structures

VERSION

version 0.04

SYNOPSIS

use Time::Tzfile;

# get 64bit timestamps if available
my $tzdata = Time::Tzfile->parse({filename => '/usr/share/zoneinfo/Europe/London'});

# always get 32bit timestamps
my $tzdata = Time::Tzfile->parse({
  filename        => '/usr/share/zoneinfo/Europe/London',
  use_version_one => 1,
});

# get an unassembled raw parse of the file
my $tzdata = Time::Tzfile->parse_raw({
  filename => '/usr/share/zoneinfo/Europe/London'});

METHODS

parse ({filename => /path/to/tzfile, use_version_one => 1})

The parse takes a hashref containing the filename of the tzfile to open and optionally a flag to use the version one (32bit) tzfile entry. Returns an arrayref of hashrefs:

{
  epoch   => 1234566789, # offset begins here
  offset  => 3600,       # offset in seconds
  type    => GMT,        # official abbreviation
  is_dst  => 0,          # is daylight saving bool
}

Tzfiles can have two entries in them: the version one entry with 32bit timestamps and the version two entry with 64bit timestamps. If the tzfile has the version two entry, and if perl is compiled with 64bit support, this method will automatically return the version two entry. If you want to force the version one entry, include the use_version_one flag in the method arguments.

See #SYNOPSIS for examples.

N.B. AFAIK all binary tzfiles are compiled with UTC timestamps, so this method ignores the leap, GMT and STD time entries for calculating offsets. If you want to include them, use #parse_raw as an input to your own calculations.

parse_raw ({filename => /path/to/tzfile, use_version_one => 1})

This method reads the binary file into an arrayref of arrayrefs. Use this if you'd like to inspect the tzfile data, or use it as an input into your own programs.

The arrayref looks like this:

[
  header          # version and counts for the body
  transitions     # historical timestamps when TZ changes occur
  transition_idx  # index of ttinfo structs which apply to transitions
  ttinfo_structs  # gmt offset, dst flag & the tz abbrev idx
  tz_abbreviation # tz abbreviation string (EDT, GMT, BST etc)
  leap_seconds    # timestamp & offset to apply leap secs
  std_wall        # arrayref of std wall clock indicators
  gmt_local       # arrayref of gm local indicators
]

SEE ALSO

TZFILE FORMAT INFO

I found these resources useful guides to understanding the tzfile format

  • Tzfile manpage

  • Very useful description of tzfile format from Bloomberg

  • Wikipedia entry on the TZ database

AUTHOR

David Farrell <dfarrell@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by David Farrell.

This is free software, licensed under:

The (two-clause) FreeBSD License