Struct SpanPrinter

pub struct SpanPrinter { /* private fields */ }

Available on crate features dep_jiff and alloc only.

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");

Implementations

impl SpanPrinter

pub const fn new() -> SpanPrinter

Create a new Temporal span printer with the default configuration.

pub const fn lowercase(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");

pub fn span_to_string(&self, span: &Span) -> 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");

pub fn duration_to_string(&self, duration: &SignedDuration) -> 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");

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

where W: Write,

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");

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

where W: Write,

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");

Trait Implementations

impl Debug for SpanPrinter

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

Formats the value using the given formatter.