Enum `Designator`

#[non_exhaustive]
pub enum Designator

Configuration for SpanPrinter::designator.

This controls which kinds of designators to use when formatting a "friendly" duration. Generally, this only provides one axis of control: the length of each designator.

Example

use jiff::{fmt::friendly::{Designator, SpanPrinter}, ToSpan};

let span = 1.year().months(2);

let printer = SpanPrinter::new();
assert_eq!(printer.span_to_string(&span), "1y 2mo");

let printer = SpanPrinter::new().designator(Designator::Short);
assert_eq!(printer.span_to_string(&span), "1yr 2mos");

let printer = SpanPrinter::new().designator(Designator::Verbose);
assert_eq!(printer.span_to_string(&span), "1year 2months");

let printer = SpanPrinter::new().designator(Designator::HumanTime);
assert_eq!(printer.span_to_string(&span), "1y 2months");

Variants

Verbose

This writes out the full word of each unit designation. For example, year.

Short

This writes out a short but not minimal label for each unit. For example, yr for year and yrs for years.

Compact

This writes out the shortest possible label for each unit that is still generally recognizable. For example, y. Note that in the compact representation, and unlike the verbose and short representations, there is no distinction between singular or plural.

HumanTime

A special mode that uses designator labels that are known to be compatible with the humantime crate.

None of Verbose, Short or Compact are compatible with humantime.

Compact is, on its own, nearly compatible. When using Compact, all designator labels are parsable by humantime except for months and microseconds. For months, Jiff uses mo and mos, but humantime only parses months, month and M. Jiff specifically doesn't support M for months because of the confusability with minutes. For microseconds, Jiff uses µs which humantime does not support parsing.

Most of the designator labels Jiff uses for Short aren't supported by humantime. And even when they are, humantime is inconsistent. For example, humantime supports sec and secs, but only nsec and not nsecs.

Finally, for Verbose, humantime supports spelling out some units in their entirety (e.g., seconds) but not others (e.g., nanoseconds is not supported by humantime).

Therefore, this custom variant is provided so that designator labels that are compatible with both Jiff and humantime, even when there isn't a coherent concept otherwise connecting their style.