Struct ZonedDateTime 

pub struct ZonedDateTime<A, Z>
where
    A: AsCalendar,
{
    pub date: Date<A>,
    pub time: Time,
    pub zone: Z,
}

A date and time for a given calendar, local to a specified time zone.

The primary definition of this type is in the icu_time crate. Other ICU4X crates re-export it for convenience.

This type exists as an input type for datetime formatting and should only be constructed to pass to a datetime formatter.

Semantics

This type represents the date, time, and time zone that are displayed to a user. It does not identify the absolute time that an event happens, nor does it represent the general concept of a “zoned date time”, which would require time zone and leap second information for operations like validation, arithmetic, and comparisons¹.

Hence, while this type implements PartialEq/Eq (equal ZonedDateTimes will display equally), it does not implement PartialOrd/Ord, arithmetic, and it is possible to create ZonedDateTimes that do not exist.

---

1. ZonedDateTime<UtcOffset> is an exception to this, as the whole time zone identity is part of the type, and there are no local time discontinuities. Therefore it actually identifies an absolute time and implements PartialOrd. ↩

Fields

date: Date<A>

The date, local to the time zone

time: Time

The time, local to the time zone

zone: Z

The time zone

Implementations

impl<A> ZonedDateTime<A, UtcOffset>

where A: AsCalendar,

pub fn try_offset_only_from_str( rfc_9557_str: &str, calendar: A, ) -> Result<ZonedDateTime<A, UtcOffset>, ParseError>

Create a ZonedDateTime in any calendar from an RFC 9557 string.

Returns an error if the string has a calendar annotation that does not match the calendar argument.

This function is “strict”: the string should have only an offset and no named time zone.

pub fn try_offset_only_from_utf8( rfc_9557_str: &[u8], calendar: A, ) -> Result<ZonedDateTime<A, UtcOffset>, ParseError>

Create a ZonedDateTime in any calendar from RFC 9557 syntax UTF-8 bytes.

See Self:try_offset_only_from_str.

impl<A> ZonedDateTime<A, TimeZoneInfo<AtTime>>

where A: AsCalendar,

pub fn try_location_only_from_str( rfc_9557_str: &str, calendar: A, iana_parser: IanaParserBorrowed<'_>, ) -> Result<ZonedDateTime<A, TimeZoneInfo<AtTime>>, ParseError>

Create a ZonedDateTime in any calendar from an RFC 9557 string.

Returns an error if the string has a calendar annotation that does not match the calendar argument.

This function is “strict”: the string should have only a named time zone and no offset.

pub fn try_location_only_from_utf8( rfc_9557_str: &[u8], calendar: A, iana_parser: IanaParserBorrowed<'_>, ) -> Result<ZonedDateTime<A, TimeZoneInfo<AtTime>>, ParseError>

Create a ZonedDateTime in any calendar from RFC 9557 UTF-8 bytes.

See Self::try_location_only_from_str.

pub fn try_lenient_from_str( rfc_9557_str: &str, calendar: A, iana_parser: IanaParserBorrowed<'_>, ) -> Result<ZonedDateTime<A, TimeZoneInfo<AtTime>>, ParseError>

Create a ZonedDateTime in any calendar from an RFC 9557 string.

Returns an error if the string has a calendar annotation that does not match the calendar argument.

This function is “lenient”: the string can have an offset, and named time zone, both, or neither. If the named time zone is missing, it is returned as Etc/Unknown.

pub fn try_lenient_from_utf8( rfc_9557_str: &[u8], calendar: A, iana_parser: IanaParserBorrowed<'_>, ) -> Result<ZonedDateTime<A, TimeZoneInfo<AtTime>>, ParseError>

Create a ZonedDateTime in any calendar from RFC 9557 UTF-8 bytes.

See Self::try_lenient_from_str.

pub fn try_strict_from_str( rfc_9557_str: &str, calendar: A, iana_parser: IanaParserBorrowed<'_>, ) -> Result<ZonedDateTime<A, TimeZoneInfo<AtTime>>, ParseError>

Create a ZonedDateTime in any calendar from an RFC 9557 string.

Returns an error if the string has a calendar annotation that does not match the calendar argument.

The string should have both an offset and a named time zone.

For more information on RFC 9557, see the ixdtf crate.

Examples

Basic usage:

use icu::calendar::cal::Hebrew;
use icu::locale::subtags::subtag;
use icu::time::{
    zone::{IanaParser, TimeZoneVariant, UtcOffset},
    TimeZone, TimeZoneInfo, ZonedDateTime,
};

let zoneddatetime = ZonedDateTime::try_strict_from_str(
    "2024-08-08T12:08:19-05:00[America/Chicago][u-ca=hebrew]",
    Hebrew,
    IanaParser::new(),
)
.unwrap();

assert_eq!(zoneddatetime.date.year().extended_year(), 5784);
assert_eq!(
    zoneddatetime.date.month().to_input().code(),
    icu::calendar::types::MonthCode(tinystr::tinystr!(4, "M11"))
);
assert_eq!(zoneddatetime.date.day_of_month().0, 4);

assert_eq!(zoneddatetime.time.hour.number(), 12);
assert_eq!(zoneddatetime.time.minute.number(), 8);
assert_eq!(zoneddatetime.time.second.number(), 19);
assert_eq!(zoneddatetime.time.subsecond.number(), 0);
assert_eq!(
    zoneddatetime.zone.id(),
    TimeZone::from_iana_id("America/Chicago")
);
assert_eq!(
    zoneddatetime.zone.offset(),
    Some(UtcOffset::try_from_seconds(-5 * 3600).unwrap())
);
let _ = zoneddatetime.zone.zone_name_timestamp();

An RFC 9557 string can provide a time zone in two parts: the DateTime UTC Offset or the Time Zone Annotation. A DateTime UTC Offset is the time offset as laid out by RFC 3339; meanwhile, the Time Zone Annotation is the annotation laid out by RFC 9557 and is defined as a UTC offset or IANA Time Zone identifier.

DateTime UTC Offsets

Below is an example of a time zone from a DateTime UTC Offset. The syntax here is familiar to a RFC 3339 DateTime string.

use icu::calendar::Iso;
use icu::time::{zone::UtcOffset, TimeZoneInfo, ZonedDateTime};

let tz_from_offset = ZonedDateTime::try_offset_only_from_str(
    "2024-08-08T12:08:19-05:00",
    Iso,
)
.unwrap();

assert_eq!(
    tz_from_offset.zone,
    UtcOffset::try_from_seconds(-5 * 3600).unwrap()
);

Time Zone Annotations

Below is an example of a time zone being provided by a time zone annotation.

use icu::calendar::Iso;
use icu::locale::subtags::subtag;
use icu::time::{
    zone::{IanaParser, TimeZoneVariant, UtcOffset},
    TimeZone, TimeZoneInfo, ZonedDateTime,
};

let tz_from_offset_annotation = ZonedDateTime::try_offset_only_from_str(
    "2024-08-08T12:08:19[-05:00]",
    Iso,
)
.unwrap();
let tz_from_iana_annotation = ZonedDateTime::try_location_only_from_str(
    "2024-08-08T12:08:19[America/Chicago]",
    Iso,
    IanaParser::new(),
)
.unwrap();

assert_eq!(
    tz_from_offset_annotation.zone,
    UtcOffset::try_from_seconds(-5 * 3600).unwrap()
);

assert_eq!(
    tz_from_iana_annotation.zone.id(),
    TimeZone(subtag!("uschi"))
);
assert_eq!(tz_from_iana_annotation.zone.offset(), None);

UTC Offset and time zone annotations.

An RFC 9557 string may contain both a UTC Offset and time zone annotation. This is fine as long as the time zone parts can be deemed as inconsistent or unknown consistency.

DateTime UTC offset with UTC Offset annotation.

These annotations must always be consistent as they should be either the same value or are inconsistent.

use icu::calendar::Iso;
use icu::time::{
    zone::UtcOffset, ParseError, TimeZone, TimeZoneInfo, ZonedDateTime,
};
use tinystr::tinystr;

let consistent_tz_from_both = ZonedDateTime::try_offset_only_from_str(
    "2024-08-08T12:08:19-05:00[-05:00]",
    Iso,
)
.unwrap();

assert_eq!(
    consistent_tz_from_both.zone,
    UtcOffset::try_from_seconds(-5 * 3600).unwrap()
);

let inconsistent_tz_from_both = ZonedDateTime::try_offset_only_from_str(
    "2024-08-08T12:08:19-05:00[+05:00]",
    Iso,
);

assert!(matches!(
    inconsistent_tz_from_both,
    Err(ParseError::InconsistentTimeUtcOffsets)
));

pub fn try_strict_from_utf8( rfc_9557_str: &[u8], calendar: A, iana_parser: IanaParserBorrowed<'_>, ) -> Result<ZonedDateTime<A, TimeZoneInfo<AtTime>>, ParseError>

Create a ZonedDateTime in any calendar from RFC 9557 UTF-8 bytes.

See Self::try_strict_from_str.

impl<A> ZonedDateTime<A, TimeZoneInfo<Full>>

where A: AsCalendar,

pub fn try_full_from_str( rfc_9557_str: &str, calendar: A, iana_parser: IanaParserBorrowed<'_>, offset_calculator: VariantOffsetsCalculatorBorrowed<'_>, ) -> Result<ZonedDateTime<A, TimeZoneInfo<Full>>, ParseError>

👎Deprecated since 2.1.0:

use try_strict_from_str

Create a ZonedDateTime in any calendar from an RFC 9557 string.

pub fn try_full_from_utf8( rfc_9557_str: &[u8], calendar: A, iana_parser: IanaParserBorrowed<'_>, offset_calculator: VariantOffsetsCalculatorBorrowed<'_>, ) -> Result<ZonedDateTime<A, TimeZoneInfo<Full>>, ParseError>

👎Deprecated since 2.1.0:

use try_strict_from_utf8

Create a ZonedDateTime in any calendar from RFC 9557 UTF-8 bytes.

See Self::try_full_from_str.

impl ZonedDateTime<Iso, UtcOffset>

pub fn from_epoch_milliseconds_and_utc_offset( epoch_milliseconds: i64, utc_offset: UtcOffset, ) -> ZonedDateTime<Iso, UtcOffset>

Creates a ZonedDateTime from an absolute time, in milliseconds since the UNIX Epoch, and a UTC offset.

This constructor returns a ZonedDateTime that supports only the localized offset time zone style.

Examples

use icu::calendar::cal::Iso;
use icu::time::zone::UtcOffset;
use icu::time::ZonedDateTime;

let iso_str = "2025-04-30T17:45-0700";
let timestamp = 1746060300000; // milliseconds since UNIX epoch
let offset: UtcOffset = "-0700".parse().unwrap();

let zdt_from_timestamp =
    ZonedDateTime::from_epoch_milliseconds_and_utc_offset(
        timestamp, offset,
    );

// Check that it equals the same as the parse result:
let zdt_from_str =
    ZonedDateTime::try_offset_only_from_str(iso_str, Iso).unwrap();
assert_eq!(zdt_from_timestamp, zdt_from_str);

Negative timestamps are supported:

use icu::calendar::cal::Iso;
use icu::time::zone::UtcOffset;
use icu::time::ZonedDateTime;

let iso_str = "1920-01-02T03:04:05.250+0600";
let timestamp = -1577847354750; // milliseconds since UNIX epoch
let offset: UtcOffset = "+0600".parse().unwrap();

let zdt_from_timestamp =
    ZonedDateTime::from_epoch_milliseconds_and_utc_offset(
        timestamp, offset,
    );

// Check that it equals the same as the parse result:
let zdt_from_str =
    ZonedDateTime::try_offset_only_from_str(iso_str, Iso).unwrap();
assert_eq!(zdt_from_timestamp, zdt_from_str);

When epoch milliseconds exceed the representable date range, the date component saturates to the maximum or minimum representable date in the ISO calendar

use icu::calendar::cal::Iso;
use icu::time::zone::UtcOffset;
use icu::time::ZonedDateTime;

let max_offset = UtcOffset::try_from_seconds(14 * 3600).unwrap();
let zdt_max = ZonedDateTime::from_epoch_milliseconds_and_utc_offset(
    i64::MAX,
    max_offset,
);

let min_offset = UtcOffset::try_from_seconds(-12 * 3600).unwrap();
let zdt_min = ZonedDateTime::from_epoch_milliseconds_and_utc_offset(
    i64::MIN,
    min_offset,
);

Trait Implementations

impl<A, Z> Clone for ZonedDateTime<A, Z>

where A: AsCalendar, Date<A>: Clone, Z: Clone,

fn clone(&self) -> ZonedDateTime<A, Z>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<C: IntoAnyCalendar, A: AsCalendar<Calendar = C>, Z: Copy> ConvertCalendar for ZonedDateTime<A, Z>

type Converted<'a> = ZonedDateTime<Ref<'a, AnyCalendar>, Z>

The converted type. This can be the same as the receiver type.

fn to_calendar<'a>(&self, calendar: &'a AnyCalendar) -> Self::Converted<'a>

Converts self to the specified AnyCalendar.

impl<A, Z> Debug for ZonedDateTime<A, Z>

where A: Debug + AsCalendar, Z: Debug,

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

Formats the value using the given formatter.

impl<Tz> From<&DateTime<Tz>> for ZonedDateTime<Gregorian, TimeZoneInfo<AtTime>>

where Tz: TimeZone, TimeZone: From<Tz>,

fn from(chrono: &DateTime<Tz>) -> ZonedDateTime<Gregorian, TimeZoneInfo<AtTime>>

Converts to this type from the input type.

impl<Tz> From<&DateTime<Tz>> for ZonedDateTime<Gregorian, TimeZoneInfo<Base>>

where Tz: TimeZone, TimeZone: From<Tz>,

fn from(chrono: &DateTime<Tz>) -> ZonedDateTime<Gregorian, TimeZoneInfo<Base>>

Converts to this type from the input type.

impl From<&OffsetDateTime> for ZonedDateTime<Gregorian, UtcOffset>

fn from(other: &OffsetDateTime) -> ZonedDateTime<Gregorian, UtcOffset>

Converts to this type from the input type.

impl From<&Zoned> for ZonedDateTime<Gregorian, TimeZoneInfo<AtTime>>

Available on crate feature compiled_data only.

fn from(jiff: &Zoned) -> ZonedDateTime<Gregorian, TimeZoneInfo<AtTime>>

Converts to this type from the input type.

impl From<&Zoned> for ZonedDateTime<Gregorian, TimeZoneInfo<Base>>

Available on crate feature compiled_data only.

fn from(jiff: &Zoned) -> ZonedDateTime<Gregorian, TimeZoneInfo<Base>>

Converts to this type from the input type.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<()> for ZonedDateTime<A, Z>

fn get_field(&self)

Returns the value of this trait’s field T.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<DayOfMonth> for ZonedDateTime<A, Z>

fn get_field(&self) -> DayOfMonth

Returns the value of this trait’s field T.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<DayOfYear> for ZonedDateTime<A, Z>

fn get_field(&self) -> DayOfYear

Returns the value of this trait’s field T.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<Hour> for ZonedDateTime<A, Z>

fn get_field(&self) -> Hour

Returns the value of this trait’s field T.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<Minute> for ZonedDateTime<A, Z>

fn get_field(&self) -> Minute

Returns the value of this trait’s field T.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<MonthInfo> for ZonedDateTime<A, Z>

fn get_field(&self) -> MonthInfo

Returns the value of this trait’s field T.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<Nanosecond> for ZonedDateTime<A, Z>

fn get_field(&self) -> Nanosecond

Returns the value of this trait’s field T.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<Option<UtcOffset>> for ZonedDateTime<A, Z>

where Z: GetField<Option<UtcOffset>>,

fn get_field(&self) -> Option<UtcOffset>

Returns the value of this trait’s field T.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<RataDie> for ZonedDateTime<A, Z>

fn get_field(&self) -> RataDie

Returns the value of this trait’s field T.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<Second> for ZonedDateTime<A, Z>

fn get_field(&self) -> Second

Returns the value of this trait’s field T.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<TimeZone> for ZonedDateTime<A, Z>

where Z: GetField<TimeZone>,

fn get_field(&self) -> TimeZone

Returns the value of this trait’s field T.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<Weekday> for ZonedDateTime<A, Z>

fn get_field(&self) -> Weekday

Returns the value of this trait’s field T.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<YearInfo> for ZonedDateTime<A, Z>

fn get_field(&self) -> YearInfo

Returns the value of this trait’s field T.

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> GetField<ZoneNameTimestamp> for ZonedDateTime<A, Z>

where Z: GetField<ZoneNameTimestamp>,

fn get_field(&self) -> ZoneNameTimestamp

Returns the value of this trait’s field T.

impl<C: IntoAnyCalendar, A: AsCalendar<Calendar = C>, Z> InSameCalendar for ZonedDateTime<A, Z>

fn check_any_calendar_kind( &self, any_calendar_kind: AnyCalendarKind, ) -> Result<(), MismatchedCalendarError>

Checks whether this type is compatible with the given calendar.

impl<A> Ord for ZonedDateTime<A, UtcOffset>

where A: AsCalendar,

fn cmp(&self, other: &ZonedDateTime<A, UtcOffset>) -> Ordering

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized,

Restrict a value to a certain interval.

impl<A, B, Y, Z> PartialEq<ZonedDateTime<B, Z>> for ZonedDateTime<A, Y>

where A: AsCalendar, B: AsCalendar, Date<A>: PartialEq<Date<B>>, Y: PartialEq<Z>,

fn eq(&self, other: &ZonedDateTime<B, Z>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A> PartialOrd for ZonedDateTime<A, UtcOffset>

where A: AsCalendar, Date<A>: PartialEq,

fn partial_cmp(&self, other: &ZonedDateTime<A, UtcOffset>) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl<A, Z> Copy for ZonedDateTime<A, Z>

where A: AsCalendar, Date<A>: Copy, Z: Copy,

impl<A, Z> Eq for ZonedDateTime<A, Z>

where A: AsCalendar, Date<A>: Eq, Z: Eq,

impl<C: CldrCalendar, A: AsCalendar<Calendar = C>, Z> InFixedCalendar<C> for ZonedDateTime<A, Z>

impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> UnstableSealed for ZonedDateTime<A, Z>