logo
pub struct OffsetDateTime { /* private fields */ }
Expand description

A PrimitiveDateTime with a UtcOffset.

All comparisons are performed using the UTC time.

Implementations

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

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

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

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

Midnight, 1 January, 1970 (UTC).

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods that allow formatting the OffsetDateTime.

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

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

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

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Formats the value using the given formatter. Read more

Performs the conversion.

Performs the conversion.

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

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

This method tests for !=.

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

This method tests for !=.

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

This method tests for !=.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The resulting type after applying the - operator.

Performs the - operation. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

Performs the -= operation. Read more

Performs the -= operation. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.