Module fmt

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).

Example	Format	Links
2025-08-20T17:35:00Z	RFC-3339	Timestamp
2025-08-20T17:35:00-05	RFC-3339	FromStr impl and Timestamp::display_with_offset
2025-08-20T17:35:00+02[Poland]	RFC-9557	Zoned
2025-08-20T17:35:00+02:00[+02:00]	RFC-9557	Zoned
2025-08-20T17:35:00	ISO-8601	civil::DateTime
2025-08-20	ISO-8601	civil::Date
17:35:00	ISO-8601	civil::Time
P1Y2M3W4DT5H6M7S	ISO-8601, Temporal	Span
PT1H2M3S	ISO-8601	SignedDuration, Span
PT1H2M3.123456789S	ISO-8601	SignedDuration, Span
1d 2h 3m 5s	friendly	FromStr impl and alternative Display via {:#} for SignedDuration, Span

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.

Example	Print configuration
1year 2months	Designator::Verbose via SpanPrinter::designator
1yr 2mos	Designator::Short via SpanPrinter::designator
1y 2mo	Designator::Compact via SpanPrinter::designator (default)
1h2m3s	Spacing::None via SpanPrinter::spacing
1h 2m 3s	Spacing::BetweenUnits via SpanPrinter::spacing (default)
1 h 2 m 3 s	Spacing::BetweenUnitsAndDesignators via SpanPrinter::spacing
2d 3h ago	Direction::Auto via SpanPrinter::direction (default)
-2d 3h	Direction::Sign via SpanPrinter::direction
+2d 3h	Direction::ForceSign via SpanPrinter::direction
2d 3h ago	Direction::Suffix via SpanPrinter::direction
9.123456789s	FractionalUnit::Second via SpanPrinter::fractional
1y, 2mo	SpanPrinter::comma_after_designator
15d 02:59:15.123	SpanPrinter::hours_minutes_seconds

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.

Example	Format string
2025-05-20	%Y-%m-%d
2025-05-20	%F
2025-W21-2	%G-W%V-%w
05/20/25	%m/%d/%y
Monday, February 10, 2025 at 9:01pm -0500	%A, %B %d, %Y at %-I:%M%P %z
Monday, February 10, 2025 at 9:01pm EST	%A, %B %d, %Y at %-I:%M%P %Z
Monday, February 10, 2025 at 9:01pm America/New_York	%A, %B %d, %Y at %-I:%M%P %Q

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.

Example	Links
Thu, 29 Feb 2024 05:34 -0500	rfc2822::parse and rfc2822::to_string
Thu, 01 Jan 1970 00:00:01 GMT	DateTimePrinter::timestamp_to_rfc9110_string

Modules

• friendly
  A bespoke but easy to read format for Span and SignedDuration.
• rfc2822
  Support for printing and parsing instants using the RFC 2822 datetime format.
• serde
  This module provides helpers to use with Serde.
• strtime
  Support for “printf”-style parsing and formatting.
• temporal
  A hybrid format derived from RFC 3339, RFC 9557 and ISO 8601.

Structs

• StdFmtWrite
  An adapter for using std::fmt::Write implementations with fmt::Write.
• StdIoWrite
  An adapter for using std::io::Write implementations with fmt::Write.

Traits

• Write
  A trait for printing datetimes or spans into Unicode-accepting buffers or streams.