Struct `UtcDateTime`

#[repr(transparent)]
pub struct UtcDateTime { /* private fields */ }

A PlainDateTime that is known to be UTC.

UtcDateTime is guaranteed to be ABI-compatible with PlainDateTime, meaning that transmuting from one to the other will not result in undefined behavior.

Implementations

`impl UtcDateTime`

const UNIX_EPOCH: Self = _;

Midnight, 1 January, 1970.

# use time::UtcDateTime;
# use time_macros::utc_datetime;
assert_eq!(UtcDateTime::UNIX_EPOCH, utc_datetime!(1970-01-01 0:00));

const MIN: Self = _;

The smallest value that can be represented by UtcDateTime.

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

# use time::UtcDateTime;
# use time_macros::utc_datetime;
// Assuming `large-dates` feature is disabled.
assert_eq!(UtcDateTime::MIN, utc_datetime!(-9999-01-01 0:00));

const MAX: Self = _;

The largest value that can be represented by UtcDateTime.

Depending on large-dates feature flag, value of this constant may vary.

With large-dates disabled it is equal to 9999-12-31 23:59:59.999_999_999
With large-dates enabled it is equal to 999999-12-31 23:59:59.999_999_999

# use time::UtcDateTime;
# use time_macros::utc_datetime;
// Assuming `large-dates` feature is disabled.
assert_eq!(UtcDateTime::MAX, utc_datetime!(+9999-12-31 23:59:59.999_999_999));

fn now() -> Self

Create a new UtcDateTime with the current date and time.

# use time::UtcDateTime;
assert!(UtcDateTime::now().year() >= 2019);

const fn new(date: Date, time: Time) -> Self

Create a new UtcDateTime from the provided Date and Time.

# use time::UtcDateTime;
# use time_macros::{date, utc_datetime, time};
assert_eq!(
    UtcDateTime::new(date!(2019-01-01), time!(0:00)),
    utc_datetime!(2019-01-01 0:00),
);

const fn from_unix_timestamp(timestamp: i64) -> Result<Self, ComponentRange>

Create a UtcDateTime from the provided Unix timestamp.

# use time::UtcDateTime;
# use time_macros::utc_datetime;
assert_eq!(
    UtcDateTime::from_unix_timestamp(0),
    Ok(UtcDateTime::UNIX_EPOCH),
);
assert_eq!(
    UtcDateTime::from_unix_timestamp(1_546_300_800),
    Ok(utc_datetime!(2019-01-01 0:00)),
);

If you have a timestamp-nanosecond pair, you can use something along the lines of the following:

# use time::{SignedDuration, UtcDateTime, ext::NumericalDuration};
let (timestamp, nanos) = (1, 500_000_000);
assert_eq!(
    UtcDateTime::from_unix_timestamp(timestamp)? + SignedDuration::nanoseconds(nanos),
    UtcDateTime::UNIX_EPOCH + 1.5.seconds()
);
# Ok::<_, time::Error>(())

const fn from_unix_timestamp_nanos(timestamp: i128) -> Result<Self, ComponentRange>

Construct an UtcDateTime from the provided Unix timestamp (in nanoseconds).

# use time::UtcDateTime;
# use time_macros::utc_datetime;
assert_eq!(
    UtcDateTime::from_unix_timestamp_nanos(0),
    Ok(UtcDateTime::UNIX_EPOCH),
);
assert_eq!(
    UtcDateTime::from_unix_timestamp_nanos(1_546_300_800_000_000_000),
    Ok(utc_datetime!(2019-01-01 0:00)),
);

const fn to_offset(self, offset: UtcOffset) -> OffsetDateTime

Convert the UtcDateTime from UTC to the provided UtcOffset, returning an OffsetDateTime.

# use time_macros::{utc_datetime, offset};
assert_eq!(
    utc_datetime!(2000-01-01 0:00)
        .to_offset(offset!(-1))
        .year(),
    1999,
);

