timeglyph_core/lib.rs
1//! `timeglyph-core` — zero-dependency epoch arithmetic.
2//!
3//! The integer half of [`timeglyph`](https://docs.rs/timeglyph). Turning a
4//! stored tick count into nanoseconds since the Unix epoch is a subtraction and
5//! a multiplication; it needs no calendar. Rendering that instant as ISO-8601
6//! does, so rendering stays upstairs. That seam is what lets this crate keep
7//! zero dependencies and a 1.75 MSRV, and so be linked by a FOUNDATION crate or
8//! a published low-MSRV parser at no cost to either (ADR-0019).
9//!
10//! # The sentinel policy
11//!
12//! These converters answer a *parser's* question — "what instant does this field
13//! hold, if any?" — so they return [`None`], rather than a decoded value, for:
14//!
15//! - **`0`** — the "not set" sentinel every one of these formats uses in
16//! practice. An unset Windows FILETIME field is a zeroed field, not a record
17//! of 1601-01-01.
18//! - **anything below the format's own epoch offset**, which cannot be a real
19//! instant in a 1601- or 1904-based encoding and is the signature of
20//! misaligned bytes rather than of an ancient event.
21//! - **arithmetic that would overflow `i64` nanoseconds** (≈ year 2262).
22//!
23//! Cocoa is the documented exception to the second rule: its 2001 reference date
24//! makes negative values ordinary — every date before 2001 is one — so only
25//! `0.0` and the non-finite values are rejected.
26//!
27//! This is deliberately **not** the contract of [`timeglyph`]'s scanner, which
28//! answers a different question — "what *could* this value decode to?" — and so
29//! reports the 1601 instant for a zero FILETIME rather than hiding it. Neither
30//! is a fallback for the other; pick by what your caller does with the answer.
31//!
32//! # Example
33//!
34//! ```
35//! use timeglyph_core::filetime_to_unix_ns;
36//!
37//! // 2020-01-01T00:00:00Z, as a Windows FILETIME.
38//! assert_eq!(
39//! filetime_to_unix_ns(132_223_104_000_000_000),
40//! Some(1_577_836_800_000_000_000)
41//! );
42//! // A zeroed field is "not set", not 1601-01-01.
43//! assert_eq!(filetime_to_unix_ns(0), None);
44//! ```
45
46/// 100-ns ticks from the Windows FILETIME epoch (1601-01-01 UTC) to the Unix
47/// epoch: 134,774 days = 11,644,473,600 seconds. See [MS-DTYP] §2.3.3.
48///
49/// [MS-DTYP]: https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-dtyp/2c57429b-fdd4-488f-b5fc-9e4cf020fcdf
50pub const FILETIME_EPOCH_OFFSET: u64 = 116_444_736_000_000_000;
51
52/// Microseconds from the WebKit/Chrome epoch to the Unix epoch. Chrome stores
53/// its history, cookie and download times as microseconds since 1601-01-01 UTC —
54/// the same epoch as FILETIME at a coarser resolution. Chromium spells this
55/// constant `kTimeTToMicrosecondsOffset` in `base/time/time.h`.
56pub const WEBKIT_EPOCH_OFFSET: u64 = 11_644_473_600_000_000;
57
58/// Seconds from the Unix epoch *forward* to the Cocoa / Core Data reference date
59/// (2001-01-01 UTC) — so it is added, not subtracted. Apple publishes it as
60/// `NSTimeIntervalSince1970` in Foundation's `NSDate.h`.
61pub const COCOA_EPOCH_OFFSET_SECS: i64 = 978_307_200;
62
63/// Seconds from the HFS+ epoch (1904-01-01 UTC) to the Unix epoch: 24,107 days.
64/// See Apple Technical Note TN1150, *HFS Plus Volume Format*.
65pub const HFS_EPOCH_OFFSET_SECS: u32 = 2_082_844_800;
66
67/// Unix nanoseconds from a 64-bit Windows `FILETIME` (100-ns ticks since
68/// 1601-01-01 UTC).
69///
70/// [`None`] when `ft` is `0` (the "not set" sentinel), when it is below
71/// [`FILETIME_EPOCH_OFFSET`], or when the nanosecond value overflows `i64`.
72/// A zero field is subsumed by the offset test — it is the smallest value below
73/// the epoch, not a case of its own.
74#[must_use]
75pub fn filetime_to_unix_ns(ft: u64) -> Option<i64> {
76 let ticks = ft.checked_sub(FILETIME_EPOCH_OFFSET)?;
77 i64::try_from(ticks).ok()?.checked_mul(100)
78}
79
80/// Unix nanoseconds from a WebKit/Chrome timestamp (microseconds since
81/// 1601-01-01 UTC) — Chrome's `History`, `Cookies` and `Web Data` stores.
82///
83/// Same sentinel policy as [`filetime_to_unix_ns`], against
84/// [`WEBKIT_EPOCH_OFFSET`].
85#[must_use]
86pub fn webkit_micros_to_unix_ns(us: u64) -> Option<i64> {
87 let micros = us.checked_sub(WEBKIT_EPOCH_OFFSET)?;
88 i64::try_from(micros).ok()?.checked_mul(1_000)
89}
90
91/// Unix nanoseconds from a Cocoa / Core Data timestamp (seconds since
92/// 2001-01-01 UTC), preserving the sub-second part.
93///
94/// [`None`] for `0.0` (the "not set" sentinel, `-0.0` included), for NaN and the
95/// infinities, and for a magnitude that will not fit `i64` nanoseconds. Negative
96/// values are *not* rejected: in a 2001-based encoding they are ordinary dates
97/// before 2001, unlike the 1601-based formats above.
98///
99/// The conversion is done in `f64`, which is the format's own representation, so
100/// nothing is lost that the stored value had — near the present, an `f64`
101/// seconds count already resolves to roughly 100 ns.
102#[must_use]
103pub fn cocoa_secs_to_unix_ns(secs: f64) -> Option<i64> {
104 // `i64::MIN` and `i64::MAX + 1`, both exactly representable in f64. The `as`
105 // cast SATURATES rather than wrapping, which would silently turn an absurd
106 // float into a plausible-looking instant; bound it explicitly instead.
107 const MIN_NS: f64 = -9_223_372_036_854_775_808.0;
108 const MAX_NS: f64 = 9_223_372_036_854_775_808.0;
109
110 if !secs.is_finite() || secs == 0.0 {
111 return None;
112 }
113 let ns = (secs + COCOA_EPOCH_OFFSET_SECS as f64) * 1e9;
114 let ns = ns.round();
115 if !(MIN_NS..MAX_NS).contains(&ns) {
116 return None;
117 }
118 Some(ns as i64)
119}
120
121/// Unix nanoseconds from an HFS+ date (seconds since 1904-01-01 UTC) — the
122/// catalog record timestamps of an HFS+ volume.
123///
124/// [`None`] for `0` and for anything below [`HFS_EPOCH_OFFSET_SECS`]. There is no
125/// overflow case: the largest `u32` second count above the epoch is ≈ 2.21e18 ns,
126/// well inside `i64`, so the conversion is total by construction.
127///
128/// TN1150 stores these as GMT, with one documented exception — the volume
129/// header's `createDate`, which is local time. Converting that field to a real
130/// instant needs the volume's timezone and is the caller's problem, not this
131/// function's.
132#[must_use]
133pub fn hfs_secs_to_unix_ns(secs: u32) -> Option<i64> {
134 let unix = secs.checked_sub(HFS_EPOCH_OFFSET_SECS)?;
135 Some(i64::from(unix) * 1_000_000_000)
136}