Struct OffsetRound

pub struct OffsetRound(/* private fields */);

Available on crate features dep_jiff and alloc only.

Options for Offset::round.

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

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

• From<Unit> for OffsetRound will construct a rounding configuration where the smallest unit is set to the one given.
• From<(Unit, i64)> for OffsetRound 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 OffsetRound and pass it to Offset::round.

Example

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

use jiff::{tz::{Offset, OffsetRound}, RoundMode, Unit};

let offset = Offset::from_seconds(4 * 60 * 60 + 17 * 60).unwrap();
let rounded = offset.round(
    OffsetRound::new()
        .smallest(Unit::Minute)
        .increment(30)
        .mode(RoundMode::Expand),
)?;
assert_eq!(rounded, Offset::from_seconds(4 * 60 * 60 + 30 * 60).unwrap());

Implementations

impl OffsetRound

pub fn new() -> OffsetRound

Create a new default configuration for rounding a time zone offset via Offset::round.

The default configuration does no rounding.

pub fn smallest(self, unit: Unit) -> OffsetRound

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

Errors

The unit must be Unit::Hour, Unit::Minute or Unit::Second.

Example

A basic example that rounds to the nearest minute:

use jiff::{tz::Offset, Unit};

let offset = Offset::from_seconds(-(5 * 60 * 60 + 30)).unwrap();
assert_eq!(offset.round(Unit::Hour)?, Offset::from_hours(-5).unwrap());

pub fn mode(self, mode: RoundMode) -> OffsetRound

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 hour, but changing its rounding mode to truncation:

use jiff::{tz::{Offset, OffsetRound}, RoundMode, Unit};

let offset = Offset::from_seconds(-(5 * 60 * 60 + 30 * 60)).unwrap();
assert_eq!(
    offset.round(OffsetRound::new()
        .smallest(Unit::Hour)
        .mode(RoundMode::Trunc),
    )?,
    // The default round mode does rounding like
    // how you probably learned in school, and would
    // result in rounding to -6 hours. But we
    // change it to truncation here, which makes it
    // round -5.
    Offset::from_hours(-5).unwrap(),
);

pub fn increment(self, increment: i64) -> OffsetRound

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::Second, then some of the valid values for the rounding increment are 1, 2, 4, 5, 15 and 30. Namely, any integer that divides evenly into 60 seconds since there are 60 seconds in the next highest unit (minutes).

Example

This shows how to round an offset to the nearest 30 minute increment:

use jiff::{tz::Offset, Unit};

let offset = Offset::from_seconds(4 * 60 * 60 + 15 * 60).unwrap();
assert_eq!(
    offset.round((Unit::Minute, 30))?,
    Offset::from_seconds(4 * 60 * 60 + 30 * 60).unwrap(),
);

Trait Implementations

impl Clone for OffsetRound

fn clone(&self) -> OffsetRound

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for OffsetRound

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

Formats the value using the given formatter.

impl Default for OffsetRound

fn default() -> OffsetRound

Returns the “default value” for a type.

impl From<(Unit, i64)> for OffsetRound

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

Converts to this type from the input type.

impl From<Unit> for OffsetRound

fn from(unit: Unit) -> OffsetRound

Converts to this type from the input type.

impl Copy for OffsetRound