Trait ToSpan

trait ToSpan: Sized

A trait for enabling concise literals for creating Span values.

In short, this trait lets you write something like 5.seconds() or 1.day() to create a Span. Once a Span has been created, you can use its mutator methods to add more fields. For example, 1.day().hours(10) is equivalent to Span::new().days(1).hours(10).

This trait is implemented for the following integer types: i8, i16, i32 and i64.

Note that this trait is provided as a convenience and should generally only be used for literals in your source code. You should not use this trait on numbers provided by end users. Namely, if the number provided is not within Jiff's span limits, then these trait methods will panic. Instead, use fallible mutator constructors like Span::try_days or Span::try_seconds.

Example

use jiff::ToSpan;

assert_eq!(5.days().to_string(), "P5D");
assert_eq!(5.days().hours(10).to_string(), "P5DT10H");

// Negation works and it doesn't matter where the sign goes. It can be
// applied to the span itself or to the integer.
assert_eq!((-5.days()).to_string(), "-P5D");
assert_eq!((-5).days().to_string(), "-P5D");

Example: alternative via span parsing

Another way of tersely building a Span value is by parsing a ISO 8601 duration string:

use jiff::Span;

let span = "P5y2m15dT23h30m10s".parse::<Span>()?;
assert_eq!(
    span.fieldwise(),
    Span::new().years(5).months(2).days(15).hours(23).minutes(30).seconds(10),
);

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

Required Methods

fn years(self: Self) -> Span

Create a new span from this integer in units of years.

Panics

When Span::new().years(self) would panic.

fn months(self: Self) -> Span

Create a new span from this integer in units of months.

Panics

When Span::new().months(self) would panic.

fn weeks(self: Self) -> Span

Create a new span from this integer in units of weeks.

Panics

When Span::new().weeks(self) would panic.

fn days(self: Self) -> Span

Create a new span from this integer in units of days.

Panics

When Span::new().days(self) would panic.

fn hours(self: Self) -> Span

Create a new span from this integer in units of hours.

Panics

When Span::new().hours(self) would panic.

fn minutes(self: Self) -> Span

Create a new span from this integer in units of minutes.

Panics

When Span::new().minutes(self) would panic.

fn seconds(self: Self) -> Span

Create a new span from this integer in units of seconds.

Panics

When Span::new().seconds(self) would panic.

fn milliseconds(self: Self) -> Span

Create a new span from this integer in units of milliseconds.

Panics

When Span::new().milliseconds(self) would panic.

fn microseconds(self: Self) -> Span

Create a new span from this integer in units of microseconds.

Panics

When Span::new().microseconds(self) would panic.

fn nanoseconds(self: Self) -> Span

Create a new span from this integer in units of nanoseconds.

Panics

When Span::new().nanoseconds(self) would panic.

Provided Methods

fn year(self: Self) -> Span

Equivalent to years(), but reads better for singular units.

fn month(self: Self) -> Span

Equivalent to months(), but reads better for singular units.

fn week(self: Self) -> Span

Equivalent to weeks(), but reads better for singular units.

fn day(self: Self) -> Span

Equivalent to days(), but reads better for singular units.

fn hour(self: Self) -> Span

Equivalent to hours(), but reads better for singular units.

fn minute(self: Self) -> Span

Equivalent to minutes(), but reads better for singular units.

fn second(self: Self) -> Span

Equivalent to seconds(), but reads better for singular units.

fn millisecond(self: Self) -> Span

Equivalent to milliseconds(), but reads better for singular units.

fn microsecond(self: Self) -> Span

Equivalent to microseconds(), but reads better for singular units.

fn nanosecond(self: Self) -> Span

Equivalent to nanoseconds(), but reads better for singular units.

Implementors