952 lines
32 KiB
Rust
952 lines
32 KiB
Rust
//! The [`Time`] struct and its associated `impl`s.
|
|
|
|
#[cfg(feature = "formatting")]
|
|
use alloc::string::String;
|
|
use core::fmt;
|
|
use core::ops::{Add, Sub};
|
|
use core::time::Duration as StdDuration;
|
|
#[cfg(feature = "formatting")]
|
|
use std::io;
|
|
|
|
use deranged::{RangedU32, RangedU8};
|
|
use num_conv::prelude::*;
|
|
use powerfmt::ext::FormatterExt;
|
|
use powerfmt::smart_display::{self, FormatterOptions, Metadata, SmartDisplay};
|
|
|
|
use crate::convert::*;
|
|
#[cfg(feature = "formatting")]
|
|
use crate::formatting::Formattable;
|
|
use crate::internal_macros::{cascade, ensure_ranged, impl_add_assign, impl_sub_assign};
|
|
#[cfg(feature = "parsing")]
|
|
use crate::parsing::Parsable;
|
|
use crate::util::DateAdjustment;
|
|
use crate::{error, Duration};
|
|
|
|
/// By explicitly inserting this enum where padding is expected, the compiler is able to better
|
|
/// perform niche value optimization.
|
|
#[repr(u8)]
|
|
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
|
|
pub(crate) enum Padding {
|
|
#[allow(clippy::missing_docs_in_private_items)]
|
|
Optimize,
|
|
}
|
|
|
|
/// The type of the `hour` field of `Time`.
|
|
type Hours = RangedU8<0, { Hour::per(Day) - 1 }>;
|
|
/// The type of the `minute` field of `Time`.
|
|
type Minutes = RangedU8<0, { Minute::per(Hour) - 1 }>;
|
|
/// The type of the `second` field of `Time`.
|
|
type Seconds = RangedU8<0, { Second::per(Minute) - 1 }>;
|
|
/// The type of the `nanosecond` field of `Time`.
|
|
type Nanoseconds = RangedU32<0, { Nanosecond::per(Second) - 1 }>;
|
|
|
|
/// 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 `Time`s, they are assumed to be in the same calendar date.
|
|
#[derive(Clone, Copy, Eq)]
|
|
#[repr(C)]
|
|
pub struct Time {
|
|
// The order of this struct's fields matter!
|
|
// Do not change them.
|
|
|
|
// Little endian version
|
|
#[cfg(target_endian = "little")]
|
|
#[allow(clippy::missing_docs_in_private_items)]
|
|
nanosecond: Nanoseconds,
|
|
#[cfg(target_endian = "little")]
|
|
#[allow(clippy::missing_docs_in_private_items)]
|
|
second: Seconds,
|
|
#[cfg(target_endian = "little")]
|
|
#[allow(clippy::missing_docs_in_private_items)]
|
|
minute: Minutes,
|
|
#[cfg(target_endian = "little")]
|
|
#[allow(clippy::missing_docs_in_private_items)]
|
|
hour: Hours,
|
|
#[cfg(target_endian = "little")]
|
|
#[allow(clippy::missing_docs_in_private_items)]
|
|
padding: Padding,
|
|
|
|
// Big endian version
|
|
#[cfg(target_endian = "big")]
|
|
#[allow(clippy::missing_docs_in_private_items)]
|
|
padding: Padding,
|
|
#[cfg(target_endian = "big")]
|
|
#[allow(clippy::missing_docs_in_private_items)]
|
|
hour: Hours,
|
|
#[cfg(target_endian = "big")]
|
|
#[allow(clippy::missing_docs_in_private_items)]
|
|
minute: Minutes,
|
|
#[cfg(target_endian = "big")]
|
|
#[allow(clippy::missing_docs_in_private_items)]
|
|
second: Seconds,
|
|
#[cfg(target_endian = "big")]
|
|
#[allow(clippy::missing_docs_in_private_items)]
|
|
nanosecond: Nanoseconds,
|
|
}
|
|
|
|
impl core::hash::Hash for Time {
|
|
fn hash<H: core::hash::Hasher>(&self, state: &mut H) {
|
|
self.as_u64().hash(state)
|
|
}
|
|
}
|
|
|
|
impl PartialEq for Time {
|
|
fn eq(&self, other: &Self) -> bool {
|
|
self.as_u64().eq(&other.as_u64())
|
|
}
|
|
}
|
|
|
|
impl PartialOrd for Time {
|
|
fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
|
|
Some(self.cmp(other))
|
|
}
|
|
}
|
|
|
|
impl Ord for Time {
|
|
fn cmp(&self, other: &Self) -> core::cmp::Ordering {
|
|
self.as_u64().cmp(&other.as_u64())
|
|
}
|
|
}
|
|
|
|
impl Time {
|
|
/// Provides an u64 based representation **of the correct endianness**
|
|
///
|
|
/// This representation can be used to do comparisons equality testing or hashing.
|
|
const fn as_u64(self) -> u64 {
|
|
let nano_bytes = self.nanosecond.get().to_ne_bytes();
|
|
|
|
#[cfg(target_endian = "big")]
|
|
return u64::from_be_bytes([
|
|
self.padding as u8,
|
|
self.hour.get(),
|
|
self.minute.get(),
|
|
self.second.get(),
|
|
nano_bytes[0],
|
|
nano_bytes[1],
|
|
nano_bytes[2],
|
|
nano_bytes[3],
|
|
]);
|
|
|
|
#[cfg(target_endian = "little")]
|
|
return u64::from_le_bytes([
|
|
nano_bytes[0],
|
|
nano_bytes[1],
|
|
nano_bytes[2],
|
|
nano_bytes[3],
|
|
self.second.get(),
|
|
self.minute.get(),
|
|
self.hour.get(),
|
|
self.padding as u8,
|
|
]);
|
|
}
|
|
|
|
/// Create a `Time` that is exactly midnight.
|
|
///
|
|
/// ```rust
|
|
/// # use time::Time;
|
|
/// # use time_macros::time;
|
|
/// assert_eq!(Time::MIDNIGHT, time!(0:00));
|
|
/// ```
|
|
pub const MIDNIGHT: Self = Self::MIN;
|
|
|
|
/// The smallest value that can be represented by `Time`.
|
|
///
|
|
/// `00:00:00.0`
|
|
pub(crate) const MIN: Self =
|
|
Self::from_hms_nanos_ranged(Hours::MIN, Minutes::MIN, Seconds::MIN, Nanoseconds::MIN);
|
|
|
|
/// The largest value that can be represented by `Time`.
|
|
///
|
|
/// `23:59:59.999_999_999`
|
|
pub(crate) const MAX: Self =
|
|
Self::from_hms_nanos_ranged(Hours::MAX, Minutes::MAX, Seconds::MAX, Nanoseconds::MAX);
|
|
|
|
// region: constructors
|
|
/// Create a `Time` from its components.
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// - `hours` must be in the range `0..=23`.
|
|
/// - `minutes` must be in the range `0..=59`.
|
|
/// - `seconds` must be in the range `0..=59`.
|
|
/// - `nanoseconds` must be in the range `0..=999_999_999`.
|
|
#[doc(hidden)]
|
|
pub const unsafe fn __from_hms_nanos_unchecked(
|
|
hour: u8,
|
|
minute: u8,
|
|
second: u8,
|
|
nanosecond: u32,
|
|
) -> Self {
|
|
// Safety: The caller must uphold the safety invariants.
|
|
unsafe {
|
|
Self::from_hms_nanos_ranged(
|
|
Hours::new_unchecked(hour),
|
|
Minutes::new_unchecked(minute),
|
|
Seconds::new_unchecked(second),
|
|
Nanoseconds::new_unchecked(nanosecond),
|
|
)
|
|
}
|
|
}
|
|
|
|
/// Attempt to create a `Time` from the hour, minute, and second.
|
|
///
|
|
/// ```rust
|
|
/// # use time::Time;
|
|
/// assert!(Time::from_hms(1, 2, 3).is_ok());
|
|
/// ```
|
|
///
|
|
/// ```rust
|
|
/// # 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.
|
|
/// ```
|
|
pub const fn from_hms(hour: u8, minute: u8, second: u8) -> Result<Self, error::ComponentRange> {
|
|
Ok(Self::from_hms_nanos_ranged(
|
|
ensure_ranged!(Hours: hour),
|
|
ensure_ranged!(Minutes: minute),
|
|
ensure_ranged!(Seconds: second),
|
|
Nanoseconds::MIN,
|
|
))
|
|
}
|
|
|
|
/// Create a `Time` from the hour, minute, second, and nanosecond.
|
|
pub(crate) const fn from_hms_nanos_ranged(
|
|
hour: Hours,
|
|
minute: Minutes,
|
|
second: Seconds,
|
|
nanosecond: Nanoseconds,
|
|
) -> Self {
|
|
Self {
|
|
hour,
|
|
minute,
|
|
second,
|
|
nanosecond,
|
|
padding: Padding::Optimize,
|
|
}
|
|
}
|
|
|
|
/// Attempt to create a `Time` from the hour, minute, second, and millisecond.
|
|
///
|
|
/// ```rust
|
|
/// # use time::Time;
|
|
/// assert!(Time::from_hms_milli(1, 2, 3, 4).is_ok());
|
|
/// ```
|
|
///
|
|
/// ```rust
|
|
/// # 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.
|
|
/// ```
|
|
pub const fn from_hms_milli(
|
|
hour: u8,
|
|
minute: u8,
|
|
second: u8,
|
|
millisecond: u16,
|
|
) -> Result<Self, error::ComponentRange> {
|
|
Ok(Self::from_hms_nanos_ranged(
|
|
ensure_ranged!(Hours: hour),
|
|
ensure_ranged!(Minutes: minute),
|
|
ensure_ranged!(Seconds: second),
|
|
ensure_ranged!(Nanoseconds: millisecond as u32 * Nanosecond::per(Millisecond)),
|
|
))
|
|
}
|
|
|
|
/// Attempt to create a `Time` from the hour, minute, second, and microsecond.
|
|
///
|
|
/// ```rust
|
|
/// # use time::Time;
|
|
/// assert!(Time::from_hms_micro(1, 2, 3, 4).is_ok());
|
|
/// ```
|
|
///
|
|
/// ```rust
|
|
/// # 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.
|
|
/// ```
|
|
pub const fn from_hms_micro(
|
|
hour: u8,
|
|
minute: u8,
|
|
second: u8,
|
|
microsecond: u32,
|
|
) -> Result<Self, error::ComponentRange> {
|
|
Ok(Self::from_hms_nanos_ranged(
|
|
ensure_ranged!(Hours: hour),
|
|
ensure_ranged!(Minutes: minute),
|
|
ensure_ranged!(Seconds: second),
|
|
ensure_ranged!(Nanoseconds: microsecond * Nanosecond::per(Microsecond) as u32),
|
|
))
|
|
}
|
|
|
|
/// Attempt to create a `Time` from the hour, minute, second, and nanosecond.
|
|
///
|
|
/// ```rust
|
|
/// # use time::Time;
|
|
/// assert!(Time::from_hms_nano(1, 2, 3, 4).is_ok());
|
|
/// ```
|
|
///
|
|
/// ```rust
|
|
/// # 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.
|
|
/// ```
|
|
pub const fn from_hms_nano(
|
|
hour: u8,
|
|
minute: u8,
|
|
second: u8,
|
|
nanosecond: u32,
|
|
) -> Result<Self, error::ComponentRange> {
|
|
Ok(Self::from_hms_nanos_ranged(
|
|
ensure_ranged!(Hours: hour),
|
|
ensure_ranged!(Minutes: minute),
|
|
ensure_ranged!(Seconds: second),
|
|
ensure_ranged!(Nanoseconds: nanosecond),
|
|
))
|
|
}
|
|
// endregion constructors
|
|
|
|
// region: getters
|
|
/// Get the clock hour, minute, and second.
|
|
///
|
|
/// ```rust
|
|
/// # 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));
|
|
/// ```
|
|
pub const fn as_hms(self) -> (u8, u8, u8) {
|
|
(self.hour.get(), self.minute.get(), self.second.get())
|
|
}
|
|
|
|
/// Get the clock hour, minute, second, and millisecond.
|
|
///
|
|
/// ```rust
|
|
/// # 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));
|
|
/// ```
|
|
pub const fn as_hms_milli(self) -> (u8, u8, u8, u16) {
|
|
(
|
|
self.hour.get(),
|
|
self.minute.get(),
|
|
self.second.get(),
|
|
(self.nanosecond.get() / Nanosecond::per(Millisecond)) as u16,
|
|
)
|
|
}
|
|
|
|
/// Get the clock hour, minute, second, and microsecond.
|
|
///
|
|
/// ```rust
|
|
/// # 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)
|
|
/// );
|
|
/// ```
|
|
pub const fn as_hms_micro(self) -> (u8, u8, u8, u32) {
|
|
(
|
|
self.hour.get(),
|
|
self.minute.get(),
|
|
self.second.get(),
|
|
self.nanosecond.get() / Nanosecond::per(Microsecond) as u32,
|
|
)
|
|
}
|
|
|
|
/// Get the clock hour, minute, second, and nanosecond.
|
|
///
|
|
/// ```rust
|
|
/// # 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)
|
|
/// );
|
|
/// ```
|
|
pub const fn as_hms_nano(self) -> (u8, u8, u8, u32) {
|
|
(
|
|
self.hour.get(),
|
|
self.minute.get(),
|
|
self.second.get(),
|
|
self.nanosecond.get(),
|
|
)
|
|
}
|
|
|
|
/// Get the clock hour, minute, second, and nanosecond.
|
|
#[cfg(feature = "quickcheck")]
|
|
pub(crate) const fn as_hms_nano_ranged(self) -> (Hours, Minutes, Seconds, Nanoseconds) {
|
|
(self.hour, self.minute, self.second, self.nanosecond)
|
|
}
|
|
|
|
/// Get the clock hour.
|
|
///
|
|
/// The returned value will always be in the range `0..24`.
|
|
///
|
|
/// ```rust
|
|
/// # use time_macros::time;
|
|
/// assert_eq!(time!(0:00:00).hour(), 0);
|
|
/// assert_eq!(time!(23:59:59).hour(), 23);
|
|
/// ```
|
|
pub const fn hour(self) -> u8 {
|
|
self.hour.get()
|
|
}
|
|
|
|
/// Get the minute within the hour.
|
|
///
|
|
/// The returned value will always be in the range `0..60`.
|
|
///
|
|
/// ```rust
|
|
/// # use time_macros::time;
|
|
/// assert_eq!(time!(0:00:00).minute(), 0);
|
|
/// assert_eq!(time!(23:59:59).minute(), 59);
|
|
/// ```
|
|
pub const fn minute(self) -> u8 {
|
|
self.minute.get()
|
|
}
|
|
|
|
/// Get the second within the minute.
|
|
///
|
|
/// The returned value will always be in the range `0..60`.
|
|
///
|
|
/// ```rust
|
|
/// # use time_macros::time;
|
|
/// assert_eq!(time!(0:00:00).second(), 0);
|
|
/// assert_eq!(time!(23:59:59).second(), 59);
|
|
/// ```
|
|
pub const fn second(self) -> u8 {
|
|
self.second.get()
|
|
}
|
|
|
|
/// Get the milliseconds within the second.
|
|
///
|
|
/// The returned value will always be in the range `0..1_000`.
|
|
///
|
|
/// ```rust
|
|
/// # use time_macros::time;
|
|
/// assert_eq!(time!(0:00).millisecond(), 0);
|
|
/// assert_eq!(time!(23:59:59.999).millisecond(), 999);
|
|
/// ```
|
|
pub const fn millisecond(self) -> u16 {
|
|
(self.nanosecond.get() / Nanosecond::per(Millisecond)) as _
|
|
}
|
|
|
|
/// Get the microseconds within the second.
|
|
///
|
|
/// The returned value will always be in the range `0..1_000_000`.
|
|
///
|
|
/// ```rust
|
|
/// # use time_macros::time;
|
|
/// assert_eq!(time!(0:00).microsecond(), 0);
|
|
/// assert_eq!(time!(23:59:59.999_999).microsecond(), 999_999);
|
|
/// ```
|
|
pub const fn microsecond(self) -> u32 {
|
|
self.nanosecond.get() / Nanosecond::per(Microsecond) as u32
|
|
}
|
|
|
|
/// Get the nanoseconds within the second.
|
|
///
|
|
/// The returned value will always be in the range `0..1_000_000_000`.
|
|
///
|
|
/// ```rust
|
|
/// # use time_macros::time;
|
|
/// assert_eq!(time!(0:00).nanosecond(), 0);
|
|
/// assert_eq!(time!(23:59:59.999_999_999).nanosecond(), 999_999_999);
|
|
/// ```
|
|
pub const fn nanosecond(self) -> u32 {
|
|
self.nanosecond.get()
|
|
}
|
|
// endregion getters
|
|
|
|
// region: arithmetic helpers
|
|
/// Add the sub-day time of the [`Duration`] to the `Time`. Wraps on overflow, returning whether
|
|
/// the date is different.
|
|
pub(crate) const fn adjusting_add(self, duration: Duration) -> (DateAdjustment, Self) {
|
|
let mut nanoseconds = self.nanosecond.get() as i32 + duration.subsec_nanoseconds();
|
|
let mut seconds =
|
|
self.second.get() as i8 + (duration.whole_seconds() % Second::per(Minute) as i64) as i8;
|
|
let mut minutes =
|
|
self.minute.get() as i8 + (duration.whole_minutes() % Minute::per(Hour) as i64) as i8;
|
|
let mut hours =
|
|
self.hour.get() as i8 + (duration.whole_hours() % Hour::per(Day) as i64) as i8;
|
|
let mut date_adjustment = DateAdjustment::None;
|
|
|
|
cascade!(nanoseconds in 0..Nanosecond::per(Second) as _ => seconds);
|
|
cascade!(seconds in 0..Second::per(Minute) as _ => minutes);
|
|
cascade!(minutes in 0..Minute::per(Hour) as _ => hours);
|
|
if hours >= Hour::per(Day) as _ {
|
|
hours -= Hour::per(Day) as i8;
|
|
date_adjustment = DateAdjustment::Next;
|
|
} else if hours < 0 {
|
|
hours += Hour::per(Day) as i8;
|
|
date_adjustment = DateAdjustment::Previous;
|
|
}
|
|
|
|
(
|
|
date_adjustment,
|
|
// Safety: The cascades above ensure the values are in range.
|
|
unsafe {
|
|
Self::__from_hms_nanos_unchecked(
|
|
hours as _,
|
|
minutes as _,
|
|
seconds as _,
|
|
nanoseconds as _,
|
|
)
|
|
},
|
|
)
|
|
}
|
|
|
|
/// Subtract the sub-day time of the [`Duration`] to the `Time`. Wraps on overflow, returning
|
|
/// whether the date is different.
|
|
pub(crate) const fn adjusting_sub(self, duration: Duration) -> (DateAdjustment, Self) {
|
|
let mut nanoseconds = self.nanosecond.get() as i32 - duration.subsec_nanoseconds();
|
|
let mut seconds =
|
|
self.second.get() as i8 - (duration.whole_seconds() % Second::per(Minute) as i64) as i8;
|
|
let mut minutes =
|
|
self.minute.get() as i8 - (duration.whole_minutes() % Minute::per(Hour) as i64) as i8;
|
|
let mut hours =
|
|
self.hour.get() as i8 - (duration.whole_hours() % Hour::per(Day) as i64) as i8;
|
|
let mut date_adjustment = DateAdjustment::None;
|
|
|
|
cascade!(nanoseconds in 0..Nanosecond::per(Second) as _ => seconds);
|
|
cascade!(seconds in 0..Second::per(Minute) as _ => minutes);
|
|
cascade!(minutes in 0..Minute::per(Hour) as _ => hours);
|
|
if hours >= Hour::per(Day) as _ {
|
|
hours -= Hour::per(Day) as i8;
|
|
date_adjustment = DateAdjustment::Next;
|
|
} else if hours < 0 {
|
|
hours += Hour::per(Day) as i8;
|
|
date_adjustment = DateAdjustment::Previous;
|
|
}
|
|
|
|
(
|
|
date_adjustment,
|
|
// Safety: The cascades above ensure the values are in range.
|
|
unsafe {
|
|
Self::__from_hms_nanos_unchecked(
|
|
hours as _,
|
|
minutes as _,
|
|
seconds as _,
|
|
nanoseconds as _,
|
|
)
|
|
},
|
|
)
|
|
}
|
|
|
|
/// Add the sub-day time of the [`std::time::Duration`] to the `Time`. Wraps on overflow,
|
|
/// returning whether the date is the previous date as the first element of the tuple.
|
|
pub(crate) const fn adjusting_add_std(self, duration: StdDuration) -> (bool, Self) {
|
|
let mut nanosecond = self.nanosecond.get() + duration.subsec_nanos();
|
|
let mut second =
|
|
self.second.get() + (duration.as_secs() % Second::per(Minute) as u64) as u8;
|
|
let mut minute = self.minute.get()
|
|
+ ((duration.as_secs() / Second::per(Minute) as u64) % Minute::per(Hour) as u64) as u8;
|
|
let mut hour = self.hour.get()
|
|
+ ((duration.as_secs() / Second::per(Hour) as u64) % Hour::per(Day) as u64) as u8;
|
|
let mut is_next_day = false;
|
|
|
|
cascade!(nanosecond in 0..Nanosecond::per(Second) => second);
|
|
cascade!(second in 0..Second::per(Minute) => minute);
|
|
cascade!(minute in 0..Minute::per(Hour) => hour);
|
|
if hour >= Hour::per(Day) {
|
|
hour -= Hour::per(Day);
|
|
is_next_day = true;
|
|
}
|
|
|
|
(
|
|
is_next_day,
|
|
// Safety: The cascades above ensure the values are in range.
|
|
unsafe { Self::__from_hms_nanos_unchecked(hour, minute, second, nanosecond) },
|
|
)
|
|
}
|
|
|
|
/// Subtract the sub-day time of the [`std::time::Duration`] to the `Time`. Wraps on overflow,
|
|
/// returning whether the date is the previous date as the first element of the tuple.
|
|
pub(crate) const fn adjusting_sub_std(self, duration: StdDuration) -> (bool, Self) {
|
|
let mut nanosecond = self.nanosecond.get() as i32 - duration.subsec_nanos() as i32;
|
|
let mut second =
|
|
self.second.get() as i8 - (duration.as_secs() % Second::per(Minute) as u64) as i8;
|
|
let mut minute = self.minute.get() as i8
|
|
- ((duration.as_secs() / Second::per(Minute) as u64) % Minute::per(Hour) as u64) as i8;
|
|
let mut hour = self.hour.get() as i8
|
|
- ((duration.as_secs() / Second::per(Hour) as u64) % Hour::per(Day) as u64) as i8;
|
|
let mut is_previous_day = false;
|
|
|
|
cascade!(nanosecond in 0..Nanosecond::per(Second) as _ => second);
|
|
cascade!(second in 0..Second::per(Minute) as _ => minute);
|
|
cascade!(minute in 0..Minute::per(Hour) as _ => hour);
|
|
if hour < 0 {
|
|
hour += Hour::per(Day) as i8;
|
|
is_previous_day = true;
|
|
}
|
|
|
|
(
|
|
is_previous_day,
|
|
// Safety: The cascades above ensure the values are in range.
|
|
unsafe {
|
|
Self::__from_hms_nanos_unchecked(
|
|
hour as _,
|
|
minute as _,
|
|
second as _,
|
|
nanosecond as _,
|
|
)
|
|
},
|
|
)
|
|
}
|
|
// endregion arithmetic helpers
|
|
|
|
// region: replacement
|
|
/// Replace the clock hour.
|
|
///
|
|
/// ```rust
|
|
/// # 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
|
|
/// ```
|
|
#[must_use = "This method does not mutate the original `Time`."]
|
|
pub const fn replace_hour(mut self, hour: u8) -> Result<Self, error::ComponentRange> {
|
|
self.hour = ensure_ranged!(Hours: hour);
|
|
Ok(self)
|
|
}
|
|
|
|
/// Replace the minutes within the hour.
|
|
///
|
|
/// ```rust
|
|
/// # 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
|
|
/// ```
|
|
#[must_use = "This method does not mutate the original `Time`."]
|
|
pub const fn replace_minute(mut self, minute: u8) -> Result<Self, error::ComponentRange> {
|
|
self.minute = ensure_ranged!(Minutes: minute);
|
|
Ok(self)
|
|
}
|
|
|
|
/// Replace the seconds within the minute.
|
|
///
|
|
/// ```rust
|
|
/// # 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
|
|
/// ```
|
|
#[must_use = "This method does not mutate the original `Time`."]
|
|
pub const fn replace_second(mut self, second: u8) -> Result<Self, error::ComponentRange> {
|
|
self.second = ensure_ranged!(Seconds: second);
|
|
Ok(self)
|
|
}
|
|
|
|
/// Replace the milliseconds within the second.
|
|
///
|
|
/// ```rust
|
|
/// # 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
|
|
/// ```
|
|
#[must_use = "This method does not mutate the original `Time`."]
|
|
pub const fn replace_millisecond(
|
|
mut self,
|
|
millisecond: u16,
|
|
) -> Result<Self, error::ComponentRange> {
|
|
self.nanosecond =
|
|
ensure_ranged!(Nanoseconds: millisecond as u32 * Nanosecond::per(Millisecond));
|
|
Ok(self)
|
|
}
|
|
|
|
/// Replace the microseconds within the second.
|
|
///
|
|
/// ```rust
|
|
/// # 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
|
|
/// ```
|
|
#[must_use = "This method does not mutate the original `Time`."]
|
|
pub const fn replace_microsecond(
|
|
mut self,
|
|
microsecond: u32,
|
|
) -> Result<Self, error::ComponentRange> {
|
|
self.nanosecond =
|
|
ensure_ranged!(Nanoseconds: microsecond * Nanosecond::per(Microsecond) as u32);
|
|
Ok(self)
|
|
}
|
|
|
|
/// Replace the nanoseconds within the second.
|
|
///
|
|
/// ```rust
|
|
/// # 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
|
|
/// ```
|
|
#[must_use = "This method does not mutate the original `Time`."]
|
|
pub const fn replace_nanosecond(
|
|
mut self,
|
|
nanosecond: u32,
|
|
) -> Result<Self, error::ComponentRange> {
|
|
self.nanosecond = ensure_ranged!(Nanoseconds: nanosecond);
|
|
Ok(self)
|
|
}
|
|
// endregion replacement
|
|
}
|
|
|
|
// region: formatting & parsing
|
|
#[cfg(feature = "formatting")]
|
|
impl Time {
|
|
/// Format the `Time` using the provided [format description](crate::format_description).
|
|
pub fn format_into(
|
|
self,
|
|
output: &mut impl io::Write,
|
|
format: &(impl Formattable + ?Sized),
|
|
) -> Result<usize, error::Format> {
|
|
format.format_into(output, None, Some(self), None)
|
|
}
|
|
|
|
/// Format the `Time` using the provided [format description](crate::format_description).
|
|
///
|
|
/// ```rust
|
|
/// # use time::format_description;
|
|
/// # use time_macros::time;
|
|
/// let format = format_description::parse("[hour]:[minute]:[second]")?;
|
|
/// assert_eq!(time!(12:00).format(&format)?, "12:00:00");
|
|
/// # Ok::<_, time::Error>(())
|
|
/// ```
|
|
pub fn format(self, format: &(impl Formattable + ?Sized)) -> Result<String, error::Format> {
|
|
format.format(None, Some(self), None)
|
|
}
|
|
}
|
|
|
|
#[cfg(feature = "parsing")]
|
|
impl Time {
|
|
/// Parse a `Time` from the input using the provided [format
|
|
/// description](crate::format_description).
|
|
///
|
|
/// ```rust
|
|
/// # use time::Time;
|
|
/// # use time_macros::{time, format_description};
|
|
/// let format = format_description!("[hour]:[minute]:[second]");
|
|
/// assert_eq!(Time::parse("12:00:00", &format)?, time!(12:00));
|
|
/// # Ok::<_, time::Error>(())
|
|
/// ```
|
|
pub fn parse(
|
|
input: &str,
|
|
description: &(impl Parsable + ?Sized),
|
|
) -> Result<Self, error::Parse> {
|
|
description.parse_time(input.as_bytes())
|
|
}
|
|
}
|
|
|
|
mod private {
|
|
#[non_exhaustive]
|
|
#[derive(Debug, Clone, Copy)]
|
|
pub struct TimeMetadata {
|
|
/// How many characters wide the formatted subsecond is.
|
|
pub(super) subsecond_width: u8,
|
|
/// The value to use when formatting the subsecond. Leading zeroes will be added as
|
|
/// necessary.
|
|
pub(super) subsecond_value: u32,
|
|
}
|
|
}
|
|
use private::TimeMetadata;
|
|
|
|
impl SmartDisplay for Time {
|
|
type Metadata = TimeMetadata;
|
|
|
|
fn metadata(&self, _: FormatterOptions) -> Metadata<Self> {
|
|
let (subsecond_value, subsecond_width) = match self.nanosecond() {
|
|
nanos if nanos % 10 != 0 => (nanos, 9),
|
|
nanos if (nanos / 10) % 10 != 0 => (nanos / 10, 8),
|
|
nanos if (nanos / 100) % 10 != 0 => (nanos / 100, 7),
|
|
nanos if (nanos / 1_000) % 10 != 0 => (nanos / 1_000, 6),
|
|
nanos if (nanos / 10_000) % 10 != 0 => (nanos / 10_000, 5),
|
|
nanos if (nanos / 100_000) % 10 != 0 => (nanos / 100_000, 4),
|
|
nanos if (nanos / 1_000_000) % 10 != 0 => (nanos / 1_000_000, 3),
|
|
nanos if (nanos / 10_000_000) % 10 != 0 => (nanos / 10_000_000, 2),
|
|
nanos => (nanos / 100_000_000, 1),
|
|
};
|
|
|
|
let formatted_width = smart_display::padded_width_of!(
|
|
self.hour.get(),
|
|
":",
|
|
self.minute.get() => width(2) fill('0'),
|
|
":",
|
|
self.second.get() => width(2) fill('0'),
|
|
".",
|
|
) + subsecond_width;
|
|
|
|
Metadata::new(
|
|
formatted_width,
|
|
self,
|
|
TimeMetadata {
|
|
subsecond_width: subsecond_width.truncate(),
|
|
subsecond_value,
|
|
},
|
|
)
|
|
}
|
|
|
|
fn fmt_with_metadata(
|
|
&self,
|
|
f: &mut fmt::Formatter<'_>,
|
|
metadata: Metadata<Self>,
|
|
) -> fmt::Result {
|
|
let subsecond_width = metadata.subsecond_width.extend();
|
|
let subsecond_value = metadata.subsecond_value;
|
|
|
|
f.pad_with_width(
|
|
metadata.unpadded_width(),
|
|
format_args!(
|
|
"{}:{:02}:{:02}.{subsecond_value:0subsecond_width$}",
|
|
self.hour, self.minute, self.second
|
|
),
|
|
)
|
|
}
|
|
}
|
|
|
|
impl fmt::Display for Time {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
SmartDisplay::fmt(self, f)
|
|
}
|
|
}
|
|
|
|
impl fmt::Debug for Time {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
fmt::Display::fmt(self, f)
|
|
}
|
|
}
|
|
// endregion formatting & parsing
|
|
|
|
// region: trait impls
|
|
impl Add<Duration> for Time {
|
|
type Output = Self;
|
|
|
|
/// Add the sub-day time of the [`Duration`] to the `Time`. Wraps on overflow.
|
|
///
|
|
/// ```rust
|
|
/// # 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));
|
|
/// ```
|
|
fn add(self, duration: Duration) -> Self::Output {
|
|
self.adjusting_add(duration).1
|
|
}
|
|
}
|
|
|
|
impl Add<StdDuration> for Time {
|
|
type Output = Self;
|
|
|
|
/// Add the sub-day time of the [`std::time::Duration`] to the `Time`. Wraps on overflow.
|
|
///
|
|
/// ```rust
|
|
/// # 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));
|
|
/// ```
|
|
fn add(self, duration: StdDuration) -> Self::Output {
|
|
self.adjusting_add_std(duration).1
|
|
}
|
|
}
|
|
|
|
impl_add_assign!(Time: Duration, StdDuration);
|
|
|
|
impl Sub<Duration> for Time {
|
|
type Output = Self;
|
|
|
|
/// Subtract the sub-day time of the [`Duration`] from the `Time`. Wraps on overflow.
|
|
///
|
|
/// ```rust
|
|
/// # 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));
|
|
/// ```
|
|
fn sub(self, duration: Duration) -> Self::Output {
|
|
self.adjusting_sub(duration).1
|
|
}
|
|
}
|
|
|
|
impl Sub<StdDuration> for Time {
|
|
type Output = Self;
|
|
|
|
/// Subtract the sub-day time of the [`std::time::Duration`] from the `Time`. Wraps on overflow.
|
|
///
|
|
/// ```rust
|
|
/// # 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));
|
|
/// ```
|
|
fn sub(self, duration: StdDuration) -> Self::Output {
|
|
self.adjusting_sub_std(duration).1
|
|
}
|
|
}
|
|
|
|
impl_sub_assign!(Time: Duration, StdDuration);
|
|
|
|
impl Sub for Time {
|
|
type Output = Duration;
|
|
|
|
/// Subtract two `Time`s, returning the [`Duration`] between. This assumes both `Time`s are in
|
|
/// the same calendar day.
|
|
///
|
|
/// ```rust
|
|
/// # 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());
|
|
/// ```
|
|
fn sub(self, rhs: Self) -> Self::Output {
|
|
let hour_diff = self.hour.get().cast_signed() - rhs.hour.get().cast_signed();
|
|
let minute_diff = self.minute.get().cast_signed() - rhs.minute.get().cast_signed();
|
|
let second_diff = self.second.get().cast_signed() - rhs.second.get().cast_signed();
|
|
let nanosecond_diff =
|
|
self.nanosecond.get().cast_signed() - rhs.nanosecond.get().cast_signed();
|
|
|
|
let seconds = hour_diff.extend::<i64>() * Second::per(Hour).cast_signed().extend::<i64>()
|
|
+ minute_diff.extend::<i64>() * Second::per(Minute).cast_signed().extend::<i64>()
|
|
+ second_diff.extend::<i64>();
|
|
|
|
let (seconds, nanoseconds) = if seconds > 0 && nanosecond_diff < 0 {
|
|
(
|
|
seconds - 1,
|
|
nanosecond_diff + Nanosecond::per(Second).cast_signed(),
|
|
)
|
|
} else if seconds < 0 && nanosecond_diff > 0 {
|
|
(
|
|
seconds + 1,
|
|
nanosecond_diff - Nanosecond::per(Second).cast_signed(),
|
|
)
|
|
} else {
|
|
(seconds, nanosecond_diff)
|
|
};
|
|
|
|
// Safety: `nanoseconds` is in range due to the overflow handling.
|
|
unsafe { Duration::new_unchecked(seconds, nanoseconds) }
|
|
}
|
|
}
|
|
// endregion trait impls
|