Create a new default Config that uses DefaultCustom.

Set the implementation of Custom to use in strtime-style APIs that use this configuration.

Enable lenient formatting.

When this is enabled, most errors that occur during formatting are silently ignored. For example, if you try to format %z with a BrokenDownTime that lacks a time zone offset, this would normally result in an error. In contrast, when lenient mode is enabled, this would just result in %z being written literally. Similarly, using invalid UTF-8 in the format string would normally result in an error. In lenient mode, invalid UTF-8 is automatically turned into the Unicode replacement codepoint U+FFFD (which looks like this: �).

Generally speaking, when this is enabled, the only error that can occur when formatting is if a write to the underlying writer fails. When using a writer that never errors (like String, unless allocation fails), it follows that enabling lenient parsing will result in a formatting operation that never fails (unless allocation fails).

This currently has no effect on parsing, although this may change in the future.

Lenient formatting is disabled by default. It is strongly recommended to keep it disabled in order to avoid mysterious failure modes for end users. You should only enable this if you have strict requirements to conform to legacy software behavior.

API stability

An artifact of lenient parsing is that most error behaviors are squashed in favor of writing the errant conversion specifier literally. This means that if you use something like %+, which is currently unrecognized, then that will result in a literal %+ in the string returned. But Jiff may one day add support for %+ in a semver compatible release.

Stated differently, the set of unknown or error conditions is not fixed and may decrease with time. This in turn means that the precise conditions under which a conversion specifier gets written literally to the resulting string may change over time in semver compatible releases of Jiff.

The alternative would be that Jiff could never add any new conversion specifiers without making a semver incompatible release. The intent of this policy is to avoid that scenario and permit reasonable evolution of Jiff's strtime support.

Example

This example shows how %z will be written literally if it would otherwise fail:

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

let tm = BrokenDownTime::from(civil::date(2025, 4, 30));
assert_eq!(
    tm.to_string("%F %z").unwrap_err().to_string(),
    "strftime formatting failed: %z failed: \
     requires time zone offset",
);

// Now enable lenient mode:
let config = Config::new().lenient(true);
assert_eq!(
    tm.to_string_with_config(&config, "%F %z").unwrap(),
    "2025-04-30 %z",
);

// Lenient mode also applies when using an unsupported
// or unrecognized conversion specifier. This would
// normally return an error for example:
assert_eq!(
    tm.to_string_with_config(&config, "%+ %0").unwrap(),
    "%+ %0",
);