jiff::fmt::strtime

Trait Custom

Source 
pub trait Custom: Sized {
    // Provided methods
    fn format_datetime<W: Write>(
        &self,
        config: &Config<Self>,
        _ext: &Extension,
        tm: &BrokenDownTime,
        wtr: &mut W,
    ) -> Result<(), Error> { ... }
    fn format_date<W: Write>(
        &self,
        config: &Config<Self>,
        _ext: &Extension,
        tm: &BrokenDownTime,
        wtr: &mut W,
    ) -> Result<(), Error> { ... }
    fn format_time<W: Write>(
        &self,
        config: &Config<Self>,
        _ext: &Extension,
        tm: &BrokenDownTime,
        wtr: &mut W,
    ) -> Result<(), Error> { ... }
    fn format_12hour_time<W: Write>(
        &self,
        config: &Config<Self>,
        _ext: &Extension,
        tm: &BrokenDownTime,
        wtr: &mut W,
    ) -> Result<(), Error> { ... }
}
Expand description

An interface for customizing strtime-style parsing and formatting.

Each method on this trait comes with a default implementation corresponding to the behavior of DefaultCustom. More methods on this trait may be added in the future.

Implementors of this trait can be attached to a Config which can then be passed to BrokenDownTime::format_with_config or BrokenDownTime::to_string_with_config.

New methods with default implementations may be added to this trait in semver compatible releases of Jiff.

§Motivation

While Jiff’s API is generally locale-agnostic, this trait is meant to provide a best effort “hook” for tailoring the behavior of strtime routines. More specifically, for conversion specifiers in strtime-style APIs that are influenced by locale settings.

In general, a strtime-style API is not optimal for localization. It’s both too flexible and not expressive enough. As a result, mixing localization with strtime-style APIs is likely not a good idea. However, this is sometimes required for legacy or convenience reasons, and that’s why Jiff provides this hook.

If you do need to localize datetimes but don’t have a requirement to have it integrate with strtime-style APIs, then you should use the icu crate via jiff-icu for type conversions. And then follow the examples in the icu::datetime API for formatting datetimes.

§Supported conversion specifiers

Currently, only formatting for the following specifiers is supported:

  • %c - Formatting the date and time.
  • %r - Formatting the 12-hour clock time.
  • %X - Formatting the clock time.
  • %x - Formatting the date.

§Unsupported behavior

This trait currently does not support parsing based on locale in any way.

This trait also does not support locale specific behavior for %a/%A (day of the week), %b/%B(name of the month) or%p/%P` (AM or PM). Supporting these is problematic with modern localization APIs, since modern APIs do not expose options to localize these things independent of anything else. Instead, they are subsumed most holistically into, e.g., “print the long form of a date in the current locale.”

Since the motivation for this trait is not really to provide the best way to localize datetimes, but rather, to facilitate convenience and inter-operation with legacy systems, it is plausible that the behaviors listed above could be supported by Jiff. If you need the above behaviors, please open a new issue with a proposal.

§Example

This example shows the difference between the default locale and the POSIX locale:

use jiff::{civil, fmt::strtime::{BrokenDownTime, PosixCustom, Config}};

let dt = civil::date(2025, 7, 1).at(17, 30, 0, 0);
let tm = BrokenDownTime::from(dt);
assert_eq!(
    tm.to_string("%c")?,
    "2025 M07 1, Tue 17:30:00",
);

let config = Config::new().custom(PosixCustom::new());
assert_eq!(
    tm.to_string_with_config(&config, "%c")?,
    "Tue Jul  1 17:30:00 2025",
);

Provided Methods§

Source

fn format_datetime<W: Write>( &self, config: &Config<Self>, _ext: &Extension, tm: &BrokenDownTime, wtr: &mut W, ) -> Result<(), Error>

Called when formatting a datetime with the %c flag.

This defaults to the implementation for DefaultCustom.

Source

fn format_date<W: Write>( &self, config: &Config<Self>, _ext: &Extension, tm: &BrokenDownTime, wtr: &mut W, ) -> Result<(), Error>

Called when formatting a datetime with the %x flag.

This defaults to the implementation for DefaultCustom.

Source

fn format_time<W: Write>( &self, config: &Config<Self>, _ext: &Extension, tm: &BrokenDownTime, wtr: &mut W, ) -> Result<(), Error>

Called when formatting a datetime with the %X flag.

This defaults to the implementation for DefaultCustom.

Source

fn format_12hour_time<W: Write>( &self, config: &Config<Self>, _ext: &Extension, tm: &BrokenDownTime, wtr: &mut W, ) -> Result<(), Error>

Called when formatting a datetime with the %r flag.

This defaults to the implementation for DefaultCustom.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§