Struct icu::timezone::IxdtfParser
source · pub struct IxdtfParser { /* private fields */ }
Expand description
✨ Enabled with the ixdtf
Cargo feature.
Implementations§
source§impl IxdtfParser
impl IxdtfParser
sourcepub fn new() -> IxdtfParser
pub fn new() -> IxdtfParser
Creates a new IxdtfParser
from compiled data.
sourcepub fn try_new_with_any_provider(
provider: &(impl AnyProvider + ?Sized),
) -> Result<IxdtfParser, DataError>
pub fn try_new_with_any_provider( provider: &(impl AnyProvider + ?Sized), ) -> Result<IxdtfParser, DataError>
A version of [Self :: new
] that uses custom data provided by an AnyProvider
.
sourcepub fn try_new_with_buffer_provider(
provider: &(impl BufferProvider + ?Sized),
) -> Result<IxdtfParser, DataError>
pub fn try_new_with_buffer_provider( provider: &(impl BufferProvider + ?Sized), ) -> Result<IxdtfParser, DataError>
A version of [Self :: new
] that uses custom data provided by a BufferProvider
.
✨ Enabled with the serde
feature.
sourcepub fn try_new_unstable<P>(provider: &P) -> Result<IxdtfParser, DataError>
pub fn try_new_unstable<P>(provider: &P) -> Result<IxdtfParser, DataError>
A version of Self::new
that uses custom data provided by a DataProvider
.
source§impl IxdtfParser
impl IxdtfParser
sourcepub fn try_offset_only_iso_from_str(
&self,
ixdtf_str: &str,
) -> Result<CustomZonedDateTime<Iso, UtcOffset>, ParseError>
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.
sourcepub fn try_offset_only_iso_from_utf8(
&self,
ixdtf_str: &[u8],
) -> Result<CustomZonedDateTime<Iso, UtcOffset>, ParseError>
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.
sourcepub fn try_location_only_iso_from_str(
&self,
ixdtf_str: &str,
) -> Result<CustomZonedDateTime<Iso, TimeZoneInfo<AtTime>>, ParseError>
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.
sourcepub fn try_location_only_iso_from_utf8(
&self,
ixdtf_str: &[u8],
) -> Result<CustomZonedDateTime<Iso, TimeZoneInfo<AtTime>>, ParseError>
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.
sourcepub fn try_loose_iso_from_str(
&self,
ixdtf_str: &str,
) -> Result<CustomZonedDateTime<Iso, TimeZoneInfo<AtTime>>, ParseError>
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
.
sourcepub fn try_loose_iso_from_utf8(
&self,
ixdtf_str: &[u8],
) -> Result<CustomZonedDateTime<Iso, TimeZoneInfo<AtTime>>, ParseError>
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
.
sourcepub fn try_iso_from_str(
&self,
ixdtf_str: &str,
) -> Result<CustomZonedDateTime<Iso, TimeZoneInfo<Full>>, ParseError>
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
.
sourcepub fn try_iso_from_utf8(
&self,
ixdtf_str: &[u8],
) -> Result<CustomZonedDateTime<Iso, TimeZoneInfo<Full>>, ParseError>
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.
sourcepub fn try_offset_only_from_str(
&self,
ixdtf_str: &str,
) -> Result<CustomZonedDateTime<AnyCalendar, UtcOffset>, ParseError>
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.
sourcepub fn try_offset_only_from_utf8(
&self,
ixdtf_str: &[u8],
) -> Result<CustomZonedDateTime<AnyCalendar, UtcOffset>, ParseError>
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.
sourcepub fn try_location_only_from_str(
&self,
ixdtf_str: &str,
) -> Result<CustomZonedDateTime<AnyCalendar, TimeZoneInfo<AtTime>>, ParseError>
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.
sourcepub fn try_location_only_from_utf8(
&self,
ixdtf_str: &[u8],
) -> Result<CustomZonedDateTime<AnyCalendar, TimeZoneInfo<AtTime>>, ParseError>
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.
sourcepub fn try_loose_from_str(
&self,
ixdtf_str: &str,
) -> Result<CustomZonedDateTime<AnyCalendar, TimeZoneInfo<AtTime>>, ParseError>
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
.
sourcepub fn try_loose_from_utf8(
&self,
ixdtf_str: &[u8],
) -> Result<CustomZonedDateTime<AnyCalendar, TimeZoneInfo<AtTime>>, ParseError>
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
.
sourcepub fn try_from_str(
&self,
ixdtf_str: &str,
) -> Result<CustomZonedDateTime<AnyCalendar, TimeZoneInfo<Full>>, ParseError>
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)
));
sourcepub fn try_from_utf8(
&self,
ixdtf_str: &[u8],
) -> Result<CustomZonedDateTime<AnyCalendar, TimeZoneInfo<Full>>, ParseError>
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§
Auto Trait Implementations§
impl Freeze for IxdtfParser
impl RefUnwindSafe for IxdtfParser
impl Send for IxdtfParser
impl Sync for IxdtfParser
impl Unpin for IxdtfParser
impl UnwindSafe for IxdtfParser
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more