Struct Time

struct Time { ... }

The clock time within a given date. Nanosecond precision.

All minutes are assumed to have exactly 60 seconds; no attempt is made to handle leap seconds (either positive or negative).

When comparing two Times, they are assumed to be in the same calendar date.

Implementations

impl Time

const fn from_hms(hour: u8, minute: u8, second: u8) -> Result<Self, ComponentRange>

Attempt to create a Time from the hour, minute, and second.

# use time::Time;
assert!(Time::from_hms(1, 2, 3).is_ok());

# use time::Time;
assert!(Time::from_hms(24, 0, 0).is_err()); // 24 isn't a valid hour.
assert!(Time::from_hms(0, 60, 0).is_err()); // 60 isn't a valid minute.
assert!(Time::from_hms(0, 0, 60).is_err()); // 60 isn't a valid second.

const fn from_hms_milli(hour: u8, minute: u8, second: u8, millisecond: u16) -> Result<Self, ComponentRange>

Attempt to create a Time from the hour, minute, second, and millisecond.

# use time::Time;
assert!(Time::from_hms_milli(1, 2, 3, 4).is_ok());

# use time::Time;
assert!(Time::from_hms_milli(24, 0, 0, 0).is_err()); // 24 isn't a valid hour.
assert!(Time::from_hms_milli(0, 60, 0, 0).is_err()); // 60 isn't a valid minute.
assert!(Time::from_hms_milli(0, 0, 60, 0).is_err()); // 60 isn't a valid second.
assert!(Time::from_hms_milli(0, 0, 0, 1_000).is_err()); // 1_000 isn't a valid millisecond.

const fn from_hms_micro(hour: u8, minute: u8, second: u8, microsecond: u32) -> Result<Self, ComponentRange>

Attempt to create a Time from the hour, minute, second, and microsecond.

# use time::Time;
assert!(Time::from_hms_micro(1, 2, 3, 4).is_ok());

# use time::Time;
assert!(Time::from_hms_micro(24, 0, 0, 0).is_err()); // 24 isn't a valid hour.
assert!(Time::from_hms_micro(0, 60, 0, 0).is_err()); // 60 isn't a valid minute.
assert!(Time::from_hms_micro(0, 0, 60, 0).is_err()); // 60 isn't a valid second.
assert!(Time::from_hms_micro(0, 0, 0, 1_000_000).is_err()); // 1_000_000 isn't a valid microsecond.

const fn from_hms_nano(hour: u8, minute: u8, second: u8, nanosecond: u32) -> Result<Self, ComponentRange>

Attempt to create a Time from the hour, minute, second, and nanosecond.

# use time::Time;
assert!(Time::from_hms_nano(1, 2, 3, 4).is_ok());

# use time::Time;
assert!(Time::from_hms_nano(24, 0, 0, 0).is_err()); // 24 isn't a valid hour.
assert!(Time::from_hms_nano(0, 60, 0, 0).is_err()); // 60 isn't a valid minute.
assert!(Time::from_hms_nano(0, 0, 60, 0).is_err()); // 60 isn't a valid second.
assert!(Time::from_hms_nano(0, 0, 0, 1_000_000_000).is_err()); // 1_000_000_000 isn't a valid nanosecond.

const fn as_hms(self: Self) -> (u8, u8, u8)

Get the clock hour, minute, and second.

# use time_macros::time;
assert_eq!(time!(0:00:00).as_hms(), (0, 0, 0));
assert_eq!(time!(23:59:59).as_hms(), (23, 59, 59));

const fn as_hms_milli(self: Self) -> (u8, u8, u8, u16)

Get the clock hour, minute, second, and millisecond.

# use time_macros::time;
assert_eq!(time!(0:00:00).as_hms_milli(), (0, 0, 0, 0));
assert_eq!(time!(23:59:59.999).as_hms_milli(), (23, 59, 59, 999));

const fn as_hms_micro(self: Self) -> (u8, u8, u8, u32)

Get the clock hour, minute, second, and microsecond.

# use time_macros::time;
assert_eq!(time!(0:00:00).as_hms_micro(), (0, 0, 0, 0));
assert_eq!(
    time!(23:59:59.999_999).as_hms_micro(),
    (23, 59, 59, 999_999)
);

const fn as_hms_nano(self: Self) -> (u8, u8, u8, u32)

Get the clock hour, minute, second, and nanosecond.

# use time_macros::time;
assert_eq!(time!(0:00:00).as_hms_nano(), (0, 0, 0, 0));
assert_eq!(
    time!(23:59:59.999_999_999).as_hms_nano(),
    (23, 59, 59, 999_999_999)
);

const fn hour(self: Self) -> u8

Get the clock hour.

The returned value will always be in the range 0..24.

# use time_macros::time;
assert_eq!(time!(0:00:00).hour(), 0);
assert_eq!(time!(23:59:59).hour(), 23);

const fn minute(self: Self) -> u8

