Struct time::OffsetDateTime

pub struct OffsetDateTime { /* fields omitted */ }

A PrimitiveDateTime with a UtcOffset.

All comparisons are performed using the UTC time.

Implementations

impl OffsetDateTime

pub fn now() -> Self

👎 Deprecated since 0.2.11:

This function returns a value with an offset of UTC, which is not apparent from its name alone. You should use OffsetDateTime::now_utc() instead.

Create a new OffsetDateTime with the current date and time in UTC.

assert!(OffsetDateTime::now().year() >= 2019);
assert_eq!(OffsetDateTime::now().offset(), offset!(UTC));

pub fn now_utc() -> Self

Create a new OffsetDateTime with the current date and time in UTC.

assert!(OffsetDateTime::now_utc().year() >= 2019);
assert_eq!(OffsetDateTime::now_utc().offset(), offset!(UTC));

pub fn now_local() -> Self

👎 Deprecated since 0.2.23:

UTC is returned if the local offset cannot be determined

Create a new OffsetDateTime with the current date and time in the local offset.

assert!(OffsetDateTime::now_local().year() >= 2019);

pub fn try_now_local() -> Result<Self, IndeterminateOffset>

Attempt to create a new OffsetDateTime with the current date and time in the local offset. If the offset cannot be determined, an error is returned.

let now = OffsetDateTime::try_now_local();
assert!(now.is_ok());

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

Convert the OffsetDateTime from the current UtcOffset to the provided UtcOffset.

assert_eq!(
    date!(2000-01-01)
        .midnight()
        .assume_utc()
        .to_offset(offset!(-1))
        .year(),
    1999,
);

// Let's see what time Sydney's new year's celebration is in New York
// and Los Angeles.

// Construct midnight on new year's in Sydney. This is equivalent to
// 13:00 UTC.
let sydney = date!(2000-01-01).midnight().assume_offset(offset!(+11));
let new_york = sydney.to_offset(offset!(-5));
let los_angeles = sydney.to_offset(offset!(-8));
assert_eq!(sydney.hour(), 0);
assert_eq!(new_york.hour(), 8);
assert_eq!(los_angeles.hour(), 5);

pub const fn unix_epoch() -> Self

Midnight, 1 January, 1970 (UTC).

assert_eq!(
    OffsetDateTime::unix_epoch(),
    date!(1970-01-01)
        .midnight()
        .assume_utc(),
);

pub fn from_unix_timestamp(timestamp: i64) -> Self

Create an OffsetDateTime from the provided Unix timestamp.

assert_eq!(
    OffsetDateTime::from_unix_timestamp(0),
    OffsetDateTime::unix_epoch(),
);
assert_eq!(
    OffsetDateTime::from_unix_timestamp(1_546_300_800),
    date!(2019-01-01)
        .midnight()
        .assume_utc(),
);

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

let (timestamp, nanos) = (1, 500_000_000);
assert_eq!(
    OffsetDateTime::from_unix_timestamp(timestamp) + Duration::nanoseconds(nanos),
    OffsetDateTime::unix_epoch() + 1.5.seconds()
);

pub fn from_unix_timestamp_nanos(timestamp: i128) -> Self

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

assert_eq!(
    OffsetDateTime::from_unix_timestamp_nanos(0),
    OffsetDateTime::unix_epoch(),
);
assert_eq!(
    OffsetDateTime::from_unix_timestamp_nanos(1_546_300_800_000_000_000),
    date!(2019-01-01)
        .midnight()
        .assume_utc(),
);

Note that the range of timestamps possible here is far larger than the valid range of dates storable in this crate. It is the user’s responsibility to ensure the timestamp provided as a parameter is valid. No behavior is guaranteed if this parameter would not result in a valid value.

pub const fn offset(self) -> UtcOffset

Get the UtcOffset.

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .offset(),
    offset!(UTC),
);
assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_offset(offset!(+1))
        .offset(),
    offset!(+1),
);

pub fn unix_timestamp(self) -> i64

Get the Unix timestamp.

