Struct icu::timezone::TimeZoneIdMapper

source ·
pub struct TimeZoneIdMapper { /* private fields */ }
Expand description

A mapper between IANA time zone identifiers and BCP-47 time zone identifiers.

This mapper 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 TimeZoneIdMapperWithFastCanonicalization.

§Examples

use icu::timezone::TimeZoneBcp47Id;
use icu::timezone::TimeZoneIdMapper;
use tinystr::tinystr;

let mapper = TimeZoneIdMapper::new();

// The IANA zone "Australia/Melbourne" is the BCP-47 zone "aumel":
assert_eq!(
    mapper.iana_to_bcp47("Australia/Melbourne"),
    TimeZoneBcp47Id(tinystr!(8, "aumel"))
);

// Lookup is ASCII-case-insensitive:
assert_eq!(
    mapper.iana_to_bcp47("australia/melbourne"),
    TimeZoneBcp47Id(tinystr!(8, "aumel"))
);

// The IANA zone "Australia/Victoria" is an alias:
assert_eq!(
    mapper.iana_to_bcp47("Australia/Victoria"),
    TimeZoneBcp47Id(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!(
    mapper.iana_to_bcp47("Australia/Boing_Boing"),
    TimeZoneBcp47Id::unknown()
);

// We can recover the canonical identifier from the mapper:
assert_eq!(
    mapper.canonicalize_iana("Australia/Victoria").unwrap().0,
    "Australia/Melbourne"
);

Implementations§

source§

impl TimeZoneIdMapper

source

pub fn new() -> TimeZoneIdMapperBorrowed<'static>

Creates a new TimeZoneIdMapper using compiled data.

See TimeZoneIdMapper for an example.

Enabled with the compiled_data Cargo feature.

📚 Help choosing a constructor

source

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

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

📚 Help choosing a constructor

source

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

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

Enabled with the serde feature.

📚 Help choosing a constructor

source

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

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.
source

pub fn as_borrowed(&self) -> TimeZoneIdMapperBorrowed<'_>

Returns a borrowed version of the mapper that can be queried.

This avoids a small potential indirection cost when querying the mapper.

Trait Implementations§

source§

impl AsRef<TimeZoneIdMapper> for TimeZoneIdMapper

source§

fn as_ref(&self) -> &TimeZoneIdMapper

Converts this type into a shared reference of the (usually inferred) input type.
source§

impl Clone for TimeZoneIdMapper

source§

fn clone(&self) -> TimeZoneIdMapper

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for TimeZoneIdMapper

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts 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 more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts 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
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

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

fn clone_into(&self, target: &mut T)

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

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> ErasedDestructor for T
where T: 'static,

source§

impl<T> MaybeSendSync for T
where T: Send + Sync,