Struct icu_timezone::IxdtfParser

pub struct IxdtfParser { /* private fields */ }

✨ Enabled with the ixdtf Cargo feature.

Implementations

impl IxdtfParser

pub fn new() -> Self

Creates a new IxdtfParser from compiled data.

pub fn try_new_with_any_provider( provider: &(impl AnyProvider + ?Sized), ) -> Result<Self, DataError>

A version of [Self :: new] that uses custom data provided by an AnyProvider.

📚 Help choosing a constructor

pub fn try_new_with_buffer_provider( provider: &(impl BufferProvider + ?Sized), ) -> Result<Self, DataError>

A version of [Self :: new] that uses custom data provided by a BufferProvider.

✨ Enabled with the serde feature.

📚 Help choosing a constructor

pub fn try_new_unstable<P>(provider: &P) -> Result<Self, DataError>

where P: ?Sized + DataProvider<ZoneOffsetPeriodV1Marker> + DataProvider<IanaToBcp47MapV3Marker>,

A version of Self::new that uses custom data provided by a DataProvider.

📚 Help choosing a constructor

⚠️ The bounds on provider may change over time, including in SemVer minor releases.

impl IxdtfParser

pub fn try_offset_only_iso_from_str( &self, ixdtf_str: &str, ) -> Result<CustomZonedDateTime<Iso, UtcOffset>, ParseError>

Create a CustomZonedDateTime in ISO-8601 calendar from an IXDTF syntax string.

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

pub fn try_offset_only_iso_from_utf8( &self, ixdtf_str: &[u8], ) -> Result<CustomZonedDateTime<Iso, UtcOffset>, ParseError>

Create a CustomZonedDateTime in ISO-8601 calendar from IXDTF syntax UTF-8 bytes.

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

pub fn try_location_only_iso_from_str( &self, ixdtf_str: &str, ) -> Result<CustomZonedDateTime<Iso, TimeZoneInfo<AtTime>>, ParseError>

Create a CustomZonedDateTime in ISO-8601 calendar from an IXDTF syntax string.

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

pub fn try_location_only_iso_from_utf8( &self, ixdtf_str: &[u8], ) -> Result<CustomZonedDateTime<Iso, TimeZoneInfo<AtTime>>, ParseError>

Create a CustomZonedDateTime in ISO-8601 calendar from IXDTF syntax UTF-8 bytes.

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

pub fn try_loose_iso_from_str( &self, ixdtf_str: &str, ) -> Result<CustomZonedDateTime<Iso, TimeZoneInfo<AtTime>>, ParseError>

Create a CustomZonedDateTime in ISO-8601 calendar from an IXDTF syntax string.

This function is “loose”: 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.

The zone variant is not calculated with this function. If you need it, use Self::try_iso_from_str.

pub fn try_loose_iso_from_utf8( &self, ixdtf_str: &[u8], ) -> Result<CustomZonedDateTime<Iso, TimeZoneInfo<AtTime>>, ParseError>

Create a CustomZonedDateTime in ISO-8601 calendar from IXDTF syntax UTF-8 bytes.

This function is “loose”: 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.

The zone variant is not calculated with this function. If you need it, use Self::try_iso_from_utf8.

pub fn try_iso_from_str( &self, ixdtf_str: &str, ) -> Result<CustomZonedDateTime<Iso, TimeZoneInfo<Full>>, ParseError>

Create a CustomZonedDateTime in ISO-8601 calendar from an IXDTF syntax string.

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

use icu_timezone::{
    IxdtfParser, TimeZoneBcp47Id, TimeZoneInfo, UtcOffset, ZoneVariant,
};
use tinystr::tinystr;

let zoneddatetime = IxdtfParser::new()
    .try_iso_from_str("2024-08-08T12:08:19-05:00[America/Chicago]")
    .unwrap();