assert_eq!(
    date!(1970-01-01)
        .midnight()
        .assume_utc()
        .unix_timestamp(),
    0,
);
assert_eq!(
    date!(1970-01-01)
        .midnight()
        .assume_utc()
        .to_offset(offset!(-1))
        .unix_timestamp(),
    0,
);

pub fn timestamp(self) -> i64

👎 Deprecated since 0.2.23:

Use OffsetDateTime::unix_timestamp instead

Get the Unix timestamp.

assert_eq!(
    date!(1970-01-01)
        .midnight()
        .assume_utc()
        .timestamp(),
    0,
);
assert_eq!(
    date!(1970-01-01)
        .midnight()
        .assume_utc()
        .to_offset(offset!(-1))
        .timestamp(),
    0,
);

pub fn unix_timestamp_nanos(self) -> i128

Get the Unix timestamp in nanoseconds.

use time::{date, offset, time};
assert_eq!(
    date!(1970-01-01)
        .midnight()
        .assume_utc()
        .unix_timestamp_nanos(),
    0,
);
assert_eq!(
    date!(1970-01-01)
        .with_time(time!(1:00))
        .assume_utc()
        .to_offset(offset!(-1))
        .unix_timestamp_nanos(),
    3_600_000_000_000,
);

pub fn timestamp_nanos(self) -> i128

👎 Deprecated since 0.2.23:

Use OffsetDateTime::unix_timestamp_nanos instead

Get the Unix timestamp in nanoseconds.

use time::{date, offset, time};
assert_eq!(
    date!(1970-01-01)
        .midnight()
        .assume_utc()
        .unix_timestamp_nanos(),
    0,
);
assert_eq!(
    date!(1970-01-01)
        .with_time(time!(1:00))
        .assume_utc()
        .to_offset(offset!(-1))
        .unix_timestamp_nanos(),
    3_600_000_000_000,
);

pub fn date(self) -> Date

Get the Date in the stored offset.

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .date(),
    date!(2019-01-01),
);
assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .to_offset(offset!(-1))
        .date(),
    date!(2018-12-31),
);

pub fn time(self) -> Time

Get the Time in the stored offset.

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .time(),
    time!(0:00)
);
assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .to_offset(offset!(-1))
        .time(),
    time!(23:00)
);

pub fn year(self) -> i32

Get the year of the date in the stored offset.

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .year(),
    2019,
);
assert_eq!(
    date!(2019-12-31)
        .with_time(time!(23:00))
        .assume_utc()
        .to_offset(offset!(+1))
        .year(),
    2020,
);
assert_eq!(
    date!(2020-01-01)
        .midnight()
        .assume_utc()
        .year(),
    2020,
);

pub fn month(self) -> u8

Get the month of the date in the stored offset. If fetching both the month and day, it is more efficient to use OffsetDateTime::month_day.

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

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .month(),
    1,
);
assert_eq!(
    date!(2019-12-31)
        .with_time(time!(23:00))
        .assume_utc()
        .to_offset(offset!(+1))
        .month(),
    1,
);

pub fn day(self) -> u8

Get the day of the date in the stored offset. If fetching both the month and day, it is more efficient to use OffsetDateTime::month_day.

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

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .day(),
    1,
);
assert_eq!(
    date!(2019-12-31)
        .with_time(time!(23:00))
        .assume_utc()
        .to_offset(offset!(+1))
        .day(),
    1,
);

pub fn month_day(self) -> (u8, u8)

Get the month and day of the date in the stored offset.

The month component will always be in the range 1..=12; the day component in 1..=31.

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .month_day(),
    (1, 1),
);
assert_eq!(
    date!(2019-12-31)
        .with_time(time!(23:00))
        .assume_utc()
        .to_offset(offset!(+1))
        .month_day(),
    (1, 1),
);

pub fn ordinal(self) -> u16

Get the day of the year of the date in the stored offset.

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

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .ordinal(),
    1,
);
assert_eq!(
    date!(2019-12-31)
        .with_time(time!(23:00))
        .assume_utc()
        .to_offset(offset!(+1))
        .ordinal(),
    1,
);

pub fn iso_year_week(self) -> (i32, u8)