// Construct midnight on new year's, UTC.
let utc = utc_datetime!(2000-01-01 0:00);
let new_york = utc.to_offset(offset!(-5));
let los_angeles = utc.to_offset(offset!(-8));
assert_eq!(utc.hour(), 0);
assert_eq!(new_york.hour(), 19);
assert_eq!(los_angeles.hour(), 16);

Panics

This method panics if the local date-time in the new offset is outside the supported range.

const fn checked_to_offset(self, offset: UtcOffset) -> Option<OffsetDateTime>

Convert the UtcDateTime from UTC to the provided UtcOffset, returning an OffsetDateTime. None is returned if the date-time in the resulting offset is invalid.

# use time::UtcDateTime;
# use time_macros::{utc_datetime, offset};
assert_eq!(
    utc_datetime!(2000-01-01 0:00)
        .checked_to_offset(offset!(-1))
        .unwrap()
        .year(),
    1999,
);
assert_eq!(
    UtcDateTime::MAX.checked_to_offset(offset!(+1)),
    None,
);

const fn unix_timestamp(self) -> i64

Get the Unix timestamp.

# use time_macros::utc_datetime;
assert_eq!(utc_datetime!(1970-01-01 0:00).unix_timestamp(), 0);
assert_eq!(utc_datetime!(1970-01-01 1:00).unix_timestamp(), 3_600);

const fn unix_timestamp_nanos(self) -> i128

Get the Unix timestamp in nanoseconds.

use time_macros::utc_datetime;
assert_eq!(utc_datetime!(1970-01-01 0:00).unix_timestamp_nanos(), 0);
assert_eq!(
    utc_datetime!(1970-01-01 1:00).unix_timestamp_nanos(),
    3_600_000_000_000,
);

const fn date(self) -> Date

Get the Date component of the UtcDateTime.

# use time_macros::{date, utc_datetime};
assert_eq!(utc_datetime!(2019-01-01 0:00).date(), date!(2019-01-01));

const fn time(self) -> Time

Get the Time component of the UtcDateTime.

# use time_macros::{utc_datetime, time};
assert_eq!(utc_datetime!(2019-01-01 0:00).time(), time!(0:00));

const fn year(self) -> i32

Get the year of the date.

# use time_macros::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).year(), 2019);
assert_eq!(utc_datetime!(2019-12-31 0:00).year(), 2019);
assert_eq!(utc_datetime!(2020-01-01 0:00).year(), 2020);

const fn month(self) -> Month

Get the month of the date.

# use time::Month;
# use time_macros::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).month(), Month::January);
assert_eq!(utc_datetime!(2019-12-31 0:00).month(), Month::December);

const fn day(self) -> u8

Get the day of the date.

The returned value will always be in the range 1..=31.

# use time_macros::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).day(), 1);
assert_eq!(utc_datetime!(2019-12-31 0:00).day(), 31);

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).

# use time_macros::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).ordinal(), 1);
assert_eq!(utc_datetime!(2019-12-31 0:00).ordinal(), 365);

const fn iso_week(self) -> u8

Get the ISO week number.

The returned value will always be in the range 1..=53.

# use time_macros::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).iso_week(), 1);
assert_eq!(utc_datetime!(2019-10-04 0:00).iso_week(), 40);
assert_eq!(utc_datetime!(2020-01-01 0:00).iso_week(), 1);
assert_eq!(utc_datetime!(2020-12-31 0:00).iso_week(), 53);
assert_eq!(utc_datetime!(2021-01-01 0:00).iso_week(), 53);

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.

# use time_macros::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).sunday_based_week(), 0);
assert_eq!(utc_datetime!(2020-01-01 0:00).sunday_based_week(), 0);
assert_eq!(utc_datetime!(2020-12-31 0:00).sunday_based_week(), 52);
assert_eq!(utc_datetime!(2021-01-01 0:00).sunday_based_week(), 0);

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.

# use time_macros::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).monday_based_week(), 0);
assert_eq!(utc_datetime!(2020-01-01 0:00).monday_based_week(), 0);
assert_eq!(utc_datetime!(2020-12-31 0:00).monday_based_week(), 52);
assert_eq!(utc_datetime!(2021-01-01 0:00).monday_based_week(), 0);

