Skip to main content

Crate timeglyph_core

Crate timeglyph_core 

Source
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 i64 nanoseconds (≈ 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 NSTimeIntervalSince1970 in Foundation’s NSDate.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 kTimeTToMicrosecondsOffset in base/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, Cookies and Web Data stores.