time Rust Library

The time crate follows a rolling minimum supported Rust version (MSRV) policy. It is guaranteed to compile with the latest stable release of Rust and the two prior minor releases.

Note that the MSRV may be bumped up to one of those three versions to provide user benefits, or bumped down to four minor releases prior to the most recent stable release to improve maintainability.

The crate provides type aliases for backward compatibility, but these are expected to be removed in a future breaking release. When writing new code, you should use the primary types instead.

• Use PlainDateTime instead of PrimitiveDateTime.
• Use SignedDuration instead of Duration.

An Instant is a measurement of a monotonically non-decreasing clock. It is an opaque type used primarily for measuring benchmarks or timing how long an operation takes.

Key Characteristics:

• Monotonicity: Instants are guaranteed to be no less than any previously measured instant, but they are not guaranteed to be steady (ticks may vary in length).
• Opaque: You cannot extract

// Note: This API is deprecated. Use std::time::Instant instead.
# #![expect(deprecated)]
# use time::Instant;
# use std::thread;
# use std::time::Duration as StdDuration;
# use time::ext::NumericalStdDuration;
let instant = Instant::now();
thread::sleep(1.std_milliseconds());
assert!(instant.elapsed() >= 1.milliseconds());

In time, FormatDescriptionV3 is the primary type used to describe how to format and parse date/time types. It is an opaque type designed for forwards compatibility and performance optimizations.

Because it is opaque, you cannot construct it directly using a struct literal. Instead, you should use one of the following methods:

1. The format_description! macro: Use this macro with version=3 to create a description from a format string.
2. Parsing methods: The parse_borrowed and parse_owned methods return a FormatDescriptionV3 instance.

If you have a FormatDescriptionV3 with a lifetime (e.g., it contains borrowed literals), you can convert it to an owned version using .to_owned() (requires the alloc feature).

Format descriptions in time are composed of several types of items that define how date and time data should be parsed or formatted:

• Literal: A fixed sequence of bytes or a UTF-8 string.
• Component: A named part of a date/time (e.g., day, hour, month) that can have specific modifiers (e.g., padding, repr).
• Optional: A component wrapped in optional(...) brackets. It can optionally include a format modifier to control how the optionality is handled.
• First: A component using first(...) brackets that allows choosing the first matching format description from a list of provided options.

Note that for v3 format descriptions, all literals must be valid UTF-8.

The time::Instant struct is deprecated as of version 0.3.35. To ensure compatibility and follow current best practices, you should stop using time::Instant and instead import std::time::Instant along with the time::ext::InstantExt trait for extended functionality.

Deprecation Note:

• Since: 0.3.35
• Recommendation: import std::time::Instant and time::ext::InstantExt instead

The NumericalDuration trait is implemented for f64, allowing you to create durations from fractional numbers.

Warning: When calling these methods on floating point values, any remainder of the floating point value will be truncated. Because floating point numbers are inherently imprecise, use them with caution for high-precision timing requirements.

use time::ext::NumericalDuration;

// Example of using f64 (truncation occurs internally)
let duration = 1.5_f64.seconds(); 

You can convert a Month to its corresponding u8 value (1-12) or attempt to create a Month from a u8 value.

• To u8: Use u8::from(month) or month as u8.
• From u8: Use Month::try_from(value) or value.try_into(). This will return an error if the value is not in the range 1-12.
• From str: Use s.parse::<Month>(). The string must match the full month name (e.g., "January").