assert_eq!(zoneddatetime.date.year().extended_year, 2024);
assert_eq!(
    zoneddatetime.date.month().standard_code,
    icu::calendar::types::MonthCode(tinystr::tinystr!(4, "M08"))
);
assert_eq!(zoneddatetime.date.day_of_month().0, 8);

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.nanosecond.number(), 0);
assert_eq!(
    zoneddatetime.zone.time_zone_id(),
    TimeZoneBcp47Id(tinystr!(8, "uschi"))
);
assert_eq!(
    zoneddatetime.zone.offset(),
    Some(UtcOffset::try_from_seconds(-18000).unwrap())
);
assert_eq!(zoneddatetime.zone.zone_variant(), ZoneVariant::Daylight);
let (_, _) = zoneddatetime.zone.local_time();

For more information on date, time, and time zone parsing, see Self::try_from_str.

pub fn try_iso_from_utf8( &self, ixdtf_str: &[u8], ) -> Result<CustomZonedDateTime<Iso, TimeZoneInfo<Full>>, ParseError>

Create a CustomZonedDateTime in ISO-8601 calendar from IXDTF syntax UTF-8 bytes.

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

See Self::try_iso_from_str.

pub fn try_offset_only_from_str( &self, ixdtf_str: &str, ) -> Result<CustomZonedDateTime<AnyCalendar, UtcOffset>, ParseError>

Create a CustomZonedDateTime in any calendar from an IXDTF syntax string.

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

pub fn try_offset_only_from_utf8( &self, ixdtf_str: &[u8], ) -> Result<CustomZonedDateTime<AnyCalendar, UtcOffset>, ParseError>

Create a CustomZonedDateTime in any calendar from IXDTF syntax UTF-8 bytes.

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

pub fn try_location_only_from_str( &self, ixdtf_str: &str, ) -> Result<CustomZonedDateTime<AnyCalendar, TimeZoneInfo<AtTime>>, ParseError>

Create a CustomZonedDateTime in any calendar from an IXDTF syntax string.

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

pub fn try_location_only_from_utf8( &self, ixdtf_str: &[u8], ) -> Result<CustomZonedDateTime<AnyCalendar, TimeZoneInfo<AtTime>>, ParseError>

Create a CustomZonedDateTime in any calendar from IXDTF syntax UTF-8 bytes.

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

pub fn try_loose_from_str( &self, ixdtf_str: &str, ) -> Result<CustomZonedDateTime<AnyCalendar, TimeZoneInfo<AtTime>>, ParseError>

Create a CustomZonedDateTime in any calendar from an IXDTF syntax string.

This function is “loose”: 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.

The zone variant is not calculated with this function. If you need it, use Self::try_from_str.

pub fn try_loose_from_utf8( &self, ixdtf_str: &[u8], ) -> Result<CustomZonedDateTime<AnyCalendar, TimeZoneInfo<AtTime>>, ParseError>

Create a CustomZonedDateTime in any calendar from IXDTF syntax UTF-8 bytes.

This function is “loose”: 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.

The zone variant is not calculated with this function. If you need it, use Self::try_from_utf8.

pub fn try_from_str( &self, ixdtf_str: &str, ) -> Result<CustomZonedDateTime<AnyCalendar, TimeZoneInfo<Full>>, ParseError>

Create a CustomZonedDateTime in any calendar from an IXDTF syntax string.

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

For more information on IXDTF, see the [ixdtf] crate.

This is a convenience constructor that uses compiled data. For custom data providers, use [ixdtf] and/or the other primitives in this crate such as TimeZoneIdMapper.

Examples

Basic usage:

use icu_timezone::{
    IxdtfParser, TimeZoneBcp47Id, TimeZoneInfo, UtcOffset, ZoneVariant,
};
use tinystr::tinystr;

let zoneddatetime = IxdtfParser::new()
    .try_from_str("2024-08-08T12:08:19-05:00[America/Chicago][u-ca=hebrew]")
    .unwrap();

assert_eq!(zoneddatetime.date.year().extended_year, 5784);
assert_eq!(
    zoneddatetime.date.month().standard_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.nanosecond.number(), 0);
