Struct `SignedDurationRound`

struct SignedDurationRound { ... }

Options for SignedDuration::round.

This type provides a way to configure the rounding of a duration. This includes setting the smallest unit (i.e., the unit to round), the rounding increment and the rounding mode (e.g., "ceil" or "truncate").

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

From<Unit> for SignedDurationRound will construct a rounding configuration where the smallest unit is set to the one given.
From<(Unit, i64)> for SignedDurationRound 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 rounding mode), one must explicitly create a SignedDurationRound and pass it to SignedDuration::round.

Example

This example shows how to always round up to the nearest half-minute:

use jiff::{RoundMode, SignedDuration, SignedDurationRound, Unit};

let dur = SignedDuration::new(4 * 60 * 60 + 17 * 60 + 1, 123_456_789);
let rounded = dur.round(
    SignedDurationRound::new()
        .smallest(Unit::Second)
        .increment(30)
        .mode(RoundMode::Expand),
)?;
assert_eq!(rounded, SignedDuration::from_secs(4 * 60 * 60 + 17 * 60 + 30));

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

Implementations

`impl SignedDurationRound`

fn new() -> SignedDurationRound

Create a new default configuration for rounding a signed duration via SignedDuration::round.

The default configuration does no rounding.

fn smallest(self: Self, unit: Unit) -> SignedDurationRound

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

Errors

The unit must be Unit::Hour or smaller.

Example

A basic example that rounds to the nearest minute:

use jiff::{SignedDuration, Unit};

let duration = SignedDuration::new(15 * 60 + 46, 0);
assert_eq!(duration.round(Unit::Minute)?, SignedDuration::from_mins(16));

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

fn mode(self: Self, mode: RoundMode) -> SignedDurationRound

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, SignedDuration, SignedDurationRound, Unit};

let duration = SignedDuration::new(15 * 60 + 46, 0);
assert_eq!(
    duration.round(SignedDurationRound::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.
    SignedDuration::from_mins(15),
);

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

fn increment(self: Self, increment: i64) -> SignedDurationRound

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

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).

Example

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

use jiff::{SignedDuration, Unit};

let duration = SignedDuration::new(4 * 60 * 60 + 2 * 60 + 30, 0);
assert_eq!(
    duration.round((Unit::Minute, 5))?,
    SignedDuration::new(4 * 60 * 60 + 5 * 60, 0),
);

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