gotz

README

gotz

Go package that parses IANA TZif timezone files and exposes raw timezone data that Go's time.Location keeps private — transitions, zone types, POSIX TZ rules, and leap second records.

Timezone data is compiled from the official IANA source and embedded in the package, so there is no dependency on the host system's timezone files.

Install

go get github.com/KarpelesLab/gotz

Usage

z, err := gotz.Load("America/New_York")
if err != nil {
    log.Fatal(err)
}

// Inspect zone types (EST, EDT, etc.)
for _, zt := range z.Types() {
    fmt.Printf("%s  offset=%d  dst=%v\n", zt.Abbrev, zt.Offset, zt.IsDST)
}

// Iterate historical transitions
for _, t := range z.Transitions() {
    zt := z.Types()[t.Type]
    fmt.Printf("%s  -> %s\n", time.Unix(t.When, 0).UTC(), zt.Abbrev)
}

// Look up the active zone at a specific time
zt := z.Lookup(time.Now())
fmt.Printf("Current zone: %s (UTC%+d)\n", zt.Abbrev, zt.Offset/3600)

// Get the POSIX TZ rule for future transitions
if rule := z.Extend(); rule != nil {
    start, end, _ := rule.TransitionsForYear(2025)
    fmt.Printf("DST starts: %s\n", time.Unix(start, 0).UTC())
    fmt.Printf("DST ends:   %s\n", time.Unix(end, 0).UTC())
}

// Convert to *time.Location for use with the standard library
loc, err := z.Location()
fmt.Println(time.Now().In(loc))

API

Loading

Function	Description
Load(name string) (*Zone, error)	Load by IANA name (cached)
Parse(name string, data []byte) (*Zone, error)	Parse raw TZif binary data

Zone

Method	Description
Name() string	IANA timezone name
Version() int	TZif format version (1–4)
Types() []ZoneType	Zone type definitions (abbreviation, offset, DST flag)
Transitions() []Transition	Historical transition records (from TZif file only)
TransitionsForRange(start, end time.Time) []Transition	All transitions in range, including generated from POSIX rule
LeapSeconds() []LeapSecond	Leap second records
Extend() *PosixTZ	Parsed POSIX TZ rule for future transitions
ExtendRaw() string	Raw POSIX TZ footer string
Lookup(time.Time) ZoneType	Zone type active at a given time
Location() (*time.Location, error)	Convert to *time.Location

PosixTZ

Method	Description
HasDST() bool	Whether DST is defined
Lookup(unix int64) (abbrev, offset, isDST)	Zone in effect at a Unix timestamp
TransitionsForYear(year int) (start, end int64, ok bool)	DST transition times for a year
String() string	POSIX TZ string representation

Updating timezone data

Run the update script to download and compile the latest IANA timezone data:

./update.sh

This downloads tzcode and tzdata from data.iana.org, compiles them with zic, and packages the result into zoneinfo.zip. Edit the CODE and DATA variables at the top of the script to target a specific release.

License

MIT — see LICENSE.

Documentation

Overview

Package gotz provides direct access to IANA timezone data, exposing transitions, zone types, and POSIX TZ rules that Go's time.Location keeps private.

Timezone data is compiled from the official IANA source and embedded in the package. Use Load to get a Zone by IANA name:

z, err := gotz.Load("America/New_York")
for _, t := range z.Transitions() {
    fmt.Println(t.When, z.Types()[t.Type].Abbrev)
}

Index

• Variables
• type LeapSecond
• type PosixTZ
  • func ParsePosixTZ(s string) (*PosixTZ, error)
  • func (p *PosixTZ) HasDST() bool
  • func (p *PosixTZ) Lookup(unix int64) (abbrev string, offset int, isDST bool)
  • func (p *PosixTZ) String() string
  • func (p *PosixTZ) TransitionsForYear(year int) (dstStart, dstEnd int64, ok bool)
• type RuleKind
• type Transition
• type TransitionRule
• type Zone
  • func Load(name string) (*Zone, error)
  • func Parse(name string, data []byte) (*Zone, error)
  • func (z *Zone) Extend() *PosixTZ
  • func (z *Zone) ExtendRaw() string
  • func (z *Zone) LeapSeconds() []LeapSecond
  • func (z *Zone) Location() (*time.Location, error)
  • func (z *Zone) Lookup(t time.Time) ZoneType
  • func (z *Zone) Name() string
  • func (z *Zone) String() string
  • func (z *Zone) Transitions() []Transition
  • func (z *Zone) TransitionsForRange(start, end time.Time) []Transition
  • func (z *Zone) Types() []ZoneType
  • func (z *Zone) Version() int
• type ZoneType

Variables

var ErrBadData = errors.New("gotz: malformed timezone data")

Types

type LeapSecond

type LeapSecond struct {
	When       int64 // Unix timestamp
	Correction int32 // cumulative correction
}

LeapSecond represents a leap second record.

type PosixTZ

