Time-Zone Generator Reference

tool::time_zone::TimeZoneDataTool builds the compact time-zone database and Windows mapping. See Generate Time-Zone Data for the workflow.

Configuration and Source Contract

The required [generate_time_zone_data] section has text setting output_directory, defaulting to src/erbsland/time/tz/impl. --output-directory (-o) overrides it for one run. --check (-c) compares all 25 outputs without writing and fails if any is missing or differs. The output directory must exist inside the project.

The [time_zone] section has text setting input_directory, defaulting to tool/data/time_zone. The directory contains tzdb version and nine region files, CLDR windowsZones.xml, and manifest.elcl. The manifest pins tzdb 2026b and CLDR 48 and supplies SHA3-256 hashes of normalized input text. Generation is offline; the copied source files alone supply zone histories, rules, aliases, abbreviations, and Windows mapping facts. Core’s XML parser and Gregorian calendar arithmetic do not consult its generated time-zone tables.

Parsing and Encoding

The model reads region files in the specified order, preserving zone continuation and rule order. Primary zone names sort lexicographically and receive IDs from one; named rule sets sort lexicographically and receive indexes from zero. Aliases resolve to primary names. Path components and possible abbreviations form a sorted text table; each fragment has at most 15 bytes, and the packed text block uses 16-bit offsets.

Rules encode year span, month, day expression, transition reference and time, and saving offset in 64-bit words. Continuation lines encode standard offset, UTC UNTIL boundary, effective offset, rule selection, and abbreviation index. UTC, wall, and standard time references follow the tzdb suffixes. The renderer retains the runtime table layouts and IDs. CLDR mappings use entries with territory 001 and the first IANA name in type; aliases are resolved before encoding the Windows key’s zone ID.

The source reader, tzdb model and calendar calculations, table preparation, and render templates are separate units. TimeZoneDataTool renders every output before updating any destination.

Verification

TimeZoneDataToolTest checks source hashes and version pins, changed and malformed records, representative transitions, CLDR mapping, and output limits. The affected Core time-zone tests verify runtime behavior.