Crate time 

Date and time handling with an embedded IANA time zone database.

time provides a small, correct, no_std-friendly date and time API built around a single value type, DateTime, plus TimeZone and Error. Durations are the standard core::time::Duration; there is no dedicated duration type.

Design

• A DateTime always represents a precise instant (seconds and nanoseconds since the Unix epoch) together with a TimeZone. There is no separate “naive” or “floating” datetime.
• Equality, ordering, hashing, subtraction and all instant arithmetic are defined on the instant only, never on the time zone. This avoids the classic footgun where == depends on the zone.
• The offset reported by a value is always the offset in effect at that instant, even for civil times that fall in a DST gap.
• Zone-less input is parsed as UTC. Use DateTime::parse_with_timezone to interpret zone-less input in a specific zone.
• Well-known representations are selected with the Format enum via DateTime::format: RFC 3339, RFC 9557, RFC 2822, HTTP dates, and more. Strict, allocation-free output is available through DateTime::try_format and DateTime::format_to.
• The embedded IANA database (TimeZone::named) is available by default, is pre-parsed at build time, and works without alloc. Future daylight-saving transitions are materialized up to a rolling horizon (the IANA release year plus 50) so near-future lookups stay a plain search, with the POSIX rule governing beyond it. The advertised release is TZDB_VERSION.

Measuring elapsed time

Values from DateTime::now and DateTime::now_in also carry a monotonic clock reading. When both values being compared have one, DateTime::duration_since, DateTime::duration_until, DateTime::signed_duration_since and DateTime::elapsed measure with the monotonic clock and are robust against wall-clock adjustments (for example NTP steps or manual clock changes). Values that were parsed or built from civil fields use the wall clock, so measuring a duration across a serialization round trip is not monotonic. Use DateTime::has_monotonic to check.

Leap seconds

The supported calendar has no leap seconds. A :60 second is accepted on input (both in parsing and in DateTime::from_parts) and is represented as :59 of the same minute; the library never produces :60 on output.

Ambiguous and skipped civil times

A civil time can be skipped (a DST gap) or repeated (a DST fold). DateTime::from_parts applies the “compatible” strategy: gaps are shifted forward and folds select the earlier instant. Use DateTime::from_parts_with with a Disambiguation to choose another strategy (including rejecting such times with ErrorKind::Ambiguous) and TimeZone::ambiguity to inspect the mapping.

Limitations

• The supported UTC calendar range is -9999-01-01 through 9999-12-31. A value near the boundary can display a year one outside this range when a large UTC offset is applied.
• There is no leap-second support (see above) and no local-time database for the hours, minutes and seconds of a zone beyond the abbreviation and the offset.
• RFC 9557 support is partial: a single, bare time zone name annotation is understood on input; other annotation forms are rejected.
• Parsing accepts up to nanosecond precision and truncates further fractional digits; output uses 3, 6 or 9 fractional digits, which keeps formatted strings sortable.

Feature flags

• std (default): enables reading the system clock and the monotonic clock, and the system time zone. It uses alloc internally but exposes no allocation-requiring API.
• timezone-db (default): embeds a copy of the IANA time zone database.
• timezone-system: reads time zone rules from the system database (implies std), detecting and caching the system zone once per process.
• serde: RFC 3339 / RFC 9557 serialization.

Examples

use time::{DateTime, TimeZone};

let dt: DateTime = "2024-07-11T01:14:00Z".parse().unwrap();
assert_eq!(dt.unix(), 1_720_660_440);

// Requires the default `timezone-db` feature.
if let Ok(ny) = TimeZone::named("America/New_York") {
    let dt = dt.in_timezone(ny);
    assert_eq!(dt.hour(), 21);
    assert_eq!(dt.offset(), -4 * 3600);
}

Structs

DateTime

A precise instant in time together with a TimeZone.

Duration

A Duration type to represent a span of time, typically used for system timeouts.

Error

An error returned by fallible operations in this crate.

Formatted

A Display adapter returned by DateTime::format.

TimeZone

A time zone: UTC, a fixed offset, or a named IANA zone.

Enums

Ambiguity

Describes how a civil time maps to UTC offsets in a time zone.

Disambiguation

How a civil (wall-clock) time that does not map cleanly to an instant should be resolved.

ErrorKind

The category of an Error.

Format

A well-known datetime representation.

Weekday

A day of the week.

Statics

TZDB_VERSION

The IANA Time Zone Database release the embedded data was compiled from.

Functions

all_timezones

Returns the names of every embedded time zone, sorted.