Struct timemachine::Time

pub struct Time(pub u8, pub u8, pub u8);

A time of day as an (hour, minute, second) offset from midnight

Basic Usage

Aside from the noon and midnight functions, the primary way to make a Time object is with the new_h(m(s)?)? functions.

use timemachine::Time;

let eleven_am = Time::new_h(11);
let one_thirty_pm = Time::new_hm(13, 30);
let five_seconds_to_noon = Time::new_hms(11, 59, 55);
// Note that the above functions are shorthands for the below tuple constructions
assert_eq!(eleven_am, Time(11, 0, 0));
assert_eq!(one_thirty_pm, Time(13, 30, 0));
assert_eq!(five_seconds_to_noon, Time(11, 59, 55));

assert_eq!(format!("{:+}", eleven_am), String::from("11:00 AM"));
assert_eq!(format!("{:+}", one_thirty_pm), String::from("01:30 PM"));
assert_eq!(format!("{:+}", five_seconds_to_noon), String::from("11:59:55 AM"));

Conversion to and from base units

Time objects are nice, but it’s helpful to be able to convert them into simpler units, such as u16 minutes (as_minutes) and u32 seconds (as_seconds) past midnight. You can also convert them back with from_minutes and from_seconds.

For more information see the relevant impl.

format!ing

Time objects implement various features found in std::fmt and can be printed prettily.

For more information see impl Display.

Implementations

impl Time

pub fn midnight() -> Self

Returns a Time representing midnight

use timemachine::Time;

let midnight = Time::midnight();
assert_eq!(midnight, Time(0, 0, 0));

pub fn noon() -> Self

Returns a Time representing noon

use timemachine::Time;

let noon = Time::noon();
assert_eq!(noon, Time(12, 0, 0));

pub fn new_h(hour: u8) -> Self

Returns a time at the given hour.

use timemachine::Time;

let noon = Time::new_h(12);
assert_eq!(noon, Time(12, 0, 0));

pub fn new_hm(hour: u8, minute: u8) -> Self

Returns a time at the given hour and minute

use timemachine::Time;

let threethirty = Time::new_hm(3, 30);
assert_eq!(threethirty, Time(3, 30, 0));

pub fn new_hms(hour: u8, minute: u8, second: u8) -> Self

Returns a time at the given hour, minute, and second

use timemachine::Time;

let twofiftyandthree = Time::new_hms(2, 50, 3);
assert_eq!(twofiftyandthree, Time(2, 50, 3));

pub fn secs_until(&self, future: &Self) -> u32

Finds the number of seconds from &self until &other.
This is baaaasically subtraction mod 24*60*60, but the function name makes it clear which operand is which.

use timemachine::Time;

let midnight = Time::midnight();
let two_past = Time::from_seconds(2);
let two_til = Time::from_seconds(-2);
// From 00:00:00 until 00:00:02 = 2 seconds
assert_eq!(midnight.secs_until(&two_past), 2);
// From 23:59:58 until 00:00:00 = 2 seconds
assert_eq!(two_til.secs_until(&midnight), 2);
// From 23:59:58 until 00:00:02 = 4 seconds
assert_eq!(two_til.secs_until(&two_past), 4);
// From 00:00:02 until 23:59:58 = 4 less than 86400 seconds
assert_eq!(two_past.secs_until(&two_til), 86400 - 4);

impl Time

Base unit conversion

Time objects are nice, but it’s also helpful to convert them into base units relative to midnight: minutes past midnight with as_minutes and seconds past midnight with as_seconds.

use timemachine::Time;

let one_am = Time::new_h(1);
let one_oh_one = Time::new_hm(1, 1);
let one_oh_one_oh_one = Time::new_hms(1, 1, 1);

assert_eq!(one_am.as_minutes(), 60);
assert_eq!(one_am.as_seconds(), 3600);

assert_eq!(one_oh_one.as_minutes(), 60 + 1);
assert_eq!(one_oh_one.as_seconds(), 3600 + 60);

assert_eq!(one_oh_one_oh_one.as_minutes(), 60 + 1); // as_minutes() truncates seconds
assert_eq!(one_oh_one_oh_one.as_seconds(), 3600 + 60 + 1);

You can also convert back with from_minutes and from_seconds. These functions can take negative values, which represent an offset before midnight.

use timemachine::Time;

