Enum Unit

pub enum Unit {
    Year = 9,
    Month = 8,
    Week = 7,
    Day = 6,
    Hour = 5,
    Minute = 4,
    Second = 3,
    Millisecond = 2,
    Microsecond = 1,
    Nanosecond = 0,
}

A way to refer to a single calendar or clock unit.

This type is principally used in APIs involving a Span, which is a duration of time. For example, routines like Zoned::until permit specifying the largest unit of the span returned:

use jiff::{Unit, Zoned};

let zdt1: Zoned = "2024-07-06 17:40-04[America/New_York]".parse()?;
let zdt2: Zoned = "2024-11-05 08:00-05[America/New_York]".parse()?;
let span = zdt1.until((Unit::Year, &zdt2))?;
assert_eq!(format!("{span:#}"), "3mo 29d 14h 20m");

But a Unit is also used in APIs for rounding datetimes themselves:

use jiff::{Unit, Zoned};

let zdt: Zoned = "2024-07-06 17:44:22.158-04[America/New_York]".parse()?;
let nearest_minute = zdt.round(Unit::Minute)?;
assert_eq!(
    nearest_minute.to_string(),
    "2024-07-06T17:44:00-04:00[America/New_York]",
);

Example: ordering

This example demonstrates that Unit has an ordering defined such that bigger units compare greater than smaller units.

use jiff::Unit;

assert!(Unit::Year > Unit::Nanosecond);
assert!(Unit::Day > Unit::Hour);
assert!(Unit::Hour > Unit::Minute);
assert!(Unit::Hour > Unit::Minute);
assert_eq!(Unit::Hour, Unit::Hour);

Variants

Year = 9

A Gregorian calendar year. It usually has 365 days for non-leap years, and 366 days for leap years.

Month = 8

A Gregorian calendar month. It usually has one of 28, 29, 30 or 31 days.

Week = 7

A week is 7 days that either begins on Sunday or Monday.

Day = 6

A day is usually 24 hours, but some days may have different lengths due to time zone transitions.

Hour = 5

An hour is always 60 minutes.

Minute = 4

A minute is always 60 seconds. (Jiff behaves as if leap seconds do not exist.)

Second = 3

A second is always 1,000 milliseconds.

Millisecond = 2

A millisecond is always 1,000 microseconds.

Microsecond = 1

A microsecond is always 1,000 nanoseconds.

Nanosecond = 0

A nanosecond is the smallest granularity of time supported by Jiff.

Implementations

impl Unit

pub(crate) fn next(&self) -> Option<Unit>

Returns the next biggest unit, if one exists.

pub(crate) fn nanoseconds(self) -> ri128<{ i128::MIN }, { i128::MAX }>

Returns the number of nanoseconds in this unit as a 128-bit integer.

Panics

When this unit is always variable. That is, years or months.

fn is_variable(self) -> bool

Returns true when this unit is definitively variable.

In effect, this is any unit bigger than ‘day’, because any such unit can vary in time depending on its reference point. A ‘day’ can as well, but we sorta special case ‘day’ to mean ‘24 hours’ for cases where the user is dealing with civil time.

pub(crate) fn singular(&self) -> &'static str

A human readable singular description of this unit of time.

pub(crate) fn plural(&self) -> &'static str

A human readable plural description of this unit of time.

pub(crate) fn compact(&self) -> &'static str

A very succinct label corresponding to this unit.

fn from_usize(n: usize) -> Option<Unit>

The inverse of unit as usize.

Trait Implementations

impl Clone for Unit

fn clone(&self) -> Unit

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Unit

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

Formats the value using the given formatter.

impl From<FractionalUnit> for Unit

fn from(u: FractionalUnit) -> Unit

Converts to this type from the input type.

impl From<Unit> for DateTimeRound

fn from(unit: Unit) -> DateTimeRound

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 From<Unit> for SignedDurationRound

fn from(unit: Unit) -> SignedDurationRound

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 From<Unit> for SpanTotal<'static>

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

Converts to this type from the input type.

impl From<Unit> for TimeRound

fn from(unit: Unit) -> TimeRound

Converts to this type from the input type.

impl From<Unit> for TimestampRound

fn from(unit: Unit) -> TimestampRound

Converts to this type from the input type.

impl From<Unit> for ZonedRound

fn from(unit: Unit) -> ZonedRound

Converts to this type from the input type.

impl Hash for Unit

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Unit

fn cmp(&self, other: &Unit) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Unit

fn eq(&self, other: &Unit) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Unit

fn partial_cmp(&self, other: &Unit) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Unit

impl Eq for Unit

impl StructuralPartialEq for Unit