Get the ISO 8601 year and week number in the stored offset.

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .iso_year_week(),
    (2019, 1),
);
assert_eq!(
    date!(2019-10-04)
        .midnight()
        .assume_utc()
        .iso_year_week(),
    (2019, 40),
);
assert_eq!(
    date!(2020-01-01)
        .midnight()
        .assume_utc()
        .iso_year_week(),
    (2020, 1),
);
assert_eq!(
    date!(2020-12-31)
        .midnight()
        .assume_utc()
        .iso_year_week(),
    (2020, 53),
);
assert_eq!(
    date!(2021-01-01)
        .midnight()
        .assume_utc()
        .iso_year_week(),
    (2020, 53),
);

pub fn week(self) -> u8

Get the ISO week number of the date in the stored offset.

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

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .week(),
    1,
);
assert_eq!(
    date!(2020-01-01)
        .midnight()
        .assume_utc()
        .week(),
    1,
);
assert_eq!(
    date!(2020-12-31)
        .midnight()
        .assume_utc()
        .week(),
    53,
);
assert_eq!(
    date!(2021-01-01)
        .midnight()
        .assume_utc()
        .week(),
    53,
);

pub fn weekday(self) -> Weekday

Get the weekday of the date in the stored offset.

This current uses Zeller’s congruence internally.

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .weekday(),
    Tuesday,
);
assert_eq!(
    date!(2019-02-01)
        .midnight()
        .assume_utc()
        .weekday(),
    Friday,
);
assert_eq!(
    date!(2019-03-01)
        .midnight()
        .assume_utc()
        .weekday(),
    Friday,
);

pub fn hour(self) -> u8

Get the clock hour in the stored offset.

The returned value will always be in the range 0..24.

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .hour(),
    0,
);
assert_eq!(
    date!(2019-01-01)
        .with_time(time!(23:59:59))
        .assume_utc()
        .to_offset(offset!(-2))
        .hour(),
    21,
);

pub fn minute(self) -> u8

Get the minute within the hour in the stored offset.

The returned value will always be in the range 0..60.

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .minute(),
    0,
);
assert_eq!(
    date!(2019-01-01)
        .with_time(time!(23:59:59))
        .assume_utc()
        .to_offset(offset!(+0:30))
        .minute(),
    29,
);

pub fn second(self) -> u8

Get the second within the minute in the stored offset.

The returned value will always be in the range 0..60.

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .second(),
    0,
);
assert_eq!(
    date!(2019-01-01)
        .with_time(time!(23:59:59))
        .assume_utc()
        .to_offset(offset!(+0:00:30))
        .second(),
    29,
);

pub fn millisecond(self) -> u16

Get the milliseconds within the second in the stored offset.

The returned value will always be in the range 0..1_000.

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .millisecond(),
    0,
);
assert_eq!(
    date!(2019-01-01)
        .with_time(time!(23:59:59.999))
        .assume_utc()
        .millisecond(),
    999,
);

pub fn microsecond(self) -> u32

Get the microseconds within the second in the stored offset.

The returned value will always be in the range 0..1_000_000.

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .microsecond(),
    0,
);
assert_eq!(
    date!(2019-01-01)
        .with_time(time!(23:59:59.999_999))
        .assume_utc()
        .microsecond(),
    999_999,
);

pub fn nanosecond(self) -> u32

Get the nanoseconds within the second in the stored offset.

The returned value will always be in the range 0..1_000_000_000.

assert_eq!(
    date!(2019-01-01)
        .midnight()
        .assume_utc()
        .nanosecond(),
    0,
);
assert_eq!(
    date!(2019-01-01)
        .with_time(time!(23:59:59.999_999_999))
        .assume_utc()
        .nanosecond(),
    999_999_999,
);

impl OffsetDateTime

Methods that allow formatting the OffsetDateTime.

pub fn format(self, format: impl Into<Format>) -> String

Format the OffsetDateTime using the provided string.

assert_eq!(
    date!(2019-01-02)
        .midnight()
        .assume_utc()
        .format("%F %r %z"),
    "2019-01-02 12:00:00 am +0000",
);

pub fn lazy_format(self, format: impl Into<Format>) -> impl Display

Format the OffsetDateTime using the provided string.

assert_eq!(
    date!(2019-01-02)
        .midnight()
        .assume_utc()
        .lazy_format("%F %r %z")
        .to_string(),
    "2019-01-02 12:00:00 am +0000",
);

pub fn parse(
    s: impl AsRef<str>,
    format: impl Into<Format>
) -> Result<Self, Error>

Attempt to parse an OffsetDateTime using the provided string.

assert_eq!(
    OffsetDateTime::parse("2019-01-02 00:00:00 +0000", "%F %T %z"),
    Ok(date!(2019-01-02).midnight().assume_utc()),
);
assert_eq!(
    OffsetDateTime::parse("2019-002 23:59:59 +0000", "%Y-%j %T %z"),
    Ok(date!(2019-002).with_time(time!(23:59:59)).assume_utc()),
);
assert_eq!(
    OffsetDateTime::parse("2019-W01-3 12:00:00 pm +0000", "%G-W%V-%u %r %z"),
    Ok(date!(2019-W01-3).with_time(time!(12:00)).assume_utc()),
);

Trait Implementations

impl Add<Duration> for OffsetDateTime

type Output = Self

The resulting type after applying the + operator.

fn add(self, duration: Duration) -> Self::Output

Performs the + operation.

impl Add<Duration> for OffsetDateTime

type Output = Self

The resulting type after applying the + operator.

fn add(self, duration: StdDuration) -> Self::Output

Performs the + operation.

impl AddAssign<Duration> for OffsetDateTime

fn add_assign(&mut self, duration: Duration)

Performs the += operation.

impl AddAssign<Duration> for OffsetDateTime

fn add_assign(&mut self, duration: StdDuration)

Performs the += operation.

impl Clone for OffsetDateTime

fn clone(&self) -> OffsetDateTime

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for OffsetDateTime

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for OffsetDateTime

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<OffsetDateTime> for SystemTime

fn from(datetime: OffsetDateTime) -> Self

Performs the conversion.

impl From<SystemTime> for OffsetDateTime

fn from(system_time: SystemTime) -> Self

Performs the conversion.

impl Hash for OffsetDateTime

fn hash<H: Hasher>(&self, hasher: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Ord for OffsetDateTime

fn cmp(&self, rhs: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<OffsetDateTime> for OffsetDateTime

fn eq(&self, rhs: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<OffsetDateTime> for SystemTime

fn eq(&self, rhs: &OffsetDateTime) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<SystemTime> for OffsetDateTime

fn eq(&self, rhs: &SystemTime) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialOrd<OffsetDateTime> for OffsetDateTime

fn partial_cmp(&self, rhs: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<OffsetDateTime> for SystemTime

fn partial_cmp(&self, other: &OffsetDateTime) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<SystemTime> for OffsetDateTime

fn partial_cmp(&self, other: &SystemTime) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Sub<Duration> for OffsetDateTime

type Output = Self

The resulting type after applying the - operator.

fn sub(self, duration: Duration) -> Self::Output

Performs the - operation.

impl Sub<Duration> for OffsetDateTime

type Output = Self

The resulting type after applying the - operator.

fn sub(self, duration: StdDuration) -> Self::Output

Performs the - operation.

impl Sub<OffsetDateTime> for OffsetDateTime

type Output = Duration

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self::Output

Performs the - operation.

impl Sub<OffsetDateTime> for SystemTime

type Output = Duration

The resulting type after applying the - operator.

fn sub(self, rhs: OffsetDateTime) -> Self::Output

Performs the - operation.

impl Sub<SystemTime> for OffsetDateTime

type Output = Duration

The resulting type after applying the - operator.

fn sub(self, rhs: SystemTime) -> Self::Output

Performs the - operation.

impl SubAssign<Duration> for OffsetDateTime

fn sub_assign(&mut self, duration: Duration)

Performs the -= operation.

impl SubAssign<Duration> for OffsetDateTime

fn sub_assign(&mut self, duration: StdDuration)

Performs the -= operation.

impl Copy for OffsetDateTime

impl Eq for OffsetDateTime

impl StructuralEq for OffsetDateTime