Expand description
Timezone Translator — convert timestamps between timezones.
Rust port of the Ruby reference implementation (lib/tztr.rb). Kept
functionally identical: same timestamp detection, same format preservation,
same timezone aliases and resolution. See CLAUDE.md for the parity
contract.
Timezone math uses jiff, which reads the system tz database — the same
source Ruby’s Time uses via ENV['TZ'] — so DST behavior matches.
Structs§
- Assumptions
- Which assumptions a line’s timestamps force on us, for
-vto disclose. - Group
- The range or list a timestamp belongs to, as
-jreports it. - Match
- One detected timestamp and its analysis, as emitted by [
matches].
Enums§
- Format
- Explicit output format (mirrors Ruby’s
--format iso|short|time). - TzError
- Why a user-supplied timezone could not be resolved.
Constants§
- ZONE_
ABBREVIATIONS - Timezone abbreviations
tztrrecognizes inside text.
Functions§
- assumed_
date - The date
-vsays it assumed for this line’s first dateless timestamp: today where it was written. MirrorsTztr.assumed_date. - assumptions
- What converting
linewould have to assume. SeeAssumptions. - detect_
format - Label the detected format. Mirrors
Tztr.detect_format. - detect_
zone - The zone a reading ends with. It must start the text or follow a space or
digit: EEST is not EST with an E in front. Mirrors
Tztr.detect_zone. - ignored_
zones - Zone abbreviations written right after a timestamp but not read as one
because of their case (
Pst), for-vto point out. MirrorsTztr.ignored_zones. - matches
- Per-match structured analysis of a line. With
detect, translation is skipped andMatch::translatedisNone. MirrorsTztr.matches. - matches_
bytes - [
matches] for input that may not be valid UTF-8. Every match is ASCII, so theMatchfields are text either way. - resolve_
tz - Resolve a user-supplied zone (alias, numeric offset, or IANA name) to an
IANA-style name the system tz database can load. Mirrors
Tztr.resolve_tz. - system_
zone - The zone the machine runs in, when
$TZdoesn’t say:/etc/localtime’s link into the tzdb (macOS, most Linux), else Debian’s/etc/timezone. MirrorsTztr.system_zone. - timezone_
aliases - All timezone aliases as
(alias, IANA name)pairs, sorted by alias. - today_
in_ zone - Today’s date in
tzasYYYY-MM-DD. - translate
- Translate every detected timestamp in
line, preserving surrounding text.to/fromaccept aliases;fromis the assumed input zone for naive timestamps;datesupplies a reference date for time-only inputs. - translate_
bytes translatefor input that may not be valid UTF-8 — a log line with a stray byte in it. Timestamps still convert; every other byte, valid or not, comes out exactly as it went in.- unknown_
zones - Zone-shaped words a date(1) line carries that tztr doesn’t know (EEST),
for
-vto name as the reason the line was left alone.