Struct Timestamp

Source

pub struct Timestamp { /* private fields */ }

Available on crate feature cookies only.

Expand description

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§

Source §

impl Timestamp

Source

pub const UNIX_EPOCH: Timestamp

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

Source

pub const MIN: Timestamp

The minimum valid Timestamp.

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

Source

pub const MAX: Timestamp

The maximum valid Timestamp.

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

Source

pub fn now() -> Timestamp

Available on crate feature std only.

Create a new Timestamp representing the current moment in time.

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

Source

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

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

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

Source

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

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

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

Source

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

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

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

Source

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

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

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

Source

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

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

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

Source

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

Convert the Timestamp to an OffsetDateTime at the provided offset.

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.

Source

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

assert!(
    timestamp!(1_546_398_245)
        .checked_to_offset(offset!(+1))
        .is_some()
);

Source

pub const fn to_utc(self) -> UtcDateTime

Convert the Timestamp to a UtcDateTime.

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

Source

pub const fn as_seconds(self) -> i64

Get the number of seconds since the Unix epoch.

Negative values represent moments before the Unix epoch.

assert_eq!(timestamp!(1_546_398_245).as_seconds(), 1_546_398_245);

Source

pub const fn as_milliseconds(self) -> i64

Get the number of milliseconds since the Unix epoch.

Negative values represent moments before the Unix epoch.

assert_eq!(
    timestamp!(1_546_398_245.006).as_milliseconds(),
    1_546_398_245_006
);

Source

pub const fn as_microseconds(self) -> i128

Get the number of microseconds since the Unix epoch.

Negative values represent moments before the Unix epoch.

assert_eq!(
    timestamp!(1_546_398_245.006_007).as_microseconds(),
    1_546_398_245_006_007
);

Source

pub const fn as_nanoseconds(self) -> i128

Get the number of nanoseconds since the Unix epoch.

Negative values represent moments before the Unix epoch.

assert_eq!(
    timestamp!(1_546_398_245.006_007_008).as_nanoseconds(),
    1_546_398_245_006_007_008
);

Source

pub const fn date(self) -> Date

Get the Date of the timestamp in UTC.

assert_eq!(timestamp!(1_546_398_245).date(), date!(2019-01-02));

Source

pub const fn time(self) -> Time

Get the Time of the timestamp in UTC.

assert_eq!(timestamp!(1_546_398_245).time(), time!(3:04:05));

Source

pub const fn year(self) -> i32

Get the year of the timestamp in UTC.

assert_eq!(timestamp!(1_546_398_245).year(), 2019);

Source

pub const fn month(self) -> Month

Get the month of the timestamp in UTC.

assert_eq!(timestamp!(1_546_398_245).month(), Month::January);

Source

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

assert_eq!(timestamp!(1_546_398_245).day(), 2);

Source

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

assert_eq!(timestamp!(1_546_398_245).ordinal(), 2);

Source

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

assert_eq!(timestamp!(1_546_398_245).iso_week(), 1);

Source

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

assert_eq!(timestamp!(1_546_398_245).sunday_based_week(), 0);

Source

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

assert_eq!(timestamp!(1_546_398_245).monday_based_week(), 0);

Source

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

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

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

Source

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

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

assert_eq!(timestamp!(1_546_398_245).to_ordinal_date(), (2019, 2));

Source

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

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

assert_eq!(
    timestamp!(1_546_398_245).to_iso_week_date(),
    (2019, 1, Weekday::Wednesday)
);

Source

pub const fn weekday(self) -> Weekday

Get the weekday of the timestamp in UTC.

assert_eq!(timestamp!(1_546_398_245).weekday(), Weekday::Wednesday);

Source

pub const fn to_julian_day(self) -> i32

Get the Julian day of the timestamp.

assert_eq!(timestamp!(1_546_398_245).to_julian_day(), 2_458_486);

Source

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

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

assert_eq!(timestamp!(1_546_398_245).as_hms(), (3, 4, 5));

Source

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

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

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

Source

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

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

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

Source

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

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

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

Source

pub const fn hour(self) -> u8

Get the hour of the timestamp in UTC.

assert_eq!(timestamp!(1_546_398_245).hour(), 3);

Source

pub const fn minute(self) -> u8

Get the minute of the timestamp in UTC.

assert_eq!(timestamp!(1_546_398_245).minute(), 4);

Source

pub const fn second(self) -> u8

Get the second of the timestamp in UTC.

assert_eq!(timestamp!(1_546_398_245).second(), 5);

Source

pub const fn millisecond(self) -> u16

Get the millisecond of the timestamp in UTC.

assert_eq!(timestamp!(1_546_398_245.006).millisecond(), 6);

Source

pub const fn microsecond(self) -> u32

Get the microsecond of the timestamp in UTC.

assert_eq!(timestamp!(1_546_398_245.006_007).microsecond(), 6_007);

Source

pub const fn nanosecond(self) -> u32

Get the nanosecond of the timestamp in UTC.

assert_eq!(
    timestamp!(1_546_398_245.006_007_008).nanosecond(),
    6_007_008
);

Source

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

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

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

Source

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

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

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

Source

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

Saturating addition of a SignedDuration.

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

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

Source

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

Saturating subtraction of a SignedDuration.

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

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

Source §

impl Timestamp

Methods that replace part of the Timestamp.

Source

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

Replace the time, preserving the date.

assert_eq!(
    timestamp!(1_546_398_245).replace_time(time!(12:34:56)),
    timestamp!(1_546_432_496)
);

Source

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

Replace the date, preserving the time.

assert_eq!(
    timestamp!(1_546_398_245).replace_date(date!(2020-01-02)),
    timestamp!(1_577_934_245)
);

Source

pub const fn replace_year(self, year: i32) -> Result<Timestamp, 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.

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

Source

pub const fn replace_month( self, month: Month, ) -> Result<Timestamp, 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.

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

Source

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

Replace the day of the month.

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

Source

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

Replace the day of the year.

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

Source

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

Replace the clock hour.

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

Source

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

Replace the minutes within the hour.

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

Source

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

Replace the seconds within the minute.

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

Source

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

Replace the milliseconds within the second.

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

Source

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

Replace the microseconds within the second.

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

Source

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

Replace the nanoseconds within the second.

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

Source §

impl Timestamp

Source

pub fn format_into( self, output: &mut (impl Write + ?Sized), format: &(impl Formattable + ?Sized), ) -> Result<usize, Format>

Available on crate feature formatting only.

Format the Timestamp using the provided format description.

Source

pub fn format( self, format: &(impl Formattable + ?Sized), ) -> Result<String, Format>

Available on crate feature formatting only.

Format the Timestamp using the provided format description.

let format = format_description!("[unix_timestamp]");
assert_eq!(timestamp!(1_546_398_245).format(&format)?, "1546398245");

Source §

impl Timestamp

Source

pub fn parse( input: &str, description: &(impl Parsable + ?Sized), ) -> Result<Timestamp, Parse>

Available on crate feature parsing only.

Parse a Timestamp from the input using the provided format description.

let format = format_description!("[unix_timestamp]");
assert_eq!(
    Timestamp::parse("1546398245", &format)?,
    timestamp!(1_546_398_245),
);

Source

pub fn parse_with_defaults( input: &[u8], description: &(impl Parsable + ?Sized), defaults: Parsed, ) -> Result<Timestamp, Parse>

Available on crate feature parsing only.

Parse a Timestamp from the input using the provided format description and default values.

let format = format_description!("[year]-[month]-[day]");
let defaults = Parsed::new().with_hour_24(0).expect("0 is a valid hour");
assert_eq!(
    Timestamp::parse_with_defaults(b"2020-01-02", &format, defaults)?,
    timestamp!(1_577_923_200)
);