const fn to_calendar_date(self) -> (i32, Month, u8)

Get the year, month, and day.

# use time::Month;
# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2019-01-01 0:00).to_calendar_date(),
    (2019, Month::January, 1)
);

const fn to_ordinal_date(self) -> (i32, u16)

Get the year and ordinal day number.

# use time_macros::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).to_ordinal_date(), (2019, 1));

const fn to_iso_week_date(self) -> (i32, u8, Weekday)

Get the ISO 8601 year, week number, and weekday.

# use time::Weekday::*;
# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2019-01-01 0:00).to_iso_week_date(),
    (2019, 1, Tuesday)
);
assert_eq!(
    utc_datetime!(2019-10-04 0:00).to_iso_week_date(),
    (2019, 40, Friday)
);
assert_eq!(
    utc_datetime!(2020-01-01 0:00).to_iso_week_date(),
    (2020, 1, Wednesday)
);
assert_eq!(
    utc_datetime!(2020-12-31 0:00).to_iso_week_date(),
    (2020, 53, Thursday)
);
assert_eq!(
    utc_datetime!(2021-01-01 0:00).to_iso_week_date(),
    (2020, 53, Friday)
);

const fn weekday(self) -> Weekday

Get the weekday.

# use time::Weekday::*;
# use time_macros::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).weekday(), Tuesday);
assert_eq!(utc_datetime!(2019-02-01 0:00).weekday(), Friday);
assert_eq!(utc_datetime!(2019-03-01 0:00).weekday(), Friday);
assert_eq!(utc_datetime!(2019-04-01 0:00).weekday(), Monday);
assert_eq!(utc_datetime!(2019-05-01 0:00).weekday(), Wednesday);
assert_eq!(utc_datetime!(2019-06-01 0:00).weekday(), Saturday);
assert_eq!(utc_datetime!(2019-07-01 0:00).weekday(), Monday);
assert_eq!(utc_datetime!(2019-08-01 0:00).weekday(), Thursday);
assert_eq!(utc_datetime!(2019-09-01 0:00).weekday(), Sunday);
assert_eq!(utc_datetime!(2019-10-01 0:00).weekday(), Tuesday);
assert_eq!(utc_datetime!(2019-11-01 0:00).weekday(), Friday);
assert_eq!(utc_datetime!(2019-12-01 0:00).weekday(), Sunday);

const fn to_julian_day(self) -> i32

Get the Julian day for the date. The time is not taken into account for this calculation.

# use time_macros::utc_datetime;
assert_eq!(utc_datetime!(-4713-11-24 0:00).to_julian_day(), 0);
assert_eq!(utc_datetime!(2000-01-01 0:00).to_julian_day(), 2_451_545);
assert_eq!(utc_datetime!(2019-01-01 0:00).to_julian_day(), 2_458_485);
assert_eq!(utc_datetime!(2019-12-31 0:00).to_julian_day(), 2_458_849);

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

Get the clock hour, minute, and second.

