A "lazy" implementation of std::fmt::Display for strftime.

Values of this type are created by the strftime methods on the various datetime types in this crate. For example, [Zoned::strftime].

A Display captures the information needed from the datetime and waits to do the actual formatting when this type's std::fmt::Display trait implementation is actually used.

Errors and panics

This trait implementation returns an error when the underlying formatting can fail. Formatting can fail either because of an invalid format string, or if formatting requires a field in BrokenDownTime to be set that isn't. For example, trying to format a DateTime with the %z specifier will fail because a DateTime has no time zone or offset information associated with it.

Note though that the std::fmt::Display API doesn't support surfacing arbitrary errors. All errors collapse into the unit std::fmt::Error struct. To see the actual error, use BrokenDownTime::format, BrokenDownTime::to_string or strtime::format. Unfortunately, the std::fmt::Display trait is used in many places where there is no way to report errors other than panicking.

Therefore, only use this type if you know your formatting string is valid and that the datetime type being formatted has all of the information required by the format string. For most conversion specifiers, this falls in the category of things where "if it works, it works for all inputs." Unfortunately, there are some exceptions to this. For example, the %y modifier will only format a year if it falls in the range 1969-2068 and will otherwise return an error.

Example

This example shows how to format a zoned datetime using [Zoned::strftime]:

use jiff::{civil::date, fmt::strtime, tz};

let zdt = date(2024, 7, 15).at(16, 24, 59, 0).in_tz("America/New_York")?;
let string = zdt.strftime("%a, %-d %b %Y %T %z").to_string();
assert_eq!(string, "Mon, 15 Jul 2024 16:24:59 -0400");

# Ok::<(), Box<dyn std::error::Error>>(())

Or use it directly when writing to something:

use jiff::{civil::date, fmt::strtime, tz};

let zdt = date(2024, 7, 15).at(16, 24, 59, 0).in_tz("America/New_York")?;

let string = format!("the date is: {}", zdt.strftime("%-m/%-d/%-Y"));
assert_eq!(string, "the date is: 7/15/2024");

# Ok::<(), Box<dyn std::error::Error>>(())