// 01:00 AM example
let one_am = Time::new_hms(1, 0, 0);
let from_mins = Time::from_minutes(60);
let from_secs = Time::from_seconds(3600);
assert_eq!(one_am, from_mins);
assert_eq!(one_am, from_secs);
assert_eq!(from_mins, from_secs);

// 10:30 PM example
let ten_thirty_pm = Time::new_hms(22, 30, 0);
let from_mins = Time::from_minutes(1350);
let from_neg_mins = Time::from_minutes(-90);
assert_eq!(ten_thirty_pm, from_mins);
assert_eq!(ten_thirty_pm, from_neg_mins);
assert_eq!(from_mins, from_neg_mins);

// 11:59:57 PM example
let three_seconds_to_midnight = Time::new_hms(23, 59, 57);
let from_secs = Time::from_seconds(-3);
assert_eq!(three_seconds_to_midnight, from_secs);

pub fn as_minutes(&self) -> u16

Returns a u16 representing minutes past midnight

Inverse of from_minutes

use timemachine::Time;

let onethirty = Time::new_hm(1, 30);
assert_eq!(onethirty.as_minutes(), 90);

Note that seconds are truncated!

use timemachine::Time;

let almost0001 = Time::new_hms(0, 0, 59);
assert_eq!(almost0001.as_minutes(), 0);

pub fn from_minutes(minutes: i16) -> Self

Returns a time object for a given minute offset past midnight. Negative values are offset before midnight.

Inverse of as_minutes

use timemachine::Time;
let one_past = Time::from_minutes(1);
let one_before = Time::from_minutes(-1);
assert_eq!(one_past, Time(0, 1, 0));
assert_eq!(one_before, Time(23, 59, 0));

Inverse of as_minutes

pub fn as_seconds(&self) -> u32

Returns a u32 representing seconds past midnight

Inverse of from_seconds

use timemachine::Time;

let twominutesfourty = Time::new_hms(0, 2, 40);
assert_eq!(twominutesfourty.as_seconds(), 160);

pub fn from_seconds(seconds: i32) -> Self

Returns a time object for a given second offset past midnight. Negative values are offset before midnight.

Inverse of as_seconds

use timemachine::Time;

let one_past = Time::from_seconds(1);
let one_before = Time::from_seconds(-1);
assert_eq!(one_past, Time(0, 0, 1));
assert_eq!(one_before, Time(23, 59, 59));

Inverse of as_seconds

Trait Implementations

impl Clone for Time

fn clone(&self) -> Time

Returns a copy 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 Display for Time

Time objects implement various features found in std::fmt and will be printed prettily when Displayed.

• Basic Display (24 Hour)

  let one_ten_pm = Time::new_hm(13, 10);
  let two_and_five = Time::new_hms(2, 0, 5);
  assert_eq!(
      format!("{}", one_ten_pm),
      "13:10".to_string()
  );
  assert_eq!(
      format!("{}", two_and_five),
      "02:00:05".to_string()
  );

• Signed Display (12 Hour)

  assert_eq!(
      format!("{:+}", one_ten_pm),
      "01:10 PM".to_string()
  );
  assert_eq!(
      format!("{:+}", two_and_five),
      "02:00:05 AM".to_string()
  );

• Explicit Precision

  assert_eq!(format!("{:.1}", one_ten_pm), "13".to_string());
  assert_eq!(format!("{:.2}", one_ten_pm), "13:10".to_string());
  assert_eq!(format!("{:.3}", one_ten_pm), "13:10:00".to_string());
  assert_eq!(format!("{:.1}", two_and_five), "02".to_string());
  assert_eq!(format!("{:.2}", two_and_five), "02:00".to_string());
  assert_eq!(format!("{:.3}", two_and_five), "02:00:05".to_string());

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

Formats the value using the given formatter.

impl Hash for Time

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, 

Feeds a slice of this type into the given Hasher.

impl Ord for Time

Ordering is relative to midnight, it’s just self.as_seconds().cmp(&other.as_seconds())

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

This method returns an Ordering between self and other.

#[must_use]

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

Compares and returns the maximum of two values.

#[must_use]

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

Compares and returns the minimum of two values.

#[must_use]

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

Restrict a value to a certain interval.

impl PartialEq<Time> for Time

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl PartialOrd<Time> for Time

Ordering is relative to midnight, it’s just self.as_seconds().cmp(&other.as_seconds())

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

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

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

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

impl Eq for Time

impl StructuralEq for Time

impl StructuralPartialEq for Time