# use time_macros::utc_datetime;
assert_eq!(utc_datetime!(2020-01-01 0:00:00).as_hms(), (0, 0, 0));
assert_eq!(utc_datetime!(2020-01-01 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::utc_datetime;
assert_eq!(utc_datetime!(2020-01-01 0:00:00).as_hms_milli(), (0, 0, 0, 0));
assert_eq!(
    utc_datetime!(2020-01-01 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::utc_datetime;
assert_eq!(utc_datetime!(2020-01-01 0:00:00).as_hms_micro(), (0, 0, 0, 0));
assert_eq!(
    utc_datetime!(2020-01-01 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::utc_datetime;
assert_eq!(utc_datetime!(2020-01-01 0:00:00).as_hms_nano(), (0, 0, 0, 0));
assert_eq!(
    utc_datetime!(2020-01-01 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::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).hour(), 0);
assert_eq!(utc_datetime!(2019-01-01 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::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).minute(), 0);
assert_eq!(utc_datetime!(2019-01-01 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::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).second(), 0);
assert_eq!(utc_datetime!(2019-01-01 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::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).millisecond(), 0);
assert_eq!(utc_datetime!(2019-01-01 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::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).microsecond(), 0);
assert_eq!(
    utc_datetime!(2019-01-01 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::utc_datetime;
assert_eq!(utc_datetime!(2019-01-01 0:00).nanosecond(), 0);
assert_eq!(
    utc_datetime!(2019-01-01 23:59:59.999_999_999).nanosecond(),
    999_999_999,
);

const fn checked_add(self, duration: SignedDuration) -> Option<Self>

Computes self + duration, returning None if an overflow occurred.

# use time::{UtcDateTime, ext::NumericalDuration};
# use time_macros::utc_datetime;
assert_eq!(UtcDateTime::MIN.checked_add((-2).days()), None);
assert_eq!(UtcDateTime::MAX.checked_add(1.days()), None);
assert_eq!(
    utc_datetime!(2019-11-25 15:30).checked_add(27.hours()),
    Some(utc_datetime!(2019-11-26 18:30))
);

const fn checked_sub(self, duration: SignedDuration) -> Option<Self>

Computes self - duration, returning None if an overflow occurred.

# use time::{UtcDateTime, ext::NumericalDuration};
# use time_macros::utc_datetime;
assert_eq!(UtcDateTime::MIN.checked_sub(2.days()), None);
assert_eq!(UtcDateTime::MAX.checked_sub((-1).days()), None);
assert_eq!(
    utc_datetime!(2019-11-25 15:30).checked_sub(27.hours()),
    Some(utc_datetime!(2019-11-24 12:30))
);

const fn saturating_add(self, duration: SignedDuration) -> Self

Computes self + duration, saturating value on overflow.

# use time::{UtcDateTime, ext::NumericalDuration};
# use time_macros::utc_datetime;
assert_eq!(
    UtcDateTime::MIN.saturating_add((-2).days()),
    UtcDateTime::MIN
);
assert_eq!(
    UtcDateTime::MAX.saturating_add(2.days()),
    UtcDateTime::MAX
);
assert_eq!(
    utc_datetime!(2019-11-25 15:30).saturating_add(27.hours()),
    utc_datetime!(2019-11-26 18:30)
);

const fn saturating_sub(self, duration: SignedDuration) -> Self

Computes self - duration, saturating value on overflow.

# use time::{UtcDateTime, ext::NumericalDuration};
# use time_macros::utc_datetime;
assert_eq!(
    UtcDateTime::MIN.saturating_sub(2.days()),
    UtcDateTime::MIN
);
assert_eq!(
    UtcDateTime::MAX.saturating_sub((-2).days()),
    UtcDateTime::MAX
);
assert_eq!(
    utc_datetime!(2019-11-25 15:30).saturating_sub(27.hours()),
    utc_datetime!(2019-11-24 12:30)
);

`impl UtcDateTime`

const fn replace_time(self, time: Time) -> Self

Replace the time, preserving the date.

# use time_macros::{utc_datetime, time};
assert_eq!(
    utc_datetime!(2020-01-01 17:00).replace_time(time!(5:00)),
    utc_datetime!(2020-01-01 5:00)
);

const fn replace_date(self, date: Date) -> Self

Replace the date, preserving the time.

# use time_macros::{utc_datetime, date};
assert_eq!(
    utc_datetime!(2020-01-01 12:00).replace_date(date!(2020-01-30)),
    utc_datetime!(2020-01-30 12:00)
);

const fn replace_year(self, year: i32) -> Result<Self, ComponentRange>

Replace the year. The month and day will be unchanged.

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 12:00).replace_year(2019),
    Ok(utc_datetime!(2019-02-18 12:00))
);
assert!(utc_datetime!(2022-02-18 12:00).replace_year(-1_000_000_000).is_err()); // -1_000_000_000 isn't a valid year
assert!(utc_datetime!(2022-02-18 12:00).replace_year(1_000_000_000).is_err()); // 1_000_000_000 isn't a valid year

const fn replace_month(self, month: Month) -> Result<Self, ComponentRange>

Replace the month of the year.

# use time_macros::utc_datetime;
# use time::Month;
assert_eq!(
    utc_datetime!(2022-02-18 12:00).replace_month(Month::January),
    Ok(utc_datetime!(2022-01-18 12:00))
);
assert!(utc_datetime!(2022-01-30 12:00).replace_month(Month::February).is_err()); // 30 isn't a valid day in February

const fn replace_day(self, day: u8) -> Result<Self, ComponentRange>

Replace the day of the month.

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 12:00).replace_day(1),
    Ok(utc_datetime!(2022-02-01 12:00))
);
assert!(utc_datetime!(2022-02-18 12:00).replace_day(0).is_err()); // 00 isn't a valid day
assert!(utc_datetime!(2022-02-18 12:00).replace_day(30).is_err()); // 30 isn't a valid day in February

const fn replace_ordinal(self, ordinal: u16) -> Result<Self, ComponentRange>

Replace the day of the year.

# use time_macros::utc_datetime;
assert_eq!(utc_datetime!(2022-049 12:00).replace_ordinal(1), Ok(utc_datetime!(2022-001 12:00)));
assert!(utc_datetime!(2022-049 12:00).replace_ordinal(0).is_err()); // 0 isn't a valid ordinal
assert!(utc_datetime!(2022-049 12:00).replace_ordinal(366).is_err()); // 2022 isn't a leap year

const fn truncate_to_day(self) -> Self

Truncate to the start of the day, setting the time to midnight.

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 15:30:45.123_456_789).truncate_to_day(),
    utc_datetime!(2022-02-18 0:00)
);

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

Replace the clock hour.

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 01:02:03.004_005_006).replace_hour(7),
    Ok(utc_datetime!(2022-02-18 07:02:03.004_005_006))
);
assert!(utc_datetime!(2022-02-18 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 to the hour, setting the minute, second, and subsecond components to zero.

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 15:30:45.123_456_789).truncate_to_hour(),
    utc_datetime!(2022-02-18 15:00)
);

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

