Struct time::PrimitiveDateTime
source · pub struct PrimitiveDateTime(/* private fields */);
Expand description
Combined date and time.
Implementations§
source§impl PrimitiveDateTime
impl PrimitiveDateTime
sourcepub const MIN: Self = _
pub const MIN: Self = _
The smallest value that can be represented by PrimitiveDateTime
.
Depending on large-dates
feature flag, value of this constant may vary.
- With
large-dates
disabled it is equal to-9999-01-01 00:00:00.0
- With
large-dates
enabled it is equal to-999999-01-01 00:00:00.0
// Assuming `large-dates` feature is disabled.
assert_eq!(PrimitiveDateTime::MIN, datetime!(-9999-01-01 0:00));
Runsourcepub const MAX: Self = _
pub const MAX: Self = _
The largest value that can be represented by PrimitiveDateTime
.
Depending on large-dates
feature flag, value of this constant may vary.
- With
large-dates
disabled it is equal to9999-12-31 23:59:59.999_999_999
- With
large-dates
enabled it is equal to999999-12-31 23:59:59.999_999_999
// Assuming `large-dates` feature is disabled.
assert_eq!(PrimitiveDateTime::MAX, datetime!(+9999-12-31 23:59:59.999_999_999));
Runsourcepub const fn year(self) -> i32
pub const fn year(self) -> i32
Get the year of the date.
assert_eq!(datetime!(2019-01-01 0:00).year(), 2019);
assert_eq!(datetime!(2019-12-31 0:00).year(), 2019);
assert_eq!(datetime!(2020-01-01 0:00).year(), 2020);
Runsourcepub const fn month(self) -> Month
pub const fn month(self) -> Month
Get the month of the date.
assert_eq!(datetime!(2019-01-01 0:00).month(), Month::January);
assert_eq!(datetime!(2019-12-31 0:00).month(), Month::December);
Runsourcepub const fn day(self) -> u8
pub const fn day(self) -> u8
Get the day of the date.
The returned value will always be in the range 1..=31
.
assert_eq!(datetime!(2019-01-01 0:00).day(), 1);
assert_eq!(datetime!(2019-12-31 0:00).day(), 31);
Runsourcepub const fn ordinal(self) -> u16
pub const fn ordinal(self) -> u16
Get the day of the year.
The returned value will always be in the range 1..=366
(1..=365
for common years).
assert_eq!(datetime!(2019-01-01 0:00).ordinal(), 1);
assert_eq!(datetime!(2019-12-31 0:00).ordinal(), 365);
Runsourcepub const fn iso_week(self) -> u8
pub const fn iso_week(self) -> u8
Get the ISO week number.
The returned value will always be in the range 1..=53
.
assert_eq!(datetime!(2019-01-01 0:00).iso_week(), 1);
assert_eq!(datetime!(2019-10-04 0:00).iso_week(), 40);
assert_eq!(datetime!(2020-01-01 0:00).iso_week(), 1);
assert_eq!(datetime!(2020-12-31 0:00).iso_week(), 53);
assert_eq!(datetime!(2021-01-01 0:00).iso_week(), 53);
Runsourcepub const fn sunday_based_week(self) -> u8
pub const fn sunday_based_week(self) -> u8
Get the week number where week 1 begins on the first Sunday.
The returned value will always be in the range 0..=53
.
assert_eq!(datetime!(2019-01-01 0:00).sunday_based_week(), 0);
assert_eq!(datetime!(2020-01-01 0:00).sunday_based_week(), 0);
assert_eq!(datetime!(2020-12-31 0:00).sunday_based_week(), 52);
assert_eq!(datetime!(2021-01-01 0:00).sunday_based_week(), 0);
Runsourcepub const fn monday_based_week(self) -> u8
pub const fn monday_based_week(self) -> u8
Get the week number where week 1 begins on the first Monday.
The returned value will always be in the range 0..=53
.
assert_eq!(datetime!(2019-01-01 0:00).monday_based_week(), 0);
assert_eq!(datetime!(2020-01-01 0:00).monday_based_week(), 0);
assert_eq!(datetime!(2020-12-31 0:00).monday_based_week(), 52);
assert_eq!(datetime!(2021-01-01 0:00).monday_based_week(), 0);
Runsourcepub const fn to_calendar_date(self) -> (i32, Month, u8)
pub const fn to_calendar_date(self) -> (i32, Month, u8)
Get the year, month, and day.
assert_eq!(
datetime!(2019-01-01 0:00).to_calendar_date(),
(2019, Month::January, 1)
);
Runsourcepub const fn to_ordinal_date(self) -> (i32, u16)
pub const fn to_ordinal_date(self) -> (i32, u16)
Get the year and ordinal day number.
assert_eq!(datetime!(2019-01-01 0:00).to_ordinal_date(), (2019, 1));
Runsourcepub const fn to_iso_week_date(self) -> (i32, u8, Weekday)
pub const fn to_iso_week_date(self) -> (i32, u8, Weekday)
Get the ISO 8601 year, week number, and weekday.
assert_eq!(
datetime!(2019-01-01 0:00).to_iso_week_date(),
(2019, 1, Tuesday)
);
assert_eq!(
datetime!(2019-10-04 0:00).to_iso_week_date(),
(2019, 40, Friday)
);
assert_eq!(
datetime!(2020-01-01 0:00).to_iso_week_date(),
(2020, 1, Wednesday)
);
assert_eq!(
datetime!(2020-12-31 0:00).to_iso_week_date(),
(2020, 53, Thursday)
);
assert_eq!(
datetime!(2021-01-01 0:00).to_iso_week_date(),
(2020, 53, Friday)
);
Runsourcepub const fn weekday(self) -> Weekday
pub const fn weekday(self) -> Weekday
Get the weekday.
assert_eq!(datetime!(2019-01-01 0:00).weekday(), Tuesday);
assert_eq!(datetime!(2019-02-01 0:00).weekday(), Friday);
assert_eq!(datetime!(2019-03-01 0:00).weekday(), Friday);
assert_eq!(datetime!(2019-04-01 0:00).weekday(), Monday);
assert_eq!(datetime!(2019-05-01 0:00).weekday(), Wednesday);
assert_eq!(datetime!(2019-06-01 0:00).weekday(), Saturday);
assert_eq!(datetime!(2019-07-01 0:00).weekday(), Monday);
assert_eq!(datetime!(2019-08-01 0:00).weekday(), Thursday);
assert_eq!(datetime!(2019-09-01 0:00).weekday(), Sunday);
assert_eq!(datetime!(2019-10-01 0:00).weekday(), Tuesday);
assert_eq!(datetime!(2019-11-01 0:00).weekday(), Friday);
assert_eq!(datetime!(2019-12-01 0:00).weekday(), Sunday);
Runsourcepub const fn to_julian_day(self) -> i32
pub const fn to_julian_day(self) -> i32
Get the Julian day for the date. The time is not taken into account for this calculation.
The algorithm to perform this conversion is derived from one provided by Peter Baum; it is freely available here.
assert_eq!(datetime!(-4713-11-24 0:00).to_julian_day(), 0);
assert_eq!(datetime!(2000-01-01 0:00).to_julian_day(), 2_451_545);
assert_eq!(datetime!(2019-01-01 0:00).to_julian_day(), 2_458_485);
assert_eq!(datetime!(2019-12-31 0:00).to_julian_day(), 2_458_849);
Runsourcepub const fn as_hms(self) -> (u8, u8, u8)
pub const fn as_hms(self) -> (u8, u8, u8)
Get the clock hour, minute, and second.
assert_eq!(datetime!(2020-01-01 0:00:00).as_hms(), (0, 0, 0));
assert_eq!(datetime!(2020-01-01 23:59:59).as_hms(), (23, 59, 59));
Runsourcepub const fn as_hms_milli(self) -> (u8, u8, u8, u16)
pub const fn as_hms_milli(self) -> (u8, u8, u8, u16)
Get the clock hour, minute, second, and millisecond.
assert_eq!(datetime!(2020-01-01 0:00:00).as_hms_milli(), (0, 0, 0, 0));
assert_eq!(
datetime!(2020-01-01 23:59:59.999).as_hms_milli(),
(23, 59, 59, 999)
);
Runsourcepub const fn as_hms_micro(self) -> (u8, u8, u8, u32)
pub const fn as_hms_micro(self) -> (u8, u8, u8, u32)
Get the clock hour, minute, second, and microsecond.
assert_eq!(datetime!(2020-01-01 0:00:00).as_hms_micro(), (0, 0, 0, 0));
assert_eq!(
datetime!(2020-01-01 23:59:59.999_999).as_hms_micro(),
(23, 59, 59, 999_999)
);
Runsourcepub const fn as_hms_nano(self) -> (u8, u8, u8, u32)
pub const fn as_hms_nano(self) -> (u8, u8, u8, u32)
Get the clock hour, minute, second, and nanosecond.
assert_eq!(datetime!(2020-01-01 0:00:00).as_hms_nano(), (0, 0, 0, 0));
assert_eq!(
datetime!(2020-01-01 23:59:59.999_999_999).as_hms_nano(),
(23, 59, 59, 999_999_999)
);
Runsourcepub const fn hour(self) -> u8
pub const fn hour(self) -> u8
Get the clock hour.
The returned value will always be in the range 0..24
.
assert_eq!(datetime!(2019-01-01 0:00).hour(), 0);
assert_eq!(datetime!(2019-01-01 23:59:59).hour(), 23);
Runsourcepub const fn minute(self) -> u8
pub const fn minute(self) -> u8
Get the minute within the hour.
The returned value will always be in the range 0..60
.
assert_eq!(datetime!(2019-01-01 0:00).minute(), 0);
assert_eq!(datetime!(2019-01-01 23:59:59).minute(), 59);
Runsourcepub const fn second(self) -> u8
pub const fn second(self) -> u8
Get the second within the minute.
The returned value will always be in the range 0..60
.
assert_eq!(datetime!(2019-01-01 0:00).second(), 0);
assert_eq!(datetime!(2019-01-01 23:59:59).second(), 59);
Runsourcepub const fn millisecond(self) -> u16
pub const fn millisecond(self) -> u16
Get the milliseconds within the second.
The returned value will always be in the range 0..1_000
.
assert_eq!(datetime!(2019-01-01 0:00).millisecond(), 0);
assert_eq!(datetime!(2019-01-01 23:59:59.999).millisecond(), 999);
Runsourcepub const fn microsecond(self) -> u32
pub const fn microsecond(self) -> u32
Get the microseconds within the second.
The returned value will always be in the range 0..1_000_000
.
assert_eq!(datetime!(2019-01-01 0:00).microsecond(), 0);
assert_eq!(
datetime!(2019-01-01 23:59:59.999_999).microsecond(),
999_999
);
Runsourcepub const fn nanosecond(self) -> u32
pub 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
.
assert_eq!(datetime!(2019-01-01 0:00).nanosecond(), 0);
assert_eq!(
datetime!(2019-01-01 23:59:59.999_999_999).nanosecond(),
999_999_999,
);
Runsourcepub const fn assume_offset(self, offset: UtcOffset) -> OffsetDateTime
pub const fn assume_offset(self, offset: UtcOffset) -> OffsetDateTime
Assuming that the existing PrimitiveDateTime
represents a moment in the provided
UtcOffset
, return an OffsetDateTime
.
assert_eq!(
datetime!(2019-01-01 0:00)
.assume_offset(offset!(UTC))
.unix_timestamp(),
1_546_300_800,
);
assert_eq!(
datetime!(2019-01-01 0:00)
.assume_offset(offset!(-1))
.unix_timestamp(),
1_546_304_400,
);
Runsourcepub const fn assume_utc(self) -> OffsetDateTime
pub const fn assume_utc(self) -> OffsetDateTime
Assuming that the existing PrimitiveDateTime
represents a moment in UTC, return an
OffsetDateTime
.
assert_eq!(
datetime!(2019-01-01 0:00).assume_utc().unix_timestamp(),
1_546_300_800,
);
Runsourcepub const fn checked_add(self, duration: Duration) -> Option<Self>
pub const fn checked_add(self, duration: Duration) -> Option<Self>
Computes self + duration
, returning None
if an overflow occurred.
let datetime = Date::MIN.midnight();
assert_eq!(datetime.checked_add((-2).days()), None);
let datetime = Date::MAX.midnight();
assert_eq!(datetime.checked_add(1.days()), None);
assert_eq!(
datetime!(2019 - 11 - 25 15:30).checked_add(27.hours()),
Some(datetime!(2019 - 11 - 26 18:30))
);
Runsourcepub const fn checked_sub(self, duration: Duration) -> Option<Self>
pub const fn checked_sub(self, duration: Duration) -> Option<Self>
Computes self - duration
, returning None
if an overflow occurred.
let datetime = Date::MIN.midnight();
assert_eq!(datetime.checked_sub(2.days()), None);
let datetime = Date::MAX.midnight();
assert_eq!(datetime.checked_sub((-1).days()), None);
assert_eq!(
datetime!(2019 - 11 - 25 15:30).checked_sub(27.hours()),
Some(datetime!(2019 - 11 - 24 12:30))
);
Runsourcepub const fn saturating_add(self, duration: Duration) -> Self
pub const fn saturating_add(self, duration: Duration) -> Self
Computes self + duration
, saturating value on overflow.
assert_eq!(
PrimitiveDateTime::MIN.saturating_add((-2).days()),
PrimitiveDateTime::MIN
);
assert_eq!(
PrimitiveDateTime::MAX.saturating_add(2.days()),
PrimitiveDateTime::MAX
);
assert_eq!(
datetime!(2019 - 11 - 25 15:30).saturating_add(27.hours()),
datetime!(2019 - 11 - 26 18:30)
);
Runsourcepub const fn saturating_sub(self, duration: Duration) -> Self
pub const fn saturating_sub(self, duration: Duration) -> Self
Computes self - duration
, saturating value on overflow.
assert_eq!(
PrimitiveDateTime::MIN.saturating_sub(2.days()),
PrimitiveDateTime::MIN
);
assert_eq!(
PrimitiveDateTime::MAX.saturating_sub((-2).days()),
PrimitiveDateTime::MAX
);
assert_eq!(
datetime!(2019 - 11 - 25 15:30).saturating_sub(27.hours()),
datetime!(2019 - 11 - 24 12:30)
);
Runsource§impl PrimitiveDateTime
impl PrimitiveDateTime
Methods that replace part of the PrimitiveDateTime
.
sourcepub const fn replace_time(self, time: Time) -> Self
pub const fn replace_time(self, time: Time) -> Self
Replace the time, preserving the date.
assert_eq!(
datetime!(2020-01-01 17:00).replace_time(time!(5:00)),
datetime!(2020-01-01 5:00)
);
Runsourcepub const fn replace_date(self, date: Date) -> Self
pub const fn replace_date(self, date: Date) -> Self
Replace the date, preserving the time.
assert_eq!(
datetime!(2020-01-01 12:00).replace_date(date!(2020-01-30)),
datetime!(2020-01-30 12:00)
);
Runsourcepub const fn replace_year(self, year: i32) -> Result<Self, ComponentRange>
pub const fn replace_year(self, year: i32) -> Result<Self, ComponentRange>
Replace the year. The month and day will be unchanged.
assert_eq!(
datetime!(2022 - 02 - 18 12:00).replace_year(2019),
Ok(datetime!(2019 - 02 - 18 12:00))
);
assert!(datetime!(2022 - 02 - 18 12:00).replace_year(-1_000_000_000).is_err()); // -1_000_000_000 isn't a valid year
assert!(datetime!(2022 - 02 - 18 12:00).replace_year(1_000_000_000).is_err()); // 1_000_000_000 isn't a valid year
Runsourcepub const fn replace_month(self, month: Month) -> Result<Self, ComponentRange>
pub const fn replace_month(self, month: Month) -> Result<Self, ComponentRange>
Replace the month of the year.
assert_eq!(
datetime!(2022 - 02 - 18 12:00).replace_month(Month::January),
Ok(datetime!(2022 - 01 - 18 12:00))
);
assert!(datetime!(2022 - 01 - 30 12:00).replace_month(Month::February).is_err()); // 30 isn't a valid day in February
Runsourcepub const fn replace_day(self, day: u8) -> Result<Self, ComponentRange>
pub const fn replace_day(self, day: u8) -> Result<Self, ComponentRange>
Replace the day of the month.
assert_eq!(
datetime!(2022 - 02 - 18 12:00).replace_day(1),
Ok(datetime!(2022 - 02 - 01 12:00))
);
assert!(datetime!(2022 - 02 - 18 12:00).replace_day(0).is_err()); // 00 isn't a valid day
assert!(datetime!(2022 - 02 - 18 12:00).replace_day(30).is_err()); // 30 isn't a valid day in February
Runsourcepub const fn replace_hour(self, hour: u8) -> Result<Self, ComponentRange>
pub const fn replace_hour(self, hour: u8) -> Result<Self, ComponentRange>
Replace the clock hour.
assert_eq!(
datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_hour(7),
Ok(datetime!(2022 - 02 - 18 07:02:03.004_005_006))
);
assert!(datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_hour(24).is_err()); // 24 isn't a valid hour
Runsourcepub const fn replace_minute(self, minute: u8) -> Result<Self, ComponentRange>
pub const fn replace_minute(self, minute: u8) -> Result<Self, ComponentRange>
Replace the minutes within the hour.
assert_eq!(
datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_minute(7),
Ok(datetime!(2022 - 02 - 18 01:07:03.004_005_006))
);
assert!(datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_minute(60).is_err()); // 60 isn't a valid minute
Runsourcepub const fn replace_second(self, second: u8) -> Result<Self, ComponentRange>
pub const fn replace_second(self, second: u8) -> Result<Self, ComponentRange>
Replace the seconds within the minute.
assert_eq!(
datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_second(7),
Ok(datetime!(2022 - 02 - 18 01:02:07.004_005_006))
);
assert!(datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_second(60).is_err()); // 60 isn't a valid second
Runsourcepub const fn replace_millisecond(
self,
millisecond: u16
) -> Result<Self, ComponentRange>
pub const fn replace_millisecond( self, millisecond: u16 ) -> Result<Self, ComponentRange>
Replace the milliseconds within the second.
assert_eq!(
datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_millisecond(7),
Ok(datetime!(2022 - 02 - 18 01:02:03.007))
);
assert!(datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_millisecond(1_000).is_err()); // 1_000 isn't a valid millisecond
Runsourcepub const fn replace_microsecond(
self,
microsecond: u32
) -> Result<Self, ComponentRange>
pub const fn replace_microsecond( self, microsecond: u32 ) -> Result<Self, ComponentRange>
Replace the microseconds within the second.
assert_eq!(
datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_microsecond(7_008),
Ok(datetime!(2022 - 02 - 18 01:02:03.007_008))
);
assert!(datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_microsecond(1_000_000).is_err()); // 1_000_000 isn't a valid microsecond
Runsourcepub const fn replace_nanosecond(
self,
nanosecond: u32
) -> Result<Self, ComponentRange>
pub const fn replace_nanosecond( self, nanosecond: u32 ) -> Result<Self, ComponentRange>
Replace the nanoseconds within the second.
assert_eq!(
datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_nanosecond(7_008_009),
Ok(datetime!(2022 - 02 - 18 01:02:03.007_008_009))
);
assert!(datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_nanosecond(1_000_000_000).is_err()); // 1_000_000_000 isn't a valid nanosecond
Runsource§impl PrimitiveDateTime
impl PrimitiveDateTime
sourcepub fn format_into(
self,
output: &mut impl Write,
format: &(impl Formattable + ?Sized)
) -> Result<usize, Format>
pub fn format_into( self, output: &mut impl Write, format: &(impl Formattable + ?Sized) ) -> Result<usize, Format>
Format the PrimitiveDateTime
using the provided format
description.
sourcepub fn format(
self,
format: &(impl Formattable + ?Sized)
) -> Result<String, Format>
pub fn format( self, format: &(impl Formattable + ?Sized) ) -> Result<String, Format>
Format the PrimitiveDateTime
using the provided format
description.
let format = format_description::parse("[year]-[month]-[day] [hour]:[minute]:[second]")?;
assert_eq!(
datetime!(2020-01-02 03:04:05).format(&format)?,
"2020-01-02 03:04:05"
);
RunTrait Implementations§
source§impl Add<Duration> for PrimitiveDateTime
impl Add<Duration> for PrimitiveDateTime
§type Output = PrimitiveDateTime
type Output = PrimitiveDateTime
+
operator.source§impl Add<Duration> for PrimitiveDateTime
impl Add<Duration> for PrimitiveDateTime
source§impl AddAssign<Duration> for PrimitiveDateTime
impl AddAssign<Duration> for PrimitiveDateTime
source§fn add_assign(&mut self, duration: StdDuration)
fn add_assign(&mut self, duration: StdDuration)
+=
operation. Read moresource§impl AddAssign<Duration> for PrimitiveDateTime
impl AddAssign<Duration> for PrimitiveDateTime
source§fn add_assign(&mut self, duration: Duration)
fn add_assign(&mut self, duration: Duration)
+=
operation. Read moresource§impl Clone for PrimitiveDateTime
impl Clone for PrimitiveDateTime
source§fn clone(&self) -> PrimitiveDateTime
fn clone(&self) -> PrimitiveDateTime
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for PrimitiveDateTime
impl Debug for PrimitiveDateTime
source§impl Display for PrimitiveDateTime
impl Display for PrimitiveDateTime
source§impl Hash for PrimitiveDateTime
impl Hash for PrimitiveDateTime
source§impl Ord for PrimitiveDateTime
impl Ord for PrimitiveDateTime
source§fn cmp(&self, other: &PrimitiveDateTime) -> Ordering
fn cmp(&self, other: &PrimitiveDateTime) -> Ordering
1.21.0 · source§fn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
source§impl PartialEq for PrimitiveDateTime
impl PartialEq for PrimitiveDateTime
source§fn eq(&self, other: &PrimitiveDateTime) -> bool
fn eq(&self, other: &PrimitiveDateTime) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialOrd for PrimitiveDateTime
impl PartialOrd for PrimitiveDateTime
source§fn partial_cmp(&self, other: &PrimitiveDateTime) -> Option<Ordering>
fn partial_cmp(&self, other: &PrimitiveDateTime) -> Option<Ordering>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl Sub<Duration> for PrimitiveDateTime
impl Sub<Duration> for PrimitiveDateTime
source§impl Sub<Duration> for PrimitiveDateTime
impl Sub<Duration> for PrimitiveDateTime
§type Output = PrimitiveDateTime
type Output = PrimitiveDateTime
-
operator.source§impl Sub for PrimitiveDateTime
impl Sub for PrimitiveDateTime
source§impl SubAssign<Duration> for PrimitiveDateTime
impl SubAssign<Duration> for PrimitiveDateTime
source§fn sub_assign(&mut self, duration: Duration)
fn sub_assign(&mut self, duration: Duration)
-=
operation. Read moresource§impl SubAssign<Duration> for PrimitiveDateTime
impl SubAssign<Duration> for PrimitiveDateTime
source§fn sub_assign(&mut self, duration: StdDuration)
fn sub_assign(&mut self, duration: StdDuration)
-=
operation. Read more