pub struct Display<'f> { /* private fields */ }Expand description
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");
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");