Struct SpanRound

pub struct SpanRound<'a> { /* private fields */ }

Options for Span::round.

This type provides a way to configure the rounding of a span. This includes setting the smallest unit (i.e., the unit to round), the largest unit, the rounding increment, the rounding mode (e.g., “ceil” or “truncate”) and the datetime that the span is relative to.

Span::round accepts anything that implements Into<SpanRound>. There are a few key trait implementations that make this convenient:

• From<Unit> for SpanRound will construct a rounding configuration where the smallest unit is set to the one given.
• From<(Unit, i64)> for SpanRound will construct a rounding configuration where the smallest unit and the rounding increment are set to the ones given.

In order to set other options (like the largest unit, the rounding mode and the relative datetime), one must explicitly create a SpanRound and pass it to Span::round.

Example

This example shows how to find how many full 3 month quarters are in a particular span of time.

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

let span1 = 10.months().days(15);
let round = SpanRound::new()
    .smallest(Unit::Month)
    .increment(3)
    .mode(RoundMode::Trunc)
    // A relative datetime must be provided when
    // rounding involves calendar units.
    .relative(date(2024, 1, 1));
let span2 = span1.round(round)?;
assert_eq!(span2.get_months() / 3, 3);

Implementations

impl<'a> SpanRound<'a>

pub fn new() -> SpanRound<'static>

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

The default configuration does no rounding.

pub fn smallest(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());

pub fn largest(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),
);

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

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

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

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

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.

pub fn mode(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(),
);

pub fn increment(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(),
);

pub fn relative<R>(self, relative: R) -> SpanRound<'a>

where R: Into<SpanRelativeTo<'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());

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

pub fn days_are_24_hours(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());

Trait Implementations

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

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

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

impl Default for SpanRound<'static>

fn default() -> SpanRound<'static>

Returns the “default value” for a type.

impl From<(Unit, i64)> for SpanRound<'static>

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

Converts to this type from the input type.

impl From<Unit> for SpanRound<'static>

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

Converts to this type from the input type.

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