time

The time crate is a comprehensive date and time handling library for Rust, providing Date, Time, PrimitiveDateTime, OffsetDateTime, Duration, and UtcOffset types built around correctness and ergonomics. It supports both a runtime format-description parser and compile-time macros (date!, time!, datetime!, format_description!) for zero-cost literal construction.

The crate is no_std-compatible (with an alloc feature for heap-using functionality), integrates with serde for serialization, and offers optional interop with rand, quickcheck, and JavaScript’s Date via js-sys for WASM targets. It is one of the most widely used date/time crates in the Rust ecosystem, serving as a lower-level alternative or complement to chrono.

What You Get

• Core types for Date, Time, PrimitiveDateTime, OffsetDateTime, UtcDateTime, Duration, and UtcOffset
• Compile-time macros (date!, time!, datetime!, format_description!) for validated literal construction
• A configurable format-description system for parsing and formatting dates/times at runtime
• no_std support (with an alloc feature) for embedded and constrained environments
• Optional serde, rand, and quickcheck integrations for serialization and property-based testing
• A companion time-macros crate providing the proc-macro implementations used by the main crate

Common Use Cases

• Representing and manipulating timestamps in a Rust backend service without pulling in a full chrono dependency
• Parsing and formatting dates/times from external APIs using configurable format descriptions
• Validating date/time literals at compile time via macros to catch invalid dates before runtime
• Using date/time types in no_std or embedded Rust projects where the standard library isn’t available

Under The Hood

Architecture - The time workspace splits responsibilities across three crates: time-core (shared internal primitives), time-macros (proc-macros for compile-time literal validation), and the main time crate exposing public types like Date (date.rs), OffsetDateTime (offset_date_time.rs), and SignedDuration/Duration (signed_duration.rs), with dedicated parsing/ and formatting/ modules implementing the format-description engine. Tech Stack - Pure Rust with a 2024 edition and MSRV of 1.88.0, using deranged for range-constrained integers, powerfmt for formatting helpers, num-conv for safe numeric conversions, and optional dependencies on serde, rand (multiple versions supported via feature flags rand08/rand09/rand010), quickcheck, and js-sys for WASM/JS interop. Code Quality - The time crate has an extensive test suite (43 test files under src/tests.rs and submodules) plus quickcheck-based property tests (quickcheck.rs) for randomized validation of date/time arithmetic; the project publishes a coverage badge via Codecov and maintains a documented MSRV policy guaranteeing compatibility with the two prior stable Rust releases. API Design - The crate favors compile-time-checked macros (date!(2024-01-01)) over runtime-fallible constructors where possible, reducing a whole class of invalid-date bugs; comprehensive documentation is published both on docs.rs and a dedicated ‘book’, and the maintainer explicitly documents an AI usage policy (AI_POLICY.md) for contributions.