Struct ResTime

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

A time with a resolution

To illustrate, consider these two times:

let t1 = ResTime::new().with_hour(15).with_minute(27).with_second(17);
let t2 = t1.with_millis(0);
assert_ne!(t1, t2);

In most date/time libraries, if you don’t specify the number of sub-second millis, it just sets them to zero. As a result, these values like t1 and t2 here would be considered equal. Not so with ResTime! Adding .with_millis(0) resulted in a different value. Previously the number of sub-second millis was unknown. Now it is known to be zero.

Equality and ordering

As illustrated above, the Eq impl considers resolution significant. Two ResTimes at different resolutions will never compare equal, even if one contains the other.

Likewise, ordering only exists between ResTimes of the same resolution. Within a resolution, ResTimes are totally ordered in the expected way. If you want to compare values of different resolutions, take a look at ResTime::coarse_cmp.

A day-spanning tree of time intervals

Including a resolution means each ResTime value actually identifies a certain time interval. You can lower the resolution, which increases the width of the interval.

The intervals at one resolution all fall completely inside a single interval at any lower resolution. This means that the intervals representable by ResTime form a tree, where each node is contained by its parent, and spanned by its children. You can think of values of ResTime as paths into that tree, and the resolution is how deep into the tree the path goes.

At maximum resolution, this type identifies a specific second within a year. You can think of it as a “second-of-year” type, but where the bit pattern is designed to go through all the commonly-used time units (week, half-hour, etc). Lower-resolution variants are the same type, but with some number of lower bits unavailable. In other words, the resolution is simply the number of available bits.

How it’s encoded

We indicate the resolution with a unary encoding in the lower bits. Starting from the LSB, there are some number of zeroes, followed by a one. The number of zeroes gives you the resolution. After the one, all bits represent actual time data.

This is a nice encoding, because (A) storing the resolution only costs a single bit, and (B) the positions of the time-data bits always have the same meaning, regardless of resolution (eg. bit 18, if it exists, always tells you whether it’s morning or afternoon).

A bonus: since there’s always a one-bit somewhere, the “all-zeroes” bit pattern is invalid, and can be used to represent the None case of Option<ResTime>.

Implementations

impl ResTime

pub fn resolution(self) -> Resolution

pub fn reduce_to(&mut self, res: Resolution)

Has no effect if res is higher than the current resolution

pub fn with_res(self, res: Resolution) -> Option<Self>

pub fn coarse_cmp(self, other: ResTime) -> Ordering

Compare two values by first coarsening them to the lower of their two resolutions. This gives results consistent with partial_cmp(), but not eq(). This function will return Ordering::Eq when one value is inside the other, whereas eq() would return false.

impl ResTime

pub const WHOLE_DAY: Self

pub const AM: Self

assert_eq!(ResTime::AM, ResTime::new().with_am_pm(AmPm::AM));

pub const PM: Self

assert_eq!(ResTime::PM, ResTime::new().with_am_pm(AmPm::PM));

pub fn new() -> Self

pub fn from_hour(h: u8) -> Self

impl ResTime

pub fn try_with_am_pm(self, x: AmPm) -> Option<Self>

pub fn try_with_time_of_day(self, x: TimeOfDay) -> Option<Self>

pub fn try_with_hour(self, x: u8) -> Option<Self>

pub fn try_with_minute(self, x: u8) -> Option<Self>

pub fn try_with_second(self, x: u8) -> Option<Self>

pub fn try_with_millis(self, x: u16) -> Option<Self>

impl ResTime

pub fn with_am_pm(self, x: AmPm) -> Self

pub fn with_time_of_day(self, x: TimeOfDay) -> Self

pub fn with_hour(self, x: u8) -> Self

0-23

pub fn with_minute(self, x: u8) -> Self

0-59

pub fn with_second(self, x: u8) -> Self

0-59

pub fn with_millis(self, x: u16) -> Self

0-999

pub fn set_millis(&mut self, x: u16)

0-999

pub fn set_second(&mut self, x: u8)

0-59

pub fn set_minute(&mut self, x: u8)

0-59

pub fn set_hour(&mut self, x: u8)

0-23

pub fn set_time_of_day(&mut self, x: TimeOfDay)

pub fn set_am_pm(&mut self, x: AmPm)

impl ResTime

pub fn millis(self) -> u16

0-999

pub fn second(self) -> u8

0-59

pub fn minute(self) -> u8

0-59

pub fn hour(self) -> u8

0-23

pub fn time_of_day(self) -> Option<TimeOfDay>

pub fn am_pm(self) -> Option<AmPm>

Trait Implementations

impl Clone for ResTime

fn clone(&self) -> ResTime

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ResTime

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

Formats the value using the given formatter.

impl Default for ResTime

fn default() -> Self

Returns the “default value” for a type.

impl Display for ResTime

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

Formats the value using the given formatter.

impl PartialEq for ResTime

fn eq(&self, other: &ResTime) -> 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 ResTime

fn partial_cmp(&self, other: &Self) -> 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 ResTime

impl Eq for ResTime

impl StructuralPartialEq for ResTime