Struct SpanPrinter

struct SpanPrinter { ... }

A printer for Temporal durations.

Note that in Jiff, a "Temporal duration" is called a "span."

This printer converts an in memory representation of a duration of time to a machine (but also human) readable format. Using this printer, one can convert a Span to a string. Note that a Span provides a Display trait implementation that utilize the default configuration of this printer. However, this printer can print directly to anything that implements the fmt::Write trait.

See the fmt::temporal module documentation for more information on the specific format used.

Example

This is a basic example showing how to print a Span directly to a Vec<u8>.

use jiff::{fmt::temporal::SpanPrinter, ToSpan};

// A printer can be created in a const context.
const PRINTER: SpanPrinter = SpanPrinter::new();

let span = 48.minutes();
let mut buf = vec![];
// Printing to a `Vec<u8>` can never fail.
PRINTER.print_span(&span, &mut buf).unwrap();
assert_eq!(buf, "PT48M".as_bytes());

Example: using adapters with std::io::Write and std::fmt::Write

By using the StdIoWrite and StdFmtWrite adapters, one can print spans directly to implementations of std::io::Write and std::fmt::Write, respectively. The example below demonstrates writing to anything that implements std::io::Write. Similar code can be written for std::fmt::Write.

use std::{fs::File, io::{BufWriter, Write}, path::Path};

use jiff::{fmt::{StdIoWrite, temporal::SpanPrinter}, ToSpan};

let span = 48.minutes();

let path = Path::new("/tmp/output");
let mut file = BufWriter::new(File::create(path)?);
SpanPrinter::new().print_span(&span, StdIoWrite(&mut file)).unwrap();
file.flush()?;
assert_eq!(std::fs::read_to_string(path)?, "PT48m");

# Ok::<(), Box<dyn std::error::Error>>(())

Implementations

impl SpanPrinter

const fn new() -> SpanPrinter

Create a new Temporal span printer with the default configuration.

const fn lowercase(self: Self, yes: bool) -> SpanPrinter

Use lowercase for unit designator labels.

By default, unit designator labels are written in uppercase.

Example

This shows the difference between the default (uppercase) and enabling lowercase. Lowercase unit designator labels tend to be easier to read (in this author's opinion), but they aren't as broadly supported since they are an extension to ISO 8601.

use jiff::{fmt::temporal::SpanPrinter, ToSpan};

let span = 5.years().days(10).hours(1);
let printer = SpanPrinter::new();
assert_eq!(printer.span_to_string(&span), "P5Y10DT1H");
assert_eq!(printer.lowercase(true).span_to_string(&span), "P5y10dT1h");

fn span_to_string(self: &Self, span: &Span) -> alloc::string::String

Format a Span into a string.

This is a convenience routine for SpanPrinter::print_span with a String.

Example

use jiff::{fmt::temporal::SpanPrinter, ToSpan};

const PRINTER: SpanPrinter = SpanPrinter::new();

let span = 3.years().months(5);
assert_eq!(PRINTER.span_to_string(&span), "P3Y5M");

# Ok::<(), Box<dyn std::error::Error>>(())

fn duration_to_string(self: &Self, duration: &SignedDuration) -> alloc::string::String

Format a SignedDuration into a string.

This balances the units of the duration up to at most hours automatically.

This is a convenience routine for SpanPrinter::print_duration with a String.

Example

use jiff::{fmt::temporal::SpanPrinter, SignedDuration};

const PRINTER: SpanPrinter = SpanPrinter::new();

let dur = SignedDuration::new(86_525, 123_000_789);
assert_eq!(PRINTER.duration_to_string(&dur), "PT24H2M5.123000789S");
assert_eq!(PRINTER.duration_to_string(&-dur), "-PT24H2M5.123000789S");

# Ok::<(), Box<dyn std::error::Error>>(())

fn print_span<W: Write>(self: &Self, span: &Span, wtr: W) -> Result<(), Error>

Print a Span to the given writer.

Errors

This only returns an error when writing to the given Write implementation would fail. Some such implementations, like for String and Vec<u8>, never fail (unless memory allocation fails). In such cases, it would be appropriate to call unwrap() on the result.

Example

use jiff::{fmt::temporal::SpanPrinter, ToSpan};

const PRINTER: SpanPrinter = SpanPrinter::new();

let span = 3.years().months(5);

let mut buf = String::new();
// Printing to a `String` can never fail.
PRINTER.print_span(&span, &mut buf).unwrap();
assert_eq!(buf, "P3Y5M");

# Ok::<(), Box<dyn std::error::Error>>(())

fn print_duration<W: Write>(self: &Self, duration: &SignedDuration, wtr: W) -> Result<(), Error>

Print a SignedDuration to the given writer.

This balances the units of the duration up to at most hours automatically.

Errors

This only returns an error when writing to the given Write implementation would fail. Some such implementations, like for String and Vec<u8>, never fail (unless memory allocation fails). In such cases, it would be appropriate to call unwrap() on the result.

Example

use jiff::{fmt::temporal::SpanPrinter, SignedDuration};

const PRINTER: SpanPrinter = SpanPrinter::new();

let dur = SignedDuration::new(86_525, 123_000_789);

let mut buf = String::new();
// Printing to a `String` can never fail.
PRINTER.print_duration(&dur, &mut buf).unwrap();
assert_eq!(buf, "PT24H2M5.123000789S");

// Negative durations are supported.
buf.clear();
PRINTER.print_duration(&-dur, &mut buf).unwrap();
assert_eq!(buf, "-PT24H2M5.123000789S");

# Ok::<(), Box<dyn std::error::Error>>(())

impl Debug for SpanPrinter

fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<'_>) -> $crate::fmt::Result

impl Freeze for SpanPrinter

impl RefUnwindSafe for SpanPrinter

impl Send for SpanPrinter

impl Sync for SpanPrinter

impl Unpin for SpanPrinter

impl UnwindSafe for SpanPrinter

impl<T> Any for SpanPrinter

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for SpanPrinter

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for SpanPrinter

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> From for SpanPrinter

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into for SpanPrinter

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for SpanPrinter

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for SpanPrinter

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>