impl<'a> SpanRound<'a>

fn new() -> SpanRound<'static>

Create a new default configuration for rounding a span via Span::round.

The default configuration does no rounding.

fn smallest(self: Self, unit: Unit) -> SpanRound<'a>

Set the smallest units allowed in the span returned. These are the units that the span is rounded to.

Errors

The smallest units must be no greater than the largest units. If this is violated, then rounding a span with this configuration will result in an error.

If a smallest unit bigger than days is selected without a relative datetime reference point, then an error is returned when using this configuration with Span::round.

Example

A basic example that rounds to the nearest minute:

use jiff::{ToSpan, Unit};

let span = 15.minutes().seconds(46);
assert_eq!(span.round(Unit::Minute)?, 16.minutes().fieldwise());

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

fn largest(self: Self, unit: Unit) -> SpanRound<'a>

Set the largest units allowed in the span returned.

When a largest unit is not specified, then it defaults to the largest non-zero unit that is at least as big as the configured smallest unit. For example, given a span of 2 months 17 hours, the default largest unit would be Unit::Month. The default implies that a span's units do not get "bigger" than what was given.

Once a largest unit is set, there is no way to change this rounding configuration back to using the "automatic" default. Instead, callers must create a new configuration.

If a largest unit is set and no other options are set, then the rounding operation can be said to be a "re-balancing." That is, the span won't lose precision, but the way in which it is expressed may change.

Errors

The largest units, when set, must be at least as big as the smallest units (which defaults to Unit::Nanosecond). If this is violated, then rounding a span with this configuration will result in an error.

If a largest unit bigger than days is selected without a relative datetime reference point, then an error is returned when using this configuration with Span::round.

Example: re-balancing

This shows how a span can be re-balanced without losing precision:

use jiff::{SpanRound, ToSpan, Unit};

let span = 86_401_123_456_789i64.nanoseconds();
assert_eq!(
    span.round(SpanRound::new().largest(Unit::Hour))?.fieldwise(),
    24.hours().seconds(1).milliseconds(123).microseconds(456).nanoseconds(789),
);

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

If you need to use a largest unit bigger than hours, then you must provide a relative datetime as a reference point (otherwise an error will occur):

use jiff::{civil::date, SpanRound, ToSpan, Unit};

let span = 3_968_000.seconds();
let round = SpanRound::new()
    .largest(Unit::Day)
    .relative(date(2024, 7, 1));
assert_eq!(
    span.round(round)?,
    45.days().hours(22).minutes(13).seconds(20).fieldwise(),
);

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

As a special case for days, one can instead opt into invariant 24-hour days (and 7-day weeks) without providing an explicit relative date:

use jiff::{SpanRound, ToSpan, Unit};

let span = 86_401_123_456_789i64.nanoseconds();
assert_eq!(
    span.round(
        SpanRound::new().largest(Unit::Day).days_are_24_hours(),
    )?.fieldwise(),
    1.day().seconds(1).milliseconds(123).microseconds(456).nanoseconds(789),
);

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

Example: re-balancing while taking DST into account

When given a zone aware relative datetime, rounding will even take DST into account:

use jiff::{SpanRound, ToSpan, Unit, Zoned};

let span = 2756.hours();
let zdt = "2020-01-01T00:00+01:00[Europe/Rome]".parse::<Zoned>()?;
let round = SpanRound::new().largest(Unit::Year).relative(&zdt);
assert_eq!(
    span.round(round)?,
    3.months().days(23).hours(21).fieldwise(),
);

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

Now compare with the same operation, but on a civil datetime (which is not aware of time zone):

use jiff::{civil::DateTime, SpanRound, ToSpan, Unit};

let span = 2756.hours();
let dt = "2020-01-01T00:00".parse::<DateTime>()?;
let round = SpanRound::new().largest(Unit::Year).relative(dt);
assert_eq!(
    span.round(round)?,
    3.months().days(23).hours(20).fieldwise(),
);

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

The result is 1 hour shorter. This is because, in the zone aware re-balancing, it accounts for the transition into DST at 2020-03-29T01:00Z, which skips an hour. This makes the span one hour longer because one of the days in the span is actually only 23 hours long instead of 24 hours.

fn mode(self: Self, mode: RoundMode) -> SpanRound<'a>

Set the rounding mode.

This defaults to RoundMode::HalfExpand, which makes rounding work like how you were taught in school.

Example

A basic example that rounds to the nearest minute, but changing its rounding mode to truncation:

use jiff::{RoundMode, SpanRound, ToSpan, Unit};

let span = 15.minutes().seconds(46);
assert_eq!(
    span.round(SpanRound::new()
        .smallest(Unit::Minute)
        .mode(RoundMode::Trunc),
    )?,
    // The default round mode does rounding like
    // how you probably learned in school, and would
    // result in rounding up to 16 minutes. But we
    // change it to truncation here, which makes it
    // round down.
    15.minutes().fieldwise(),
);

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

fn increment(self: Self, increment: i64) -> SpanRound<'a>

Set the rounding increment for the smallest unit.

The default value is 1. Other values permit rounding the smallest unit to the nearest integer increment specified. For example, if the smallest unit is set to Unit::Minute, then a rounding increment of 30 would result in rounding in increments of a half hour. That is, the only minute value that could result would be 0 or 30.

Errors

