Struct OffsetRound

struct OffsetRound(_)

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:

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

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

Implementations

impl OffsetRound

fn new() -> OffsetRound

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

The default configuration does no rounding.

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

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

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

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

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

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

impl Clone for OffsetRound

fn clone(self: &Self) -> OffsetRound

impl Copy for OffsetRound

impl Debug for OffsetRound

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

impl Default for OffsetRound

fn default() -> OffsetRound

impl Freeze for OffsetRound

impl From for OffsetRound

fn from((unit, increment): (Unit, i64)) -> OffsetRound

impl From for OffsetRound

fn from(unit: Unit) -> OffsetRound

impl RefUnwindSafe for OffsetRound

impl Send for OffsetRound

impl Sync for OffsetRound

impl Unpin for OffsetRound

impl UnsafeUnpin for OffsetRound

impl UnwindSafe for OffsetRound

impl<T> Any for OffsetRound

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for OffsetRound

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

impl<T> BorrowMut for OffsetRound

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

impl<T> CloneToUninit for OffsetRound

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

impl<T> From for OffsetRound

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for OffsetRound

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

impl<T, U> Into for OffsetRound

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 OffsetRound

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

impl<T, U> TryInto for OffsetRound

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