Expand description
Types for resolving and manipulating time zones.
§Fields
In ICU4X, a formattable time zone consists of up to four different fields:
- The time zone ID
- The offset from UTC
- A timestamp, as time zone names can change over time
- The zone variant, representing concepts such as Standard, Summer, Daylight, and Ramadan time
§Time Zone
The time zone ID corresponds to a time zone from the time zone database. The time zone ID usually corresponds to the largest city in the time zone.
There are two mostly-interchangeable standards for time zone IDs:
- IANA time zone IDs, like
"America/Chicago"
- BCP-47 time zone IDs, like
"uschi"
ICU4X uses BCP-47 time zone IDs for all of its APIs. To get a BCP-47 time zone from an
IANA time zone, use TimeZoneIdMapper
.
§UTC Offset
The UTC offset precisely states the time difference between the time zone in question and Coordinated Universal Time (UTC).
In localized strings, it is often rendered as “UTC-6”, meaning 6 hours less than UTC (some locales use the term “GMT” instead of “UTC”).
§Timestamp
Some time zones change names over time, such as when changing “metazone”. For example, Portugal changed from
“Western European Time” to “Central European Time” and back in the 1990s, without changing time zone id
(Europe/Lisbon
/ptlis
). Therefore, a timestamp is needed to resolve such generic time zone names.
It is not required to set the timestamp on TimeZoneInfo
. If it is not set, some string
formats may be unsupported.
§Zone Variant
Many zones use different names and offsets in the summer than in the winter. In ICU4X, this is called the zone variant.
CLDR has two zone variants, named "standard"
and "daylight"
. However, the mapping of these
variants to specific observed offsets varies from time zone to time zone, and they may not
consistently represent winter versus summer time.
Note: It is not required to set the zone variant on TimeZoneInfo
. If it is not set, some string
formats may be unsupported.
§Examples
use icu::calendar::{Date, Time};
use icu::timezone::TimeZoneBcp47Id;
use icu::timezone::TimeZoneIdMapper;
use icu::timezone::ZoneVariant;
use tinystr::tinystr;
// Parse the IANA ID
let id = TimeZoneIdMapper::new().iana_to_bcp47("America/Chicago");
// Alternatively, use the BCP47 ID directly
let id = TimeZoneBcp47Id(tinystr!(8, "uschi"));
// Create a TimeZoneInfo<Base> by associating the ID with an offset
let time_zone = id.with_offset("-0600".parse().ok());
// Extend to a TimeZoneInfo<AtTime> by adding a local time
let time_zone_at_time = time_zone
.at_time((Date::try_new_iso(2023, 12, 2).unwrap(), Time::midnight()));
// Extend to a TimeZoneInfo<Full> by adding a zone variant
let time_zone_with_variant =
time_zone_at_time.with_zone_variant(ZoneVariant::Standard);
Modules§
- Time zone data model choices.
- 🚧 [Unstable] Data provider struct definitions for this ICU4X component.
- Scaffolding traits and types not generally required in client code.
Structs§
- A date and time local to a specified custom time zone.
- The time zone offset was invalid. Must be within ±18:00:00.
- ✨ Enabled with the
ixdtf
Cargo feature. - TimeZone ID in BCP47 format
- A mapper between IANA time zone identifiers and BCP-47 time zone identifiers.
- A borrowed wrapper around the time zone ID mapper, returned by
TimeZoneIdMapper::as_borrowed()
. More efficient to query. - A mapper that supplements
TimeZoneIdMapper
with about 8 KB of additional data to improve the performance of canonical IANA ID lookup. - A borrowed wrapper around the time zone ID mapper, returned by
TimeZoneIdMapperWithFastCanonicalization::as_borrowed()
. More efficient to query. - A utility type that can hold time zone information.
- An offset from Coordinated Universal Time (UTC)
- A mapper between Windows time zone identifier and a BCP-47 ID.
- A borrowed wrapper around the windows time zone mapper data.
ZoneOffsetCalculator
uses data from the data provider to calculate time zone offsets.- Represents the different offsets in use for a time zone
Enums§
- The error type for parsing IXDTF syntax strings in
icu_timezone
. - A time zone variant, representing the currently observed relative offset.
Traits§
- Trait encoding a particular data model for time zones.