Struct `Timestamp`

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

A Unix timestamp with nanosecond precision.

This type represents a point in time as a number of seconds and nanoseconds elapsed since the Unix epoch (1970-01-01 00:00:00 UTC). Negative values represent times before the Unix epoch.

Implementations

`impl Timestamp`

const UNIX_EPOCH: Self = _;

A Timestamp representing the Unix epoch (1970-01-01 00:00:00 UTC).

const MIN: Self = _;

The minimum valid Timestamp.

The moment in time represented by this value may vary depending on the feature flags enabled.

const MAX: Self = _;

The maximum valid Timestamp.

The moment in time represented by this value may vary depending on the feature flags enabled.

fn now() -> Self

Create a new Timestamp representing the current moment in time.

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

const fn new(seconds: i64, nanoseconds: u32) -> Result<Self, ComponentRange>

Create a Timestamp from the provided Unix timestamp in seconds and nanoseconds, returning an error if the resulting value is out of range.

# use time::Timestamp;
assert!(Timestamp::new(0, 0).is_ok());
assert!(Timestamp::new(i64::MAX, 0).is_err());

const fn from_seconds(seconds: i64) -> Result<Self, ComponentRange>

Create a Timestamp from the provided Unix timestamp in seconds, returning an error if the resulting value is out of range.

# use time::Timestamp;
assert!(Timestamp::from_seconds(0).is_ok());
assert!(Timestamp::from_seconds(i64::MAX).is_err());

const fn from_milliseconds(milliseconds: i64) -> Result<Self, ComponentRange>

Create a Timestamp from the provided Unix timestamp in milliseconds, returning an error if the resulting value is out of range.

# use time::Timestamp;
assert!(Timestamp::from_milliseconds(0).is_ok());
assert!(Timestamp::from_milliseconds(i64::MAX).is_err());

const fn from_microseconds(microseconds: i128) -> Result<Self, ComponentRange>

Create a Timestamp from the provided Unix timestamp in microseconds, returning an error if the resulting value is out of range.

# use time::Timestamp;
assert!(Timestamp::from_microseconds(0).is_ok());
assert!(Timestamp::from_microseconds(i128::MAX).is_err());

const fn from_nanoseconds(nanoseconds: i128) -> Result<Self, ComponentRange>

Create a Timestamp from the provided Unix timestamp in nanoseconds, returning an error if the resulting value is out of range.

# use time::Timestamp;
assert!(Timestamp::from_nanoseconds(0).is_ok());
assert!(Timestamp::from_nanoseconds(i128::MAX).is_err());

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

Convert the Timestamp to an OffsetDateTime at the provided offset.

# use time_macros::{offset, timestamp};
assert_eq!(timestamp!(1_546_398_245).to_offset(offset!(+1)).hour(), 4);

Panics

This panics if the resulting date-time with the provided offset is outside the supported range. Consider using checked_to_offset for a non-panicking alternative.

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

Convert the Timestamp to an OffsetDateTime with the provided offset, returning None if the resulting value is out of range.

# use time_macros::{offset, timestamp};
assert!(
    timestamp!(1_546_398_245)
        .checked_to_offset(offset!(+1))
        .is_some()
);

const fn to_utc(self) -> UtcDateTime

Convert the Timestamp to a UtcDateTime.

# use time_macros::{timestamp, utc_datetime};
assert_eq!(timestamp!(1_546_398_245).to_utc(), utc_datetime!(2019-01-02 3:04:05));

const fn as_seconds(self) -> i64

Get the number of seconds since the Unix epoch.

Negative values represent moments before the Unix epoch.

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).as_seconds(), 1_546_398_245);

const fn as_milliseconds(self) -> i64

Get the number of milliseconds since the Unix epoch.

Negative values represent moments before the Unix epoch.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245.006).as_milliseconds(),
    1_546_398_245_006
);

const fn as_microseconds(self) -> i128

Get the number of microseconds since the Unix epoch.

Negative values represent moments before the Unix epoch.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245.006_007).as_microseconds(),
    1_546_398_245_006_007
);

const fn as_nanoseconds(self) -> i128

Get the number of nanoseconds since the Unix epoch.

Negative values represent moments before the Unix epoch.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245.006_007_008).as_nanoseconds(),
    1_546_398_245_006_007_008
);

const fn date(self) -> Date

Get the Date of the timestamp in UTC.

# use time_macros::{date, timestamp};
assert_eq!(timestamp!(1_546_398_245).date(), date!(2019-01-02));

const fn time(self) -> Time