type PosixTZ struct {
	StdAbbrev string // standard time abbreviation
	StdOffset int    // standard time UTC offset in seconds (positive = east)
	DSTAbbrev string // DST abbreviation (empty if no DST)
	DSTOffset int    // DST UTC offset in seconds
	Start     TransitionRule
	End       TransitionRule
}

PosixTZ represents a parsed POSIX-style TZ string. Example: "EST5EDT,M3.2.0,M11.1.0"

func ParsePosixTZ

func ParsePosixTZ(s string) (*PosixTZ, error)

ParsePosixTZ parses a POSIX-style TZ string.

func (*PosixTZ) HasDST

func (p *PosixTZ) HasDST() bool

HasDST reports whether the POSIX TZ rule defines daylight saving time.

func (*PosixTZ) Lookup

func (p *PosixTZ) Lookup(unix int64) (abbrev string, offset int, isDST bool)

Lookup returns the zone abbreviation, UTC offset, and DST flag in effect at the given Unix timestamp according to this POSIX TZ rule.

func (*PosixTZ) String

func (p *PosixTZ) String() string

String returns the POSIX TZ string representation.

func (*PosixTZ) TransitionsForYear

func (p *PosixTZ) TransitionsForYear(year int) (dstStart, dstEnd int64, ok bool)

TransitionsForYear returns the DST start and end times as Unix timestamps for the given year. Returns ok=false if there is no DST.

type RuleKind

type RuleKind int

RuleKind identifies the type of transition rule in a POSIX TZ string.

const (
	// RuleJulian is the Jn format: Julian day (1-365), Feb 29 is never counted.
	RuleJulian RuleKind = iota
	// RuleDOY is the n format: zero-based day of year (0-365), Feb 29 is counted.
	RuleDOY
	// RuleMonthWeekDay is the Mm.w.d format: month, week, day-of-week.
	RuleMonthWeekDay
)

type Transition

type Transition struct {
	When  int64 // Unix timestamp
	Type  int   // index into Zone.Types()
	IsStd bool  // transition time is standard (not wall clock)
	IsUT  bool  // transition time is UT (not local)
}

Transition represents a moment when the timezone rule changes.

type TransitionRule

type TransitionRule struct {
	Kind RuleKind
	Day  int // Julian day (1-365), DOY (0-365), or day-of-week (0=Sunday)
	Week int // week of month (1-5), only for RuleMonthWeekDay
	Mon  int // month (1-12), only for RuleMonthWeekDay
	Time int // seconds after midnight (default 7200 = 02:00:00)
}

TransitionRule specifies when a DST transition occurs within a year.

type Zone

type Zone struct {
	// contains filtered or unexported fields
}

Zone represents a parsed IANA timezone with all raw data exposed.

func Load

func Load(name string) (*Zone, error)

Load returns a Zone for the given IANA timezone name. Results are cached; subsequent calls for the same name return the same *Zone.

func Parse

func Parse(name string, data []byte) (*Zone, error)

Parse parses TZif-format binary data into a Zone.

func (*Zone) Extend

func (z *Zone) Extend() *PosixTZ

Extend returns the parsed POSIX TZ rule for computing future transitions, or nil if the TZif file has no footer string.

func (*Zone) ExtendRaw

func (z *Zone) ExtendRaw() string

ExtendRaw returns the raw POSIX TZ footer string.

func (*Zone) LeapSeconds

func (z *Zone) LeapSeconds() []LeapSecond

LeapSeconds returns a copy of the leap second records.

func (*Zone) Location

func (z *Zone) Location() (*time.Location, error)

Location returns a *time.Location equivalent to this Zone. This uses time.LoadLocationFromTZData with the original TZif binary data.

func (*Zone) Lookup

func (z *Zone) Lookup(t time.Time) ZoneType

Lookup returns the zone type in effect at the given time. It searches transitions and falls back to the POSIX TZ rule for times after the last transition.

func (*Zone) Name

func (z *Zone) Name() string

Name returns the IANA timezone name.

func (*Zone) String

func (z *Zone) String() string

String returns the timezone name.

func (*Zone) Transitions

func (z *Zone) Transitions() []Transition

Transitions returns a copy of the transition records.

func (*Zone) TransitionsForRange

func (z *Zone) TransitionsForRange(start, end time.Time) []Transition

TransitionsForRange returns all transitions in the half-open interval [start, end), combining stored transitions from the TZif file with dynamically generated ones from the POSIX TZ extend rule.

func (*Zone) Types

func (z *Zone) Types() []ZoneType

Types returns a copy of the zone type definitions.

func (*Zone) Version

func (z *Zone) Version() int

Version returns the TZif format version (1, 2, 3, or 4).

type ZoneType

type ZoneType struct {
	Abbrev string // abbreviated name
	Offset int    // seconds east of UTC
	IsDST  bool   // true if daylight saving time
}

ZoneType describes a local time type (e.g., EST, EDT).