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 configures formatting to use lenient mode. This avoids panics occuring when using APIs like Timestamp::strftime with unsupported or invalid formatting directives. Without lenient mode, whenever formatting would fail, this would surface as a panic when converting this display implementation to a string.

Example

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

use jiff::civil::date;

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};

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

Example: errors are silently ignored

If the formatting string is malformed in some way, then it is silently ignored. For example, when using an invalid formatting directive:

use jiff::Zoned;

let zdt = Zoned::UNIX_EPOCH;
let string = zdt.strftime("%Y %").to_string();
assert_eq!(string, "1970 %");

If one wants to surface errors from a formatting string, use a lower level API:

use jiff::Zoned;

let zdt = Zoned::UNIX_EPOCH;
assert_eq!(
    jiff::fmt::strtime::format("%Y %", &zdt).unwrap_err().to_string(),
    "strftime formatting failed: invalid format string, \
     expected byte after `%`, but found end of format string",
);