pub struct IanaParser { /* private fields */ }
Expand description
A parser between IANA time zone identifiers and BCP-47 time zone identifiers.
This parser supports two-way mapping, but it is optimized for the case of IANA to BCP-47. It also supports normalizing and canonicalizing the IANA strings.
There are approximately 600 IANA identifiers and 450 BCP-47 identifiers.
BCP-47 time zone identifiers are 8 ASCII characters or less and currently average 5.1 characters long. Current IANA time zone identifiers are less than 40 ASCII characters and average 14.2 characters long.
These lists grow very slowly; in a typical year, 2-3 new identifiers are added.
§Normalization vs Canonicalization
Multiple IANA time zone identifiers can refer to the same BCP-47 time zone. For example, the
following three IANA identifiers all map to "usind"
:
- “America/Fort_Wayne”
- “America/Indiana/Indianapolis”
- “America/Indianapolis”
- “US/East-Indiana”
There is only one canonical identifier, which is “America/Indiana/Indianapolis”. The canonicalization operation returns the canonical identifier. You should canonicalize if you need to compare time zones for equality. Note that the canonical identifier can change over time. For example, the identifier “Europe/Kiev” was renamed to the newly-added identifier “Europe/Kyiv” in 2022.
The normalization operation, on the other hand, keeps the input identifier but normalizes the casing. For example, “AMERICA/FORT_WAYNE” normalizes to “America/Fort_Wayne”. Normalization is a data-driven operation because there are no algorithmic casing rules that work for all IANA time zone identifiers.
Normalization is a cheap operation, but canonicalization might be expensive, since it might
require searching over all IANA IDs to find the canonicalization. If you need
canonicalization that is reliably fast, use IanaParserExtended
.
§Examples
use icu::time::zone::IanaParser;
use icu::time::TimeZone;
use tinystr::tinystr;
let parser = IanaParser::new();
// The IANA zone "Australia/Melbourne" is the BCP-47 zone "aumel":
assert_eq!(
parser.parse("Australia/Melbourne"),
TimeZone(tinystr!(8, "aumel"))
);
// Lookup is ASCII-case-insensitive:
assert_eq!(
parser.parse("australia/melbourne"),
TimeZone(tinystr!(8, "aumel"))
);
// The IANA zone "Australia/Victoria" is an alias:
assert_eq!(
parser.parse("Australia/Victoria"),
TimeZone(tinystr!(8, "aumel"))
);
// The IANA zone "Australia/Boing_Boing" does not exist
// (maybe not *yet*), so it produces the special unknown
// timezone in order for this operation to be infallible:
assert_eq!(parser.parse("Australia/Boing_Boing"), TimeZone::unknown());
Implementations§
Source§impl IanaParser
impl IanaParser
Sourcepub fn new() -> IanaParserBorrowed<'static>
pub fn new() -> IanaParserBorrowed<'static>
Creates a new IanaParser
using compiled data.
See IanaParser
for an example.
✨ Enabled with the compiled_data
Cargo feature.
Sourcepub fn try_new_with_buffer_provider(
provider: &(impl BufferProvider + ?Sized),
) -> Result<IanaParser, DataError>
pub fn try_new_with_buffer_provider( provider: &(impl BufferProvider + ?Sized), ) -> Result<IanaParser, 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<IanaParser, DataError>
pub fn try_new_unstable<P>(provider: &P) -> Result<IanaParser, DataError>
A version of Self::new
that uses custom data provided by a DataProvider
.
Sourcepub fn as_borrowed(&self) -> IanaParserBorrowed<'_>
pub fn as_borrowed(&self) -> IanaParserBorrowed<'_>
Returns a borrowed version of the parser that can be queried.
This avoids a small potential indirection cost when querying the parser.
Trait Implementations§
Source§impl AsRef<IanaParser> for IanaParser
impl AsRef<IanaParser> for IanaParser
Source§fn as_ref(&self) -> &IanaParser
fn as_ref(&self) -> &IanaParser
Source§impl Clone for IanaParser
impl Clone for IanaParser
Source§fn clone(&self) -> IanaParser
fn clone(&self) -> IanaParser
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moreAuto Trait Implementations§
impl Freeze for IanaParser
impl RefUnwindSafe for IanaParser
impl Send for IanaParser
impl Sync for IanaParser
impl Unpin for IanaParser
impl UnwindSafe for IanaParser
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> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
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