tzdb/lib.rs
1// SPDX-License-Identifier: Apache-2.0
2//
3// Copyright 2022-2024 René Kijewski <crates.io@k6i.de>
4//
5// Licensed under the Apache License, Version 2.0 (the "License");
6// you may not use this file except in compliance with the License.
7// You may obtain a copy of the License at
8//
9// http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing, software
12// distributed under the License is distributed on an "AS IS" BASIS,
13// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14// See the License for the specific language governing permissions and
15// limitations under the License.
16
17#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
18#![allow(unknown_lints)]
19#![forbid(unsafe_code)]
20#![warn(absolute_paths_not_starting_with_crate)]
21#![warn(elided_lifetimes_in_paths)]
22#![warn(explicit_outlives_requirements)]
23#![warn(meta_variable_misuse)]
24#![warn(missing_copy_implementations)]
25#![warn(missing_debug_implementations)]
26#![warn(missing_docs)]
27#![warn(non_ascii_idents)]
28#![warn(noop_method_call)]
29#![warn(single_use_lifetimes)]
30#![warn(trivial_casts)]
31#![warn(unreachable_pub)]
32#![warn(unused_extern_crates)]
33#![warn(unused_lifetimes)]
34#![warn(unused_results)]
35#![no_std]
36
37//! # `tzdb` — Time Zone Database
38//!
39//! [](https://github.com/Kijewski/tzdb/actions/workflows/ci.yml)
40//! [](https://crates.io/crates/tzdb)
41//! [](https://docs.rs/tzdb/)
42//! 
43//! [](https://github.com/Kijewski/tzdb/blob/v0.6.1/LICENSE.md "License: Apache-2.0")
44//!
45//! Static time zone information for [tz-rs](https://crates.io/crates/tz-rs).
46//!
47//! This crate provides all time zones found in the [Time Zone Database](https://www.iana.org/time-zones).
48//!
49//! ## Usage examples
50//!
51//! ```rust
52//! # #[cfg(feature = "local")] {
53//! // get the system time zone
54//! let time_zone = tzdb::local_tz().unwrap(); // tz::TimeZoneRef<'_>
55//! let current_time = tzdb::now::local().unwrap(); // tz::DateTime
56//! # }
57//!
58//! // access by identifier
59//! let time_zone = tzdb::time_zone::europe::KYIV;
60//! # #[cfg(feature = "now")] {
61//! let current_time = tzdb::now::in_tz(tzdb::time_zone::europe::KYIV).unwrap();
62//! # }
63//!
64//! // access by name
65//! let time_zone = tzdb::tz_by_name("Europe/Berlin").unwrap();
66//! # #[cfg(feature = "now")] {
67//! let current_time = tzdb::now::in_named("Europe/Berlin").unwrap();
68//! # }
69//!
70//! // names are case insensitive
71//! let time_zone = tzdb::tz_by_name("ArCtIc/LoNgYeArByEn").unwrap();
72//! # #[cfg(feature = "now")] {
73//! let current_time = tzdb::now::in_named("ArCtIc/LoNgYeArByEn").unwrap();
74//! # }
75//!
76//! // provide a default time zone
77//! # #[cfg(feature = "now")] {
78//! let current_time = tzdb::now::local_or(tzdb::time_zone::GMT).unwrap();
79//! let current_time = tzdb::now::in_named_or(tzdb::time_zone::GMT, "Some/City").unwrap();
80//! # }
81//! ```
82//!
83//! ## Feature flags
84//!
85//! * `local` <sup>(enabled by default)</sup> — enable functions to query the current system time
86//! * `now` <sup>(enabled by default)</sup> — enable functions to query the current system time
87//! * `std` <sup>(enabled by default, `now` and `local`)</sup> — enable the use of features in the [`std`] crate
88//! * `alloc` <sup>(enabled by `std`)</sup> — enable the use of features in the [`alloc`] crate
89
90#[cfg(docsrs)]
91extern crate alloc;
92#[cfg(docsrs)]
93extern crate std;
94
95#[cfg(docsrs)]
96pub mod changelog;
97#[cfg(feature = "now")]
98pub mod now;
99
100#[doc(no_inline)]
101pub use tzdb_data::{time_zone, TZ_NAMES, VERSION, VERSION_HASH};
102
103/// Find a time zone by name, e.g. `"Europe/Berlin"` (case-insensitive)
104///
105/// # Example
106///
107/// ```
108/// assert_eq!(
109/// tzdb::time_zone::europe::BERLIN,
110/// tzdb::tz_by_name("Europe/Berlin").unwrap(),
111/// );
112/// ```
113#[inline]
114pub fn tz_by_name<S: AsRef<[u8]>>(s: S) -> Option<tz::TimeZoneRef<'static>> {
115 Some(*tzdb_data::find_tz(s.as_ref())?)
116}
117
118/// Find the raw, unparsed time zone data by name, e.g. `"Europe/Berlin"` (case-insensitive)
119///
120/// # Example
121///
122/// ```
123/// assert_eq!(
124/// tzdb::time_zone::europe::RAW_BERLIN,
125/// tzdb::raw_tz_by_name("Europe/Berlin").unwrap(),
126/// );
127/// ```
128#[inline]
129pub fn raw_tz_by_name<S: AsRef<[u8]>>(s: S) -> Option<&'static [u8]> {
130 tzdb_data::find_raw(s.as_ref())
131}
132
133/// Find the time zone of the current system
134///
135/// This function uses [`iana_time_zone::get_timezone()`] in the background.
136/// You may want to cache the output to avoid repeated filesystem accesses by `get_timezone()`.
137///
138/// # Example
139///
140/// ```rust
141/// // Query the time zone of the local system:
142/// let time_zone = tzdb::local_tz().unwrap();
143/// ```
144///
145/// Most likely you will want to fallback to a default time zone,
146/// if the system time zone could not be determined or was not found in the database:
147///
148/// ```rust
149/// // Query the time zone of the local system:
150/// let time_zone = tzdb::local_tz().unwrap_or(tzdb::time_zone::GMT);
151/// ```
152#[must_use]
153#[cfg(feature = "local")]
154#[cfg_attr(docsrs, doc(cfg(feature = "local")))]
155pub fn local_tz() -> Option<tz::TimeZoneRef<'static>> {
156 tz_by_name(iana_time_zone::get_timezone().ok()?)
157}