Replace the minutes within the hour.

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 01:02:03.004_005_006).replace_minute(7),
    Ok(utc_datetime!(2022-02-18 01:07:03.004_005_006))
);
assert!(utc_datetime!(2022-02-18 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 to the minute, setting the second and subsecond components to zero.

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 15:30:45.123_456_789).truncate_to_minute(),
    utc_datetime!(2022-02-18 15:30)
);

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

Replace the seconds within the minute.

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 01:02:03.004_005_006).replace_second(7),
    Ok(utc_datetime!(2022-02-18 01:02:07.004_005_006))
);
assert!(utc_datetime!(2022-02-18 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 to the second, setting the subsecond components to zero.

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 15:30:45.123_456_789).truncate_to_second(),
    utc_datetime!(2022-02-18 15:30:45)
);

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

Replace the milliseconds within the second.

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 01:02:03.004_005_006).replace_millisecond(7),
    Ok(utc_datetime!(2022-02-18 01:02:03.007))
);
assert!(utc_datetime!(2022-02-18 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 to the millisecond, setting the microsecond and nanosecond components to zero.

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 15:30:45.123_456_789).truncate_to_millisecond(),
    utc_datetime!(2022-02-18 15:30:45.123)
);

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

Replace the microseconds within the second.

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 01:02:03.004_005_006).replace_microsecond(7_008),
    Ok(utc_datetime!(2022-02-18 01:02:03.007_008))
);
assert!(utc_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

const fn truncate_to_microsecond(self) -> Self

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

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 15:30:45.123_456_789).truncate_to_microsecond(),
    utc_datetime!(2022-02-18 15:30:45.123_456)
);

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

Replace the nanoseconds within the second.

# use time_macros::utc_datetime;
assert_eq!(
    utc_datetime!(2022-02-18 01:02:03.004_005_006).replace_nanosecond(7_008_009),
    Ok(utc_datetime!(2022-02-18 01:02:03.007_008_009))
);
assert!(utc_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