assert_eq!(
    zoneddatetime.zone.time_zone_id(),
    TimeZoneBcp47Id(tinystr!(8, "uschi"))
);
assert_eq!(
    zoneddatetime.zone.offset(),
    Some(UtcOffset::try_from_seconds(-18000).unwrap())
);
assert_eq!(zoneddatetime.zone.zone_variant(), ZoneVariant::Daylight);
let (_, _) = zoneddatetime.zone.local_time();

An IXDTF 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 RFC3339; meanwhile, the Time Zone Annotation is the annotation laid out by RFC9557 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 RFC3339 DateTime string.

use icu_timezone::{IxdtfParser, TimeZoneInfo, UtcOffset};

let tz_from_offset = IxdtfParser::new()
    .try_offset_only_from_str("2024-08-08T12:08:19-05:00")
    .unwrap();

assert_eq!(
    tz_from_offset.zone,
    UtcOffset::try_from_seconds(-18000).unwrap()
);

Time Zone Annotations

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

use icu_timezone::{
    IxdtfParser, TimeZoneBcp47Id, TimeZoneInfo, UtcOffset, ZoneVariant,
};
use tinystr::tinystr;

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

assert_eq!(
    tz_from_offset_annotation.zone,
    UtcOffset::try_from_seconds(-18000).unwrap()
);

assert_eq!(
    tz_from_iana_annotation.zone.time_zone_id(),
    TimeZoneBcp47Id(tinystr!(8, "uschi"))
);
assert_eq!(tz_from_iana_annotation.zone.offset(), None);

DateTime UTC Offset and Time Zone Annotations.

An IXDTF string may contain both a DateTime 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 IANA identifier annotation

In cases where the DateTime UTC Offset is provided and the IANA identifier, some validity checks are performed.

use icu_timezone::{TimeZoneInfo, IxdtfParser, UtcOffset, TimeZoneBcp47Id, ZoneVariant, ParseError};
use tinystr::tinystr;

let consistent_tz_from_both = IxdtfParser::new().try_from_str("2024-08-08T12:08:19-05:00[America/Chicago]").unwrap();


assert_eq!(consistent_tz_from_both.zone.time_zone_id(), TimeZoneBcp47Id(tinystr!(8, "uschi")));
assert_eq!(consistent_tz_from_both.zone.offset(), Some(UtcOffset::try_from_seconds(-18000).unwrap()));
assert_eq!(consistent_tz_from_both.zone.zone_variant(), ZoneVariant::Daylight);
let (_, _) = consistent_tz_from_both.zone.local_time();

// We know that America/Los_Angeles never used a -05:00 offset at any time of the year 2024
assert_eq!(
    IxdtfParser::new().try_from_str("2024-08-08T12:08:19-05:00[America/Los_Angeles]").unwrap_err(),
    ParseError::InvalidOffsetError
);

// We don't know that America/Los_Angeles didn't use standard time (-08:00) in August
assert!(
    IxdtfParser::new().try_from_str("2024-08-08T12:08:19-08:00[America/Los_Angeles]").is_ok()
);

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_timezone::{
    IxdtfParser, ParseError, TimeZoneBcp47Id, TimeZoneInfo, UtcOffset,
};
use tinystr::tinystr;

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

assert_eq!(
    consistent_tz_from_both.zone,
    UtcOffset::try_from_seconds(-18000).unwrap()
);

let inconsistent_tz_from_both = IxdtfParser::new()
    .try_offset_only_from_str("2024-08-08T12:08:19-05:00[+05:00]");

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

pub fn try_from_utf8( &self, ixdtf_str: &[u8], ) -> Result<CustomZonedDateTime<AnyCalendar, TimeZoneInfo<Full>>, ParseError>

Create a CustomZonedDateTime in any calendar from IXDTF syntax UTF-8 bytes.

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

See Self::try_from_str.

Trait Implementations

impl Debug for IxdtfParser

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

Formats the value using the given formatter.