Skip to content

Commit 5a5cd3b

Browse files
nekevssManishearth
nekevss
and
Manishearth
authored
Update the library introduction and README for timezone_provider (#570)
Let me know what you think 😄 I think there's probably more that can be added as far as a deep dive. But this was mostly just to build out the docs more than what was there previously. --------- Co-authored-by: Manish Goregaokar <[email protected]>
1 parent f42353c commit 5a5cd3b

File tree

5 files changed

+130
-9
lines changed

5 files changed

+130
-9
lines changed

‎provider/Cargo.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,3 +72,4 @@ serde = { version = "1.0.219", features = ["derive"], optional = true }
7272
databake = { version = "0.2.0", features = ["derive"], optional = true }
7373
yoke = { version = "0.8.0", features = ["derive"], optional = true }
7474
serde_json = { version = "1.0.143", optional = true }
75+

‎provider/README.md‎

Lines changed: 57 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,63 @@
1+
# Time zone providers
12

23
<!-- cargo-rdme start -->
34

4-
Data providers for time zone data
5+
Providers for time zone data
56

6-
This crate aims to provide a variety of data providers
7-
for time zone data.
7+
Let's talk about time zone data everyone!
8+
9+
At a high level, the `timezone_provider` crate provides a set of traits along with a few
10+
implementations of those traits. The general intention here is to make providing time zone
11+
data as agnostic and easy as possible.
12+
13+
This crate is fairly "low level" at least as far as date and time needs are concerned. So
14+
we'll cover the basic overview of the trait and some of the general implementations of
15+
those traits, and then we will go on a bit further of a dive for the power users that
16+
are interested in implementing their own provider or is just really curious about what
17+
is going on.
18+
19+
### Available providers
20+
21+
Below is a list of currently available time zone providers.
22+
23+
- `ZoneInfo64TzdbProvider`: a provider using ICU4C's zoneinfo64 resource bundle (enable with `zoneinfo64` features flag)
24+
- `FsTzdbProvider`: a provider that reads and parses tzdata at runtime from the host file system's
25+
TZif files (enable with `tzif` feature flag)
26+
- `CompiledTzdbProvider`: a provider that reads and parses tzdata at runtime from TZif's compiled
27+
into the application (enable with `tzif` feature flag)
28+
29+
Coming soon (hopefully), a zero copy compiled tzdb provider (see `experimental_tzif` for more).
30+
31+
### Time zone provider traits
32+
33+
This crate provides three primary traits for working with time zone data.
34+
35+
- [`TimeZoneProvider`][crate::provider::TimeZoneProvider]
36+
- [`TimeZoneNormalizer`][crate::provider::TimeZoneNormalizer]
37+
- [`TimeZoneResolver`][crate::provider::TimeZoneResolver]
38+
39+
The first trait `TimeZoneProvider` is the primary interface for a time zone provider used by `temporal_rs`.
40+
41+
Meanwhile, the two other traits, `TimeZoneNormalizer` and `TimeZoneResolver`, are secondary
42+
traits that can be used to implement the core `TimeZoneProvider`. Once implemented, this
43+
crate providers a default type for creating a `TimeZoneProvider` by mixing and matching objects that implement the secondary
44+
traits, `NormalizerAndResolver`.
45+
46+
#### Why two secondary traits?
47+
48+
Well that's because `TimeZoneProvider` handles two different concerns: fetching and
49+
formatting normalized and canonicalized time zone identifiers, and resolving time
50+
zone data requests. This functionality typically requires two different sets of data,
51+
each of which may be in a variety of formats.
52+
53+
#### Why not just have the two secondary traits without `TimeZoneProvider`?
54+
55+
Well while the functionality typically requires two sets of data. Those sets are not
56+
necessarily completely unique. The time zone database updates potentially multiple times a
57+
year so having your formatting in 2025a while your data is in 2025b could cause some
58+
desync. So in order to better represent this `TimeZoneProvider` is used on top of them.
59+
60+
**NOTE:** you CAN always just directly use `TimeZoneNormalizer` and
61+
`TimeZoneResolver` together if you want. We just wouldn't recommemnd it.
862

963
<!-- cargo-rdme end -->

‎provider/src/lib.rs‎

Lines changed: 56 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,60 @@
1-
//! Data providers for time zone data
1+
//! Providers for time zone data
22
//!
3-
//! This crate aims to provide a variety of data providers
4-
//! for time zone data.
3+
//! Let's talk about time zone data everyone!
4+
//!
5+
//! At a high level, the `timezone_provider` crate provides a set of traits along with a few
6+
//! implementations of those traits. The general intention here is to make providing time zone
7+
//! data as agnostic and easy as possible.
8+
//!
9+
//! This crate is fairly "low level" at least as far as date and time needs are concerned. So
10+
//! we'll cover the basic overview of the trait and some of the general implementations of
11+
//! those traits, and then we will go on a bit further of a dive for the power users that
12+
//! are interested in implementing their own provider or is just really curious about what
13+
//! is going on.
14+
//!
15+
//! ## Available providers
16+
//!
17+
//! Below is a list of currently available time zone providers.
18+
//!
19+
//! - `ZoneInfo64TzdbProvider`: a provider using ICU4C's zoneinfo64 resource bundle (enable with `zoneinfo64` features flag)
20+
//! - `FsTzdbProvider`: a provider that reads and parses tzdata at runtime from the host file system's
21+
//! TZif files (enable with `tzif` feature flag)
22+
//! - `CompiledTzdbProvider`: a provider that reads and parses tzdata at runtime from TZif's compiled
23+
//! into the application (enable with `tzif` feature flag)
24+
//!
25+
//! Coming soon (hopefully), a zero copy compiled tzdb provider (see `experimental_tzif` for more).
26+
//!
27+
//! ## Time zone provider traits
28+
//!
29+
//! This crate provides three primary traits for working with time zone data.
30+
//!
31+
//! - [`TimeZoneProvider`][crate::provider::TimeZoneProvider]
32+
//! - [`TimeZoneNormalizer`][crate::provider::TimeZoneNormalizer]
33+
//! - [`TimeZoneResolver`][crate::provider::TimeZoneResolver]
34+
//!
35+
//! The first trait `TimeZoneProvider` is the primary interface for a time zone provider used by `temporal_rs`.
36+
//!
37+
//! Meanwhile, the two other traits, `TimeZoneNormalizer` and `TimeZoneResolver`, are secondary
38+
//! traits that can be used to implement the core `TimeZoneProvider`. Once implemented, this
39+
//! crate providers a default type for creating a `TimeZoneProvider` by mixing and matching objects that implement the secondary
40+
//! traits, `NormalizerAndResolver`.
41+
//!
42+
//! ### Why two secondary traits?
43+
//!
44+
//! Well that's because `TimeZoneProvider` handles two different concerns: fetching and
45+
//! formatting normalized and canonicalized time zone identifiers, and resolving time
46+
//! zone data requests. This functionality typically requires two different sets of data,
47+
//! each of which may be in a variety of formats.
48+
//!
49+
//! ### Why not just have the two secondary traits without `TimeZoneProvider`?
50+
//!
51+
//! Well while the functionality typically requires two sets of data. Those sets are not
52+
//! necessarily completely unique. The time zone database updates potentially multiple times a
53+
//! year so having your formatting in 2025a while your data is in 2025b could cause some
54+
//! desync. So in order to better represent this `TimeZoneProvider` is used on top of them.
55+
//!
56+
//! **NOTE:** you CAN always just directly use `TimeZoneNormalizer` and
57+
//! `TimeZoneResolver` together if you want. We just wouldn't recommemnd it.
558
//!
659
760
#![no_std]

‎provider/src/provider.rs‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
//! The `TimeZoneProvider` trait.
1+
//! Traits and struct for creating time zone data providers.
2+
//!
3+
//! This module contains the traits needed to implement a time zone data
4+
//! provider along with relevant structs.
25
36
use core::str::FromStr;
47

‎provider/src/tzif.rs‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1251,12 +1251,22 @@ fn offset_range(offset_one: i64, offset_two: i64) -> core::ops::Range<i64> {
12511251

12521252
/// Timezone provider that uses compiled data.
12531253
///
1254-
/// Currently uses jiff_tzdb and performs parsing; will eventually
1255-
/// use pure compiled data (<https://github.com/boa-dev/temporal/pull/264>)
1254+
/// This provider includes raw tzdata in the application binary and parses that data into
1255+
/// a TZif format, which incurs a runtime cost; however, parsed TZifs are cached, which
1256+
/// offsets the runtime cost on repeated requests.
1257+
///
1258+
/// This will eventually use pure compiled data (<https://github.com/boa-dev/temporal/pull/264>)
12561259
pub type CompiledTzdbProvider =
12571260
NormalizerAndResolver<CompiledNormalizer, TzdbResolver<CompiledTzdbResolver>>;
1261+
12581262
/// Timezone provider that uses filesystem based tzif data.
12591263
///
1264+
/// This provider parses tzdata into a TZif format, which incurs a runtime cost; however,
1265+
/// parsed TZifs are cached, which offsets the runtime cost on repeated requests.
1266+
///
1267+
/// Important note: the filesystem tzdb is not available on windows; as a result, this provider
1268+
/// will fallback to compiled data via `jiff_tzdb`.
1269+
///
12601270
/// Currently uses jiff_tzdb and performs parsing; will eventually
12611271
/// use pure compiled data (<https://github.com/boa-dev/temporal/pull/264>)
12621272
pub type FsTzdbProvider = NormalizerAndResolver<CompiledNormalizer, TzdbResolver<FsTzdbResolver>>;

0 commit comments

Comments
 (0)