Get the minute within the hour.

The returned value will always be in the range 0..60.

# use time_macros::time;
assert_eq!(time!(0:00:00).minute(), 0);
assert_eq!(time!(23:59:59).minute(), 59);

const fn second(self: Self) -> u8

Get the second within the minute.

The returned value will always be in the range 0..60.

# use time_macros::time;
assert_eq!(time!(0:00:00).second(), 0);
assert_eq!(time!(23:59:59).second(), 59);

const fn millisecond(self: Self) -> u16

Get the milliseconds within the second.

The returned value will always be in the range 0..1_000.

# use time_macros::time;
assert_eq!(time!(0:00).millisecond(), 0);
assert_eq!(time!(23:59:59.999).millisecond(), 999);

const fn microsecond(self: Self) -> u32

Get the microseconds within the second.

The returned value will always be in the range 0..1_000_000.

# use time_macros::time;
assert_eq!(time!(0:00).microsecond(), 0);
assert_eq!(time!(23:59:59.999_999).microsecond(), 999_999);

const fn nanosecond(self: Self) -> u32

Get the nanoseconds within the second.

The returned value will always be in the range 0..1_000_000_000.

# use time_macros::time;
assert_eq!(time!(0:00).nanosecond(), 0);
assert_eq!(time!(23:59:59.999_999_999).nanosecond(), 999_999_999);

const fn duration_until(self: Self, other: Self) -> Duration

Determine the Duration that, if added to self, would result in the parameter.

# use time::Time;
# use time::ext::NumericalDuration;
# use time_macros::time;
assert_eq!(time!(18:00).duration_until(Time::MIDNIGHT), 6.hours());
assert_eq!(time!(23:00).duration_until(time!(1:00)), 2.hours());

const fn duration_since(self: Self, other: Self) -> Duration

Determine the Duration that, if added to the parameter, would result in self.

# use time::Time;
# use time::ext::NumericalDuration;
# use time_macros::time;
assert_eq!(Time::MIDNIGHT.duration_since(time!(18:00)), 6.hours());
assert_eq!(time!(1:00).duration_since(time!(23:00)), 2.hours());

const fn replace_hour(self: Self, hour: u8) -> Result<Self, ComponentRange>

Replace the clock hour.

# use time_macros::time;
assert_eq!(
    time!(01:02:03.004_005_006).replace_hour(7),
    Ok(time!(07:02:03.004_005_006))
);
assert!(time!(01:02:03.004_005_006).replace_hour(24).is_err()); // 24 isn't a valid hour

const fn truncate_to_hour(self: Self) -> Self

Truncate the time to the hour, setting the minute, second, and subsecond components to zero.

# use time_macros::time;
assert_eq!(time!(01:02:03.004_005_006).truncate_to_hour(), time!(01:00));

const fn replace_minute(self: Self, minute: u8) -> Result<Self, ComponentRange>

Replace the minutes within the hour.

# use time_macros::time;
assert_eq!(
    time!(01:02:03.004_005_006).replace_minute(7),
    Ok(time!(01:07:03.004_005_006))
);
assert!(time!(01:02:03.004_005_006).replace_minute(60).is_err()); // 60 isn't a valid minute

const fn truncate_to_minute(self: Self) -> Self

Truncate the time to the minute, setting the second and subsecond components to zero.

# use time_macros::time;
assert_eq!(
    time!(01:02:03.004_005_006).truncate_to_minute(),
    time!(01:02)
);

const fn replace_second(self: Self, second: u8) -> Result<Self, ComponentRange>

Replace the seconds within the minute.

# use time_macros::time;
assert_eq!(
    time!(01:02:03.004_005_006).replace_second(7),
    Ok(time!(01:02:07.004_005_006))
);
assert!(time!(01:02:03.004_005_006).replace_second(60).is_err()); // 60 isn't a valid second

const fn truncate_to_second(self: Self) -> Self

Truncate the time to the second, setting the subsecond component to zero.

# use time_macros::time;
assert_eq!(
    time!(01:02:03.004_005_006).truncate_to_second(),
    time!(01:02:03)
);

const fn replace_millisecond(self: Self, millisecond: u16) -> Result<Self, ComponentRange>

Replace the milliseconds within the second.

# use time_macros::time;
assert_eq!(
    time!(01:02:03.004_005_006).replace_millisecond(7),
    Ok(time!(01:02:03.007))
);
assert!(
    time!(01:02:03.004_005_006)
        .replace_millisecond(1_000)
        .is_err() // 1_000 isn't a valid millisecond
);

const fn truncate_to_millisecond(self: Self) -> Self

Truncate the time to the millisecond, setting the microsecond and nanosecond components to zero.

# use time_macros::time;
assert_eq!(
    time!(01:02:03.004_005_006).truncate_to_millisecond(),
    time!(01:02:03.004)
);

const fn replace_microsecond(self: Self, microsecond: u32) -> Result<Self, ComponentRange>

