Expand description
timeglyph-core — zero-dependency epoch arithmetic.
The integer half of timeglyph. Turning a
stored tick count into nanoseconds since the Unix epoch is a subtraction and
a multiplication; it needs no calendar. Rendering that instant as ISO-8601
does, so rendering stays upstairs. That seam is what lets this crate keep
zero dependencies and a 1.75 MSRV, and so be linked by a FOUNDATION crate or
a published low-MSRV parser at no cost to either (ADR-0019).
§The sentinel policy
These converters answer a parser’s question — “what instant does this field
hold, if any?” — so they return None, rather than a decoded value, for:
0— the “not set” sentinel every one of these formats uses in practice. An unset Windows FILETIME field is a zeroed field, not a record of 1601-01-01.- anything below the format’s own epoch offset, which cannot be a real instant in a 1601- or 1904-based encoding and is the signature of misaligned bytes rather than of an ancient event.
- arithmetic that would overflow
i64nanoseconds (≈ year 2262).
Cocoa is the documented exception to the second rule: its 2001 reference date
makes negative values ordinary — every date before 2001 is one — so only
0.0 and the non-finite values are rejected.
This is deliberately not the contract of [timeglyph]’s scanner, which
answers a different question — “what could this value decode to?” — and so
reports the 1601 instant for a zero FILETIME rather than hiding it. Neither
is a fallback for the other; pick by what your caller does with the answer.
§Example
use timeglyph_core::filetime_to_unix_ns;
// 2020-01-01T00:00:00Z, as a Windows FILETIME.
assert_eq!(
filetime_to_unix_ns(132_223_104_000_000_000),
Some(1_577_836_800_000_000_000)
);
// A zeroed field is "not set", not 1601-01-01.
assert_eq!(filetime_to_unix_ns(0), None);Constants§
- COCOA_
EPOCH_ OFFSET_ SECS - Seconds from the Unix epoch forward to the Cocoa / Core Data reference date
(2001-01-01 UTC) — so it is added, not subtracted. Apple publishes it as
NSTimeIntervalSince1970in Foundation’sNSDate.h. - FILETIME_
EPOCH_ OFFSET - 100-ns ticks from the Windows FILETIME epoch (1601-01-01 UTC) to the Unix epoch: 134,774 days = 11,644,473,600 seconds. See MS-DTYP §2.3.3.
- HFS_
EPOCH_ OFFSET_ SECS - Seconds from the HFS+ epoch (1904-01-01 UTC) to the Unix epoch: 24,107 days. See Apple Technical Note TN1150, HFS Plus Volume Format.
- WEBKIT_
EPOCH_ OFFSET - Microseconds from the WebKit/Chrome epoch to the Unix epoch. Chrome stores
its history, cookie and download times as microseconds since 1601-01-01 UTC —
the same epoch as FILETIME at a coarser resolution. Chromium spells this
constant
kTimeTToMicrosecondsOffsetinbase/time/time.h.
Functions§
- cocoa_
secs_ to_ unix_ ns - Unix nanoseconds from a Cocoa / Core Data timestamp (seconds since 2001-01-01 UTC), preserving the sub-second part.
- filetime_
to_ unix_ ns - Unix nanoseconds from a 64-bit Windows
FILETIME(100-ns ticks since 1601-01-01 UTC). - hfs_
secs_ to_ unix_ ns - Unix nanoseconds from an HFS+ date (seconds since 1904-01-01 UTC) — the catalog record timestamps of an HFS+ volume.
- webkit_
micros_ to_ unix_ ns - Unix nanoseconds from a WebKit/Chrome timestamp (microseconds since
1601-01-01 UTC) — Chrome’s
History,CookiesandWeb Datastores.