Configurable support for printing and parsing datetimes and durations.

Note that for most use cases, you should be using the corresponding Display or FromStr trait implementations for printing and parsing respectively. The APIs in this module provide more configurable support for printing and parsing.

Tables of examples

The tables below attempt to show some examples of datetime and duration formatting, along with names and links to relevant routines and types. The point of these tables is to give a general overview of the formatting and parsing functionality in these sub-modules.

Support for FromStr and Display

This table lists the formats supported by the FromStr and Display trait implementations on the datetime and duration types in Jiff.

In all of these cases, the trait implementations are mere conveniences for functionality provided by the temporal sub-module (and, in a couple cases, the friendly sub-module). The sub-modules provide lower level control (such as parsing from &[u8]) and more configuration (such as controlling the disambiguation strategy used when parsing zoned datetime RFC-9557 strings).

Note that for datetimes like 2025-08-20T17:35:00, the following variants are also accepted:

2025-08-20 17:35:00
2025-08-20T17:35:00.123456789
2025-08-20T17:35
2025-08-20T17

This applies to RFC 3339 and RFC 9557 timestamps as well.

Also, for ISO 8601 durations, the unit designator labels are matched case insensitively. For example, PT1h2m3s is recognized by Jiff.

The "friendly" duration format

This table lists a few examples of the friendly duration format. Briefly, it is a bespoke format for Jiff, but is meant to match similar bespoke formats used elsewhere and be easier to read than the standard ISO 8601 duration format.

All examples below can be parsed via a Span's FromStr trait implementation. All examples with units no bigger than hours can be parsed via a SignedDuration's FromStr trait implementation. This table otherwise shows the options for printing durations in the format shown.

Bespoke datetime formats via strptime and strftime

Every datetime type has bespoke formatting routines defined on it. For example, Zoned::strptime and civil::Date::strftime. Additionally, the strtime sub-module also provides convenience routines, strtime::format and strtime::parse, where the former is generic over any datetime type in Jiff and the latter provides a BrokenDownTime for granular parsing.

The specific conversion specifiers supported are documented in the strtime sub-module. While precise POSIX compatibility is not guaranteed, the conversion specifiers are generally meant to match prevailing implementations. (Although there are many such implementations and they each tend to have their own quirks and features.)

RFC 2822 parsing and printing

RFC-2822 support is provided by the rfc2822 sub-module.