Trait ToSpan

pub trait ToSpan: Sized {
    // Required methods
    fn years(self) -> Span;
    fn months(self) -> Span;
    fn weeks(self) -> Span;
    fn days(self) -> Span;
    fn hours(self) -> Span;
    fn minutes(self) -> Span;
    fn seconds(self) -> Span;
    fn milliseconds(self) -> Span;
    fn microseconds(self) -> Span;
    fn nanoseconds(self) -> Span;

    // Provided methods
    fn year(self) -> Span { ... }
    fn month(self) -> Span { ... }
    fn week(self) -> Span { ... }
    fn day(self) -> Span { ... }
    fn hour(self) -> Span { ... }
    fn minute(self) -> Span { ... }
    fn second(self) -> Span { ... }
    fn millisecond(self) -> Span { ... }
    fn microsecond(self) -> Span { ... }
    fn nanosecond(self) -> Span { ... }
}

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

Required Methods

fn years(self) -> Span

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

Panics

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

fn months(self) -> Span

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

Panics

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

fn weeks(self) -> Span

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

Panics

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

fn days(self) -> Span

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

Panics

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

fn hours(self) -> Span

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

Panics

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

fn minutes(self) -> Span

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

Panics

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

fn seconds(self) -> Span

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

Panics

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

fn milliseconds(self) -> Span

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

Panics

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

fn microseconds(self) -> Span

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

Panics

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

fn nanoseconds(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) -> Span

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

fn month(self) -> Span

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

fn week(self) -> Span

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

fn day(self) -> Span

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

fn hour(self) -> Span

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

fn minute(self) -> Span

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

fn second(self) -> Span

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

fn millisecond(self) -> Span

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

fn microsecond(self) -> Span

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

fn nanosecond(self) -> Span

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

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl ToSpan for i8

fn years(self) -> Span

fn months(self) -> Span

fn weeks(self) -> Span

fn days(self) -> Span

fn hours(self) -> Span

fn minutes(self) -> Span

fn seconds(self) -> Span

fn milliseconds(self) -> Span

fn microseconds(self) -> Span

fn nanoseconds(self) -> Span

impl ToSpan for i16

fn years(self) -> Span

fn months(self) -> Span

fn weeks(self) -> Span

fn days(self) -> Span

fn hours(self) -> Span

fn minutes(self) -> Span

fn seconds(self) -> Span

fn milliseconds(self) -> Span

fn microseconds(self) -> Span

fn nanoseconds(self) -> Span

impl ToSpan for i32

fn years(self) -> Span

fn months(self) -> Span

fn weeks(self) -> Span

fn days(self) -> Span

fn hours(self) -> Span

fn minutes(self) -> Span

fn seconds(self) -> Span

fn milliseconds(self) -> Span

fn microseconds(self) -> Span

fn nanoseconds(self) -> Span

impl ToSpan for i64

fn years(self) -> Span

fn months(self) -> Span

fn weeks(self) -> Span

fn days(self) -> Span

fn hours(self) -> Span

fn minutes(self) -> Span

fn seconds(self) -> Span

fn milliseconds(self) -> Span

fn microseconds(self) -> Span

fn nanoseconds(self) -> Span

Implementors