timeglyph 0.3.0

Forensic timestamp decipherment — decode, encode, and identify the many ways systems inscribe time, with scored, cited, ambiguity-first interpretation.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

//! Selectable output timezone (presentation only).
//!
//! The instant ([`timeglyph::PosixNs`]) is absolute; a [`timeglyph::RenderZone`]
//! changes only how it is *displayed*. The default is UTC with a `Z` suffix
//! (unambiguous — "the offset to local time is unknown"). A fixed offset or a
//! named IANA zone renders with a numeric offset, DST-correct per instant.
#![allow(clippy::unwrap_used, clippy::expect_used)]

use timeglyph::{format, PosixNs, RenderZone};

/// The instant 2020-01-01T00:00:00Z (a winter instant in the US).
fn winter() -> PosixNs {
    format("unix").unwrap().decode_int(1_577_836_800).unwrap()
}

/// The instant 2020-07-01T00:00:00Z (a summer instant in the US).
fn summer() -> PosixNs {
    format("unix").unwrap().decode_int(1_593_561_600).unwrap()
}

#[test]
fn default_zone_renders_utc_with_z() {
    let z = RenderZone::parse("UTC").unwrap();
    assert_eq!(winter().render(&z).as_deref(), Some("2020-01-01T00:00:00Z"));
    // Empty / "Z" are also UTC.
    assert!(matches!(RenderZone::parse("").unwrap(), RenderZone::Utc));
    assert!(matches!(RenderZone::parse("Z").unwrap(), RenderZone::Utc));
}

#[test]
fn fixed_offset_renders_numeric_offset() {
    let z = RenderZone::parse("+08:00").unwrap();
    assert_eq!(
        winter().render(&z).as_deref(),
        Some("2020-01-01T08:00:00+08:00")
    );
    // Compact and negative forms parse too.
    let z2 = RenderZone::parse("-0500").unwrap();
    assert_eq!(
        winter().render(&z2).as_deref(),
        Some("2019-12-31T19:00:00-05:00")
    );
}

#[test]
fn named_zone_is_dst_correct_per_instant() {
    let ny = RenderZone::parse("America/New_York").unwrap();
    // Winter → EST (-05:00); summer → EDT (-04:00). Same zone, different offset.
    assert_eq!(
        winter().render(&ny).as_deref(),
        Some("2019-12-31T19:00:00-05:00")
    );
    assert_eq!(
        summer().render(&ny).as_deref(),
        Some("2020-06-30T20:00:00-04:00")
    );
}

#[test]
fn unknown_zone_is_an_error_not_a_silent_utc_fallback() {
    // Secure-by-default: a typo'd zone must fail loudly, never silently render
    // UTC and mislead the analyst about the displayed offset.
    assert!(RenderZone::parse("Not/AZone").is_err());
    assert!(RenderZone::parse("PST8PDT_nope").is_err());
}