Get the Time of the timestamp in UTC.

# use time_macros::{time, timestamp};
assert_eq!(timestamp!(1_546_398_245).time(), time!(3:04:05));

const fn year(self) -> i32

Get the year of the timestamp in UTC.

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).year(), 2019);

const fn month(self) -> Month

Get the month of the timestamp in UTC.

# use time::Month;
# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).month(), Month::January);

const fn day(self) -> u8

Get the day of the month of the timestamp in UTC.

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

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).day(), 2);

const fn ordinal(self) -> u16

Get the day of the year of the timestamp in UTC.

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

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).ordinal(), 2);

const fn iso_week(self) -> u8

Get the ISO week number of the timestamp in UTC.

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

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).iso_week(), 1);

const fn sunday_based_week(self) -> u8

Get the Sunday-based week number of the timestamp in UTC.

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

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).sunday_based_week(), 0);

const fn monday_based_week(self) -> u8

Get the Monday-based week number of the timestamp in UTC.

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

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).monday_based_week(), 0);

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

Get the calendar date (year, month, day) of the timestamp in UTC.

# use time::Month;
# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245).to_calendar_date(),
    (2019, Month::January, 2)
);

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

Get the ordinal date (year, ordinal day) of the timestamp in UTC.

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).to_ordinal_date(), (2019, 2));

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

Get the ISO week date (year, week number, weekday) of the timestamp in UTC.

# use time::Weekday;
# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245).to_iso_week_date(),
    (2019, 1, Weekday::Wednesday)
);

const fn weekday(self) -> Weekday

Get the weekday of the timestamp in UTC.

# use time::Weekday;
# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).weekday(), Weekday::Wednesday);

const fn to_julian_day(self) -> i32

Get the Julian day of the timestamp.

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).to_julian_day(), 2_458_486);

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

Get the hours, minutes, and seconds of the timestamp in UTC.

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).as_hms(), (3, 4, 5));

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

Get the hours, minutes, seconds, and milliseconds of the timestamp in UTC.

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245.006).as_hms_milli(), (3, 4, 5, 6));

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

Get the hours, minutes, seconds, and microseconds of the timestamp in UTC.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245.006_007).as_hms_micro(),
    (3, 4, 5, 6_007)
);

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

Get the hours, minutes, seconds, and nanoseconds of the timestamp in UTC.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245.006_007_008).as_hms_nano(),
    (3, 4, 5, 6_007_008)
);

const fn hour(self) -> u8

Get the hour of the timestamp in UTC.

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).hour(), 3);

const fn minute(self) -> u8

Get the minute of the timestamp in UTC.

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).minute(), 4);

const fn second(self) -> u8

Get the second of the timestamp in UTC.

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245).second(), 5);

const fn millisecond(self) -> u16

Get the millisecond of the timestamp in UTC.

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245.006).millisecond(), 6);

const fn microsecond(self) -> u32

Get the microsecond of the timestamp in UTC.

# use time_macros::timestamp;
assert_eq!(timestamp!(1_546_398_245.006_007).microsecond(), 6_007);

const fn nanosecond(self) -> u32

Get the nanosecond of the timestamp in UTC.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245.006_007_008).nanosecond(),
    6_007_008
);

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

Checked addition of a SignedDuration, returning None if the result is out of range.

# use time_macros::timestamp;
# use time::ext::NumericalDuration as _;
assert_eq!(
    timestamp!(1_546_398_245).checked_add(1.days()),
    Some(timestamp!(1_546_484_645))
);
assert_eq!(
    timestamp!(1_546_398_245).checked_add((-1).days()),
    Some(timestamp!(1_546_311_845))
);

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

Checked subtraction of a SignedDuration, returning None if the result is out of range.

# use time_macros::timestamp;
# use time::ext::NumericalDuration as _;
assert_eq!(
    timestamp!(1_546_398_245).checked_sub(1.days()),
    Some(timestamp!(1_546_311_845))
);
assert_eq!(
    timestamp!(1_546_398_245).checked_sub((-1).days()),
    Some(timestamp!(1_546_484_645))
);

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

Saturating addition of a SignedDuration.

Returns Timestamp::MAX or Timestamp::MIN if the result is out of range.

# use time::Timestamp;
# use time_macros::timestamp;
# use time::ext::NumericalDuration as _;
assert_eq!(
    timestamp!(1_546_398_245).saturating_add(1.days()),
    timestamp!(1_546_484_645)
);
assert_eq!(Timestamp::MAX.saturating_add(1.days()), Timestamp::MAX);
assert_eq!(Timestamp::MIN.saturating_add((-1).days()), Timestamp::MIN);

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

Saturating subtraction of a SignedDuration.

Returns Timestamp::MAX or Timestamp::MIN if the result is out of range.

# use time::Timestamp;
# use time_macros::timestamp;
# use time::ext::NumericalDuration as _;
assert_eq!(
    timestamp!(1_546_398_245).saturating_sub(1.days()),
    timestamp!(1_546_311_845)
);
assert_eq!(Timestamp::MIN.saturating_sub(1.days()), Timestamp::MIN);
assert_eq!(Timestamp::MAX.saturating_sub((-1).days()), Timestamp::MAX);

`impl Timestamp`

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

Replace the time, preserving the date.

# use time_macros::{time, timestamp};
assert_eq!(
    timestamp!(1_546_398_245).replace_time(time!(12:34:56)),
    timestamp!(1_546_432_496)
);

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

Replace the date, preserving the time.

# use time_macros::{date, timestamp};
assert_eq!(
    timestamp!(1_546_398_245).replace_date(date!(2020-01-02)),
    timestamp!(1_577_934_245)
);

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

Replace the year, preserving the month and day. If the date is February 29 and the resulting year is not a leap year, an error is returned.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245).replace_year(2020),
    Ok(timestamp!(1_577_934_245))
);
assert!(timestamp!(1_546_398_245).replace_year(-1_000_000).is_err()); // -1_000_000 isn't a valid year
assert!(timestamp!(1_546_398_245).replace_year(1_000_000).is_err()); // 1_000_000 isn't a valid year

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

Replace the month of the year, preserving the year and day. If the day is invalid for the resulting month, an error is returned.

# use time_macros::timestamp;
# use time::Month;
assert_eq!(
    timestamp!(1_546_398_245).replace_month(Month::February),
    Ok(timestamp!(1_549_076_645))
);
assert!(
    timestamp!(1_548_817_445)
        .replace_month(Month::February)
        .is_err()
); // the day of the month is 30, which is invalid for February

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

Replace the day of the month.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245).replace_day(1),
    Ok(timestamp!(1_546_311_845))
);
assert!(timestamp!(1_546_398_245).replace_day(0).is_err()); // 00 isn't a valid day
assert!(timestamp!(1_546_398_245).replace_day(32).is_err()); // 32 isn't a valid day

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

Replace the day of the year.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245).replace_ordinal(1),
    Ok(timestamp!(1_546_311_845))
);
assert!(timestamp!(1_546_398_245).replace_ordinal(0).is_err()); // 0 isn't a valid day of the year
assert!(timestamp!(1_546_398_245).replace_ordinal(366).is_err()); // the timestamp is in 2019, which isn't a leap year

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

Replace the clock hour.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245).replace_hour(0),
    Ok(timestamp!(1_546_387_445))
);
assert!(timestamp!(1_546_398_245).replace_hour(24).is_err()); // 24 isn't a valid hour

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

Replace the minutes within the hour.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245).replace_minute(0),
    Ok(timestamp!(1_546_398_005))
);
assert!(timestamp!(1_546_398_245).replace_minute(60).is_err()); // 60 isn't a valid minute

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

Replace the seconds within the minute.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245).replace_second(0),
    Ok(timestamp!(1_546_398_240))
);
assert!(timestamp!(1_546_398_245).replace_second(60).is_err()); // 60 isn't a valid second

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

Replace the milliseconds within the second.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245.006).replace_millisecond(7),
    Ok(timestamp!(1_546_398_245.007))
);
assert!(
    timestamp!(1_546_398_245.006)
        .replace_millisecond(1_000)
        .is_err()
); // 1_000 isn't a valid millisecond

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

Replace the microseconds within the second.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245.006_007).replace_microsecond(123_456),
    Ok(timestamp!(1_546_398_245.123_456))
);
assert!(
    timestamp!(1_546_398_245.006_007)
        .replace_microsecond(1_000_000)
        .is_err()
); // 1_000_000 isn't a valid microsecond

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

Replace the nanoseconds within the second.

# use time_macros::timestamp;
assert_eq!(
    timestamp!(1_546_398_245.006_007_008).replace_nanosecond(123_456_789),
    Ok(timestamp!(1_546_398_245.123_456_789))
);
assert!(
    timestamp!(1_546_398_245.006_007_008)
        .replace_nanosecond(1_000_000_000)
        .is_err()
); // 1_000_000_000 isn't a valid nanosecond