Struct Time

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

A time with a resolution

Start with Time::new(), which is a timestamp at the lowest resolution possible, and covers the whole day. Increase the resolution using the Time::with_* methods. Reducude the resolution using Time::reduce_to.

Consider these two times:

let t1 = Time::new().with_hour(15).with_minute(27).with_second(17);
assert_eq!(t1.to_string(), "15:27:17");

let t2 = t1.with_millis(0);
assert_eq!(t2.to_string(), "15:27:17.000");

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 compactor::Time! 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 Times at different resolutions will never compare equal, even if one contains the other.

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

A day-spanning tree of time intervals

Including a resolution means each Time 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 Time form a tree, where each node is contained by its parent, and spanned by its children. You can think of values of Time 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<Time>.

Implementations

impl Time

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: Time) -> 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 Time

pub fn new() -> Self

Covers the whole day

impl Time

pub const WHOLE_DAY: Self

pub const AM: Self

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

pub const PM: Self

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

pub const NIGHT: Self

assert_eq!(Time::NIGHT, Time::new().with_time_of_day(SixHour::Night));

pub const MORNING: Self

assert_eq!(Time::MORNING, Time::new().with_time_of_day(SixHour::Morning));

pub const AFTERNOON: Self

assert_eq!(Time::AFTERNOON, Time::new().with_time_of_day(SixHour::Afternoon));

pub const EVENING: Self

assert_eq!(Time::EVENING, Time::new().with_time_of_day(SixHour::Evening));

pub fn from_hour(h: u8) -> Self

impl Time

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

pub fn try_with_time_of_day(self, x: SixHour) -> 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 Time

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

pub fn with_time_of_day(self, x: SixHour) -> 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: SixHour)

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

impl Time

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<SixHour>

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

Trait Implementations

impl Clone for Time

fn clone(&self) -> Time

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Time

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

Formats the value using the given formatter.

impl Default for Time

fn default() -> Self

Returns the “default value” for a type.

impl Display for Time

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

Formats the value using the given formatter.

impl PartialEq for Time

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

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 Time

impl Eq for Time

impl StructuralPartialEq for Time