When the smallest unit is less than days, the rounding increment must divide evenly into the next highest unit after the smallest unit configured (and must not be equivalent to it). For example, if the smallest unit is Unit::Nanosecond, then some of the valid values for the rounding increment are 1, 2, 4, 5, 100 and 500. Namely, any integer that divides evenly into 1,000 nanoseconds since there are 1,000 nanoseconds in the next highest unit (microseconds).

The error will occur when computing the span, and not when setting the increment here.

Example

This shows how to round a span to the nearest 5 minute increment:

use jiff::{ToSpan, Unit};

let span = 4.hours().minutes(2).seconds(30);
assert_eq!(
    span.round((Unit::Minute, 5))?,
    4.hours().minutes(5).fieldwise(),
);

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

fn relative<R: Into<SpanRelativeTo<'a>>>(self: Self, relative: R) -> SpanRound<'a>

Set the relative datetime to use when rounding a span.

A relative datetime is only required when calendar units (units greater than days) are involved. This includes having calendar units in the original span, or calendar units in the configured smallest or largest unit. A relative datetime is required when calendar units are used because the duration of a particular calendar unit (like 1 month or 1 year) is variable and depends on the date. For example, 1 month from 2024-01-01 is 31 days, but 1 month from 2024-02-01 is 29 days.

A relative datetime is provided by anything that implements Into<SpanRelativeTo>. There are a few convenience trait implementations provided:

• From<&Zoned> for SpanRelativeTo uses a zone aware datetime to do rounding. In this case, rounding will take time zone transitions into account. In particular, when using a zoned relative datetime, not all days are necessarily 24 hours.
• From<civil::DateTime> for SpanRelativeTo uses a civil datetime. In this case, all days will be considered 24 hours long.
• From<civil::Date> for SpanRelativeTo uses a civil date. In this case, all days will be considered 24 hours long.

Note that one can impose 24-hour days without providing a reference date via SpanRelativeTo::days_are_24_hours.

Errors

If rounding involves a calendar unit (units bigger than hours) and no relative datetime is provided, then this configuration will lead to an error when used with Span::round.

Example

This example shows very precisely how a DST transition can impact rounding and re-balancing. For example, consider the day 2024-11-03 in America/New_York. On this day, the 1 o'clock hour was repeated, making the day 24 hours long. This will be taken into account when rounding if a zoned datetime is provided as a reference point:

use jiff::{SpanRound, ToSpan, Unit, Zoned};

let zdt = "2024-11-03T00-04[America/New_York]".parse::<Zoned>()?;
let round = SpanRound::new().largest(Unit::Hour).relative(&zdt);
assert_eq!(1.day().round(round)?, 25.hours().fieldwise());

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

And similarly for 2024-03-10, where the 2 o'clock hour was skipped entirely:

use jiff::{SpanRound, ToSpan, Unit, Zoned};

let zdt = "2024-03-10T00-05[America/New_York]".parse::<Zoned>()?;
let round = SpanRound::new().largest(Unit::Hour).relative(&zdt);
assert_eq!(1.day().round(round)?, 23.hours().fieldwise());

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

fn days_are_24_hours(self: Self) -> SpanRound<'a>

This is a convenience function for setting the relative option on this configuration to SpanRelativeTo::days_are_24_hours.

Example

When rounding spans involving days, either a relative datetime must be provided, or a special assertion opting into 24-hour days is required. Otherwise, you get an error.

use jiff::{SpanRound, ToSpan, Unit};

let span = 2.days().hours(12);
// No relative date provided, which results in an error.
assert_eq!(
    span.round(Unit::Day).unwrap_err().to_string(),
    "error with `smallest` rounding option: using unit 'day' in a \
     span or configuration requires that either a relative reference \
     time be given or `SpanRelativeTo::days_are_24_hours()` is used \
     to indicate invariant 24-hour days, but neither were provided",
);
let rounded = span.round(
    SpanRound::new().smallest(Unit::Day).days_are_24_hours(),
)?;
assert_eq!(rounded, 3.days().fieldwise());

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

impl Default for SpanRound<'static>

fn default() -> SpanRound<'static>

impl From for SpanRound<'static>

fn from(unit: Unit) -> SpanRound<'static>

impl From for SpanRound<'static>

fn from((unit, increment): (Unit, i64)) -> SpanRound<'static>

impl<'a> Clone for SpanRound<'a>

fn clone(self: &Self) -> SpanRound<'a>

impl<'a> Copy for SpanRound<'a>

impl<'a> Debug for SpanRound<'a>

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

impl<'a> Freeze for SpanRound<'a>

impl<'a> RefUnwindSafe for SpanRound<'a>

impl<'a> Send for SpanRound<'a>

impl<'a> Sync for SpanRound<'a>

impl<'a> Unpin for SpanRound<'a>

impl<'a> UnsafeUnpin for SpanRound<'a>

impl<'a> UnwindSafe for SpanRound<'a>

impl<T> Any for SpanRound<'a>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for SpanRound<'a>

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

impl<T> BorrowMut for SpanRound<'a>

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

impl<T> CloneToUninit for SpanRound<'a>

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for SpanRound<'a>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for SpanRound<'a>

fn to_owned(self: &Self) -> T

fn clone_into(self: &Self, target: &mut T)

impl<T, U> Into for SpanRound<'a>

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 SpanRound<'a>

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

impl<T, U> TryInto for SpanRound<'a>

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