Struct Time

#[repr(C)]
pub struct Time { /* private fields */ }

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 MIDNIGHT: Self = _;

A Time that is exactly midnight. This is the smallest possible value for a Time.

# use time::Time;
# use time_macros::time;
assert_eq!(Time::MIDNIGHT, time!(0:00));

const MAX: Self = _;

A Time that is one nanosecond before midnight. This is the largest possible value for a Time.

# use time::Time;
# use time_macros::time;
assert_eq!(Time::MAX, time!(23:59:59.999_999_999));

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) -> (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) -> (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) -> (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) -> (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) -> 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) -> 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) -> 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) -> 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) -> 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) -> 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, other: Self) -> SignedDuration

Determine the SignedDuration 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, other: Self) -> SignedDuration

Determine the SignedDuration 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, 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

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

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

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

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

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, 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
);

Trait Implementations

impl Add<Duration> for Time

type Output = Time;
fn add(self, duration: StdDuration) -> Self::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 Add<SignedDuration> for Time

type Output = Time;
fn add(self, duration: SignedDuration) -> Self::Output

Add the sub-day time of the SignedDuration 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 AddAssign<Duration> for Time

fn add_assign(&mut self, rhs: StdDuration)

impl AddAssign<SignedDuration> for Time

fn add_assign(&mut self, rhs: SignedDuration)

impl Clone for Time

fn clone(&self) -> Self

impl Copy for Time

impl Debug for Time

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

impl Display for Time

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

impl Eq for Time

impl Hash for Time

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

impl Ord for Time

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

impl PartialEq for Time

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

impl PartialOrd for Time

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

impl SmartDisplay for Time

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

impl Sub for Time

type Output = SignedDuration;
fn sub(self, rhs: Self) -> Self::Output

Subtract two Times, returning the SignedDuration 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<Duration> for Time

type Output = Time;
fn sub(self, duration: StdDuration) -> Self::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<SignedDuration> for Time

type Output = Time;
fn sub(self, duration: SignedDuration) -> Self::Output

Subtract the sub-day time of the SignedDuration 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<Duration> for Time

fn sub_assign(&mut self, rhs: StdDuration)

impl SubAssign<SignedDuration> for Time

fn sub_assign(&mut self, rhs: SignedDuration)

Auto Trait Implementations

impl Freeze for Time

impl RefUnwindSafe for Time

impl Send for Time

impl Sync for Time

impl Unpin for Time

impl UnsafeUnpin for Time

impl UnwindSafe for Time

Blanket Implementations

impl<T> Any for Time where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Time where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Time where T: ?Sized,

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

impl<T> CloneToUninit for Time where T: Clone,

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

impl<T> From<T> for Time

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for Time where T: Clone,

type Owned = T;
fn to_owned(&self) -> T
fn clone_into(&self, target: &mut T)

impl<T> ToString for Time where T: Display + ?Sized,

fn to_string(&self) -> String

impl<T, U> Into<U> for Time where U: From<T>,

fn into(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<U> for Time where U: Into<T>,

type Error = never;
fn try_from(value: U) -> Result<T, never>

impl<T, U> TryInto<U> for Time where U: TryFrom<T>,

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