Struct SignedDurationRound

pub struct SignedDurationRound { /* private fields */ }

Available on crate features dep_jiff and alloc only.

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

Implementations

impl SignedDurationRound

pub fn new() -> SignedDurationRound

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

The default configuration does no rounding.

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

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

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

Trait Implementations

impl Clone for SignedDurationRound

fn clone(&self) -> SignedDurationRound

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for SignedDurationRound

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

Formats the value using the given formatter.

impl Default for SignedDurationRound

fn default() -> SignedDurationRound

Returns the “default value” for a type.

impl From<(Unit, i64)> for SignedDurationRound

fn from(_: (Unit, i64)) -> SignedDurationRound

Converts to this type from the input type.

impl From<Unit> for SignedDurationRound

fn from(unit: Unit) -> SignedDurationRound

Converts to this type from the input type.

impl Copy for SignedDurationRound