Replace the microseconds within the second.

# use time_macros::time;
assert_eq!(
    time!(01:02:03.004_005_006).replace_microsecond(7_008),
    Ok(time!(01:02:03.007_008))
);
assert!(
    time!(01:02:03.004_005_006)
        .replace_microsecond(1_000_000)
        .is_err() // 1_000_000 isn't a valid microsecond
);

const fn truncate_to_microsecond(self: Self) -> Self

Truncate the time to the microsecond, setting the nanosecond component to zero.

# use time_macros::time;
assert_eq!(
    time!(01:02:03.004_005_006).truncate_to_microsecond(),
    time!(01:02:03.004_005)
);

const fn replace_nanosecond(self: Self, nanosecond: u32) -> Result<Self, ComponentRange>

Replace the nanoseconds within the second.

# use time_macros::time;
assert_eq!(
    time!(01:02:03.004_005_006).replace_nanosecond(7_008_009),
    Ok(time!(01:02:03.007_008_009))
);
assert!(
    time!(01:02:03.004_005_006)
        .replace_nanosecond(1_000_000_000)
        .is_err() // 1_000_000_000 isn't a valid nanosecond
);

impl Add for Time

fn add(self: Self, duration: Duration) -> <Self as >::Output

Add the sub-day time of the Duration to the Time. Wraps on overflow.

# use time::ext::NumericalDuration;
# use time_macros::time;
assert_eq!(time!(12:00) + 2.hours(), time!(14:00));
assert_eq!(time!(0:00:01) + (-2).seconds(), time!(23:59:59));

impl Add for Time

fn add(self: Self, duration: StdDuration) -> <Self as >::Output

Add the sub-day time of the std::time::Duration to the Time. Wraps on overflow.

# use time::ext::NumericalStdDuration;
# use time_macros::time;
assert_eq!(time!(12:00) + 2.std_hours(), time!(14:00));
assert_eq!(time!(23:59:59) + 2.std_seconds(), time!(0:00:01));

impl AddAssign for Time

fn add_assign(self: &mut Self, rhs: Duration)

impl AddAssign for Time

fn add_assign(self: &mut Self, rhs: StdDuration)

impl Clone for Time

fn clone(self: &Self) -> Time

impl Copy for Time

impl Debug for Time

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

impl Display for Time

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

impl Eq for Time

impl Freeze for Time

impl Hash for Time

fn hash<H>(self: &Self, state: &mut H)
where
    H: Hasher

impl Ord for Time

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

impl PartialEq for Time

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

impl PartialOrd for Time

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

impl RefUnwindSafe for Time

impl Send for Time

impl SmartDisplay for Time

fn metadata(self: &Self, _: FormatterOptions) -> Metadata<'_, Self>
fn fmt_with_metadata(self: &Self, f: &mut Formatter<'_>, metadata: Metadata<'_, Self>) -> Result

impl Sub for Time

fn sub(self: Self, duration: StdDuration) -> <Self as >::Output

Subtract the sub-day time of the std::time::Duration from the Time. Wraps on overflow.

# use time::ext::NumericalStdDuration;
# use time_macros::time;
assert_eq!(time!(14:00) - 2.std_hours(), time!(12:00));
assert_eq!(time!(0:00:01) - 2.std_seconds(), time!(23:59:59));

impl Sub for Time

fn sub(self: Self, rhs: Self) -> <Self as >::Output

Subtract two Times, returning the Duration between. This assumes both Times are in the same calendar day.

# use time::ext::NumericalDuration;
# use time_macros::time;
assert_eq!(time!(0:00) - time!(0:00), 0.seconds());
assert_eq!(time!(1:00) - time!(0:00), 1.hours());
assert_eq!(time!(0:00) - time!(1:00), (-1).hours());
assert_eq!(time!(0:00) - time!(23:00), (-23).hours());

impl Sub for Time

fn sub(self: Self, duration: Duration) -> <Self as >::Output

Subtract the sub-day time of the Duration from the Time. Wraps on overflow.

# use time::ext::NumericalDuration;
# use time_macros::time;
assert_eq!(time!(14:00) - 2.hours(), time!(12:00));
assert_eq!(time!(23:59:59) - (-2).seconds(), time!(0:00:01));

impl SubAssign for Time

fn sub_assign(self: &mut Self, rhs: Duration)

impl SubAssign for Time

fn sub_assign(self: &mut Self, rhs: StdDuration)

impl Sync for Time

impl Unpin for Time

impl UnsafeUnpin for Time

impl UnwindSafe for Time

impl<T> Any for Time

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Time

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

impl<T> BorrowMut for Time

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

impl<T> CloneToUninit for Time

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

impl<T> From for Time

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for Time

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

impl<T> ToString for Time

fn to_string(self: &Self) -> String

impl<T, U> Into for Time

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 Time

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

impl<T, U> TryInto for Time

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