Replace feature fallback with local

This change makes it possible to opt-out of functions the need
`iana_time_zone`. This may be useful if you have other means to
determine the relevant time zone name, and to want to reduce the
compilation time, the number of dependencies, etc.

.github/workflows/ci.yml

@@ -9,6 +9,7 @@ on:
       - v0.3.x
       - v0.4.x
       - v0.5.x
+      - v0.6.x
   pull_request:
     branches:
       - main
@@ -17,6 +18,7 @@ on:
       - v0.3.x
       - v0.4.x
       - v0.5.x
+      - v0.6.x
   schedule:
     - cron: "58 7 * * 3"
 

CHANGELOG.md

@@ -1,5 +1,9 @@
 ## Changes between the versions
 
+### 0.6.0-pre.1 (2023-12-27)
+
+* Make `iana_time_zone` inclusion optional
+
 ### 0.5.9 (2023-12-27)
 
 * Update to Time Zone Database release [2023d](https://mm.icann.org/pipermail/tz-announce/2023-December/000080.html)

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tzdb"
-version = "0.5.9"
+version = "0.6.0-pre.1"
 edition = "2018"
 authors = ["René Kijewski <crates.io@k6i.de>"]
 repository = "https://github.com/Kijewski/tzdb"
@@ -13,13 +13,12 @@ readme = "README.md"
 
 [dependencies]
 tz-rs = { version = "^0.6.14", default-features = false, features = ["const", "std"] }
-iana-time-zone = { version = "^0.1.50", default-features = false }
+iana-time-zone = { version = "^0.1.50", default-features = false, features = ["fallback"], optional = true }
 
 [features]
-default = ["fallback"]
-
-# Do not fail to compile for unknown target platforms:
-fallback = ["iana-time-zone/fallback"]
+default = ["local"]
+# Enable functions to query the current system time:
+local = ["iana-time-zone"]
 
 [package.metadata.docs.rs]
 all-features = true

README.md

@@ -38,4 +38,4 @@ let current_time = tzdb::now::in_named_or(tzdb::time_zone::GMT, "Some/City")?;
 
 ## Feature flags
 
-* `fallback` <sup>(enabled by default)</sup> — compile for unknown target platforms, too
+* `local` <sup>(enabled by default)</sup> — enable functions to query the current system time

SECURITY.md

@@ -4,6 +4,7 @@
 
 | Version | Supported          |
 | :-----: | :----------------: |
+| 0.6.x   | :white_check_mark: |
 | 0.5.x   | :white_check_mark: |
 | 0.4.x   | :white_check_mark: |
 | 0.3.x   | :white_check_mark: |

src/lib.rs

@@ -51,9 +51,11 @@
 //! ## Usage examples
 //!
 //! ```rust
+//! # #[cfg(feature = "local")] {
 //! // get the system time zone
 //! let time_zone = tzdb::local_tz().unwrap();       // tz::TimeZoneRef<'_>
 //! let current_time = tzdb::now::local().unwrap();  // tz::DateTime
+//! # }
 //!
 //! // access by identifier
 //! let time_zone = tzdb::time_zone::europe::KYIV;
@@ -68,13 +70,15 @@
 //! let current_time = tzdb::now::in_named("ArCtIc/LongYeArByEn").unwrap();
 //!
 //! // provide a default time zone
+//! # #[cfg(feature = "local")] {
 //! let current_time = tzdb::now::local_or(tzdb::time_zone::GMT).unwrap();
+//! # }
 //! let current_time = tzdb::now::in_named_or(tzdb::time_zone::GMT, "Some/City").unwrap();
 //! ```
 //!
 //! ## Feature flags
 //!
-//! * `fallback` <sup>*(enabled by default)*</sup> — compile for unknown target platforms, too
+//! * `local` <sup>(enabled by default)</sup> — enable functions to query the current system time
 //!
 
 #[cfg(docsrs)]
@@ -85,8 +89,6 @@ pub mod changelog;
 mod generated;
 pub mod now;
 
-use iana_time_zone::get_timezone;
-
 pub use crate::generated::time_zone;
 
 /// The version of the source Time Zone Database
@@ -130,7 +132,7 @@ pub const TZ_NAMES: &[&str] = &crate::generated::TIME_ZONES_LIST;
 
 /// Find the time zone of the current system
 ///
-/// This function uses [`iana_time_zone::get_timezone()`](get_timezone) in the background.
+/// This function uses [`iana_time_zone::get_timezone()`] in the background.
 /// You may want to cache the output to avoid repeated filesystem accesses by `get_timezone()`.
 ///
 /// # Example
@@ -148,6 +150,8 @@ pub const TZ_NAMES: &[&str] = &crate::generated::TIME_ZONES_LIST;
 /// let time_zone = tzdb::local_tz().unwrap_or(tzdb::time_zone::GMT);
 /// ```
 #[must_use]
+#[cfg(feature = "local")]
+#[cfg_attr(docsrs, doc(cfg(feature = "local")))]
 pub fn local_tz() -> Option<tz::TimeZoneRef<'static>> {
-    tz_by_name(get_timezone().ok()?)
+    tz_by_name(iana_time_zone::get_timezone().ok()?)
 }

src/now.rs

@@ -4,10 +4,20 @@ use std::convert::TryFrom;
 use std::fmt;
 use std::time::{SystemTime, SystemTimeError};
 
-use iana_time_zone::{get_timezone, GetTimezoneError};
 use tz::error::ProjectDateTimeError;
 use tz::{DateTime, TimeZoneRef};
 
+#[cfg(not(feature = "local"))]
+mod iana_time_zone {
+    #[allow(missing_copy_implementations)] // intentionally omitted
+    #[derive(Debug)]
+    #[non_exhaustive]
+    pub struct GetTimezoneError(Impossible);
+
+    #[derive(Debug, Clone, Copy)]
+    enum Impossible {}
+}
+
 /// An error as returned by [`local()`] and similar functions
 ///
 /// # See also:
@@ -19,7 +29,7 @@ use tz::{DateTime, TimeZoneRef};
 #[derive(Debug)]
 pub enum NowError {
     /// Could not get time zone. Only returned by [`local()`].
-    TimeZone(GetTimezoneError),
+    TimeZone(iana_time_zone::GetTimezoneError),
     /// Unknown system time zone. Only returned by [`local()`], and [`in_named()`].
     UnknownTimezone,
     /// Could not project timestamp.
@@ -42,7 +52,10 @@ impl fmt::Display for NowError {
 impl std::error::Error for NowError {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
         match self {
+            #[cfg(feature = "local")]
             Self::TimeZone(err) => Some(err),
+            #[cfg(not(feature = "local"))]
+            Self::TimeZone(_) => None,
             Self::UnknownTimezone => None,
             Self::ProjectDateTime(err) => Some(err),
             Self::Utcnow(err) => Some(err),
@@ -86,8 +99,10 @@ impl std::error::Error for NowError {
 /// * `local()` / [`local_or()`]
 /// * [`in_named()`] / [`in_named_or()`]
 /// * [`in_tz()`]
+#[cfg(feature = "local")]
+#[cfg_attr(docsrs, doc(cfg(feature = "local")))]
 pub fn local() -> Result<DateTime, NowError> {
-    in_named(get_timezone().map_err(NowError::TimeZone)?)
+    in_named(iana_time_zone::get_timezone().map_err(NowError::TimeZone)?)
 }
 
 /// Get the current time in the local system time zone with a fallback time zone
@@ -115,8 +130,10 @@ pub fn local() -> Result<DateTime, NowError> {
 /// * [`local()`] / `local_or()`
 /// * [`in_named()`] / [`in_named_or()`]
 /// * [`in_tz()`]
+#[cfg(feature = "local")]
+#[cfg_attr(docsrs, doc(cfg(feature = "local")))]
 pub fn local_or(default: TimeZoneRef<'_>) -> Result<DateTime, NowError> {
-    let tz = get_timezone()
+    let tz = iana_time_zone::get_timezone()
         .ok()
         .and_then(crate::tz_by_name)
         .unwrap_or(default);