Make by_name() and names_in_db() optional

.github/workflows/ci.yml

@@ -56,8 +56,8 @@ jobs:
       - name: Cache
         uses: actions/cache@v2
         with:
-          key: ${{ runner.os }}-check-${{ steps.actions-rs.outputs.rustc }}-${{ hashFiles('Cargo.lock') }}
-          restore-keys: ${{ runner.os }}-check-${{ steps.actions-rs.outputs.rustc }}-
+          key: ${{ runner.os }}-check-${{ steps.actions-rs.outputs.rustc_hash }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-check-${{ steps.actions-rs.outputs.rustc_hash }}-
           path: |
             ~/.cargo/registry/index/
             ~/.cargo/registry/cache/
@@ -96,8 +96,8 @@ jobs:
       - name: Cache
         uses: actions/cache@v2
         with:
-          key: ${{ runner.os }}-test-${{ steps.actions-rs.outputs.rustc }}-${{ hashFiles('Cargo.lock') }}
-          restore-keys: ${{ runner.os }}-test-${{ steps.actions-rs.outputs.rustc }}-
+          key: ${{ runner.os }}-test-${{ steps.actions-rs.outputs.rustc_hash }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-test-${{ steps.actions-rs.outputs.rustc_hash }}-
           path: |
             ~/.cargo/registry/index/
             ~/.cargo/registry/cache/
@@ -106,6 +106,37 @@ jobs:
 
       - run: cargo test --workspace --all-targets
 
+  doc:
+    name: "Documentation"
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          lfs: true
+
+      - name: Install Rust
+        id: actions-rs
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: nightly
+          override: true
+
+      - name: Cache
+        uses: actions/cache@v2
+        with:
+          key: ${{ runner.os }}-doc-${{ steps.actions-rs.outputs.rustc_hash }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-doc-${{ steps.actions-rs.outputs.rustc_hash }}-
+          path: |
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            target/
+
+      - run: cargo doc --package tzdb --features docsrs
+
   audit:
     runs-on: ubuntu-latest
 

README.md

@@ -15,13 +15,13 @@ See the documentation for a full list the the contained time zones:
 
 ## Usage examples
 
-```rs
+```rust
 use tz::{DateTime, TimeZone};
 use tzdb::TimeZoneExt;
 
 let access_by_identifier = DateTime::now(tzdb::time_zone::EuropeKiev);
 let access_by_name = DateTime::now(TimeZone::from_db("Europe/Berlin").unwrap());
-let names_are_caseless = DateTime::now(TimeZone::from_db("ArCtIc/LongYeArByEn").unwrap());
+let names_are_case_insensitive = DateTime::now(TimeZone::from_db("ArCtIc/LongYeArByEn").unwrap());
 ```
 
 ## Git Cloning

make-tzdb/src/main.rs

@@ -138,7 +138,7 @@ pub fn main() -> anyhow::Result<()> {
 use once_cell::race::OnceBox;
 use tz::TimeZone;
 
-use crate::{{DbTimeZone, Lower32}};
+use crate::DbTimeZone;
 "#
     )?;
 
@@ -164,6 +164,7 @@ use crate::{{DbTimeZone, Lower32}};
     writeln!(f, "}}")?;
     writeln!(f)?;
 
+    writeln!(f, r#"#[cfg(feature = "by-name")]"#)?;
     writeln!(
         f,
         "pub(crate) fn tz_by_name(s: &str) -> Option<&'static DbTimeZone> {{"
@@ -172,7 +173,7 @@ use crate::{{DbTimeZone, Lower32}};
     assert!(max_len <= 32);
     writeln!(
         f,
-        "    Some(*TIME_ZONES_BY_NAME.get(Lower32([0u128; 2]).for_str(s)?)?)"
+        "    Some(*TIME_ZONES_BY_NAME.get(crate::Lower32([0u128; 2]).for_str(s)?)?)"
     )?;
     writeln!(f, "}}")?;
     writeln!(f)?;
@@ -181,13 +182,15 @@ use crate::{{DbTimeZone, Lower32}};
     for (_, name, _, canon) in &names_and_indices {
         phf.entry(name.to_ascii_lowercase(), &format!("time_zone::{}", canon));
     }
+    writeln!(f, r#"#[cfg(feature = "by-name")]"#)?;
     writeln!(
         f,
         "static TIME_ZONES_BY_NAME: phf::Map<&'static str, &'static DbTimeZone> = {};",
         phf.build(),
     )?;
     writeln!(f)?;
 
+    writeln!(f, r#"#[cfg(feature = "list")]"#)?;
     writeln!(
         f,
         "pub(crate) static TIME_ZONES_LIST: [(&str, &DbTimeZone); {}] = [",

tzdb/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tzdb"
-version = "0.0.3"
+version = "0.0.5"
 edition = "2021"
 authors = ["René Kijewski <[email protected]>"]
 repository = "https://github.com/Kijewski/tzdb"
@@ -12,7 +12,25 @@ readme = "README.md"
 rust-version = "1.57"
 
 [dependencies]
-byte-slice-cast = "1.2.0"
 once_cell = { version = "1.9.0", features = ["parking_lot", "race"] }
-phf = "0.10.1"
 tz-rs = "0.5.3"
+
+# optional dependencies
+byte-slice-cast = { version = "1.2.0", optional = true }
+document-features = { version = "=0.2.1", optional = true }
+phf = { version = "0.10.1", optional = true }
+
+[features]
+default = ["by-name", "list"]
+## enables [TimeZoneExt::from_db()]
+##
+by-name = ["phf", "byte-slice-cast"]
+## enables [TimeZoneExt::names_in_db()]
+##
+list = []
+
+# Internal feature, used when generating docs. *You* are not supposed to enable this feature!
+docsrs = ["document-features", "default"]
+
+[package.metadata.docs.rs]
+features = ["docsrs"]

tzdb/src/lib.rs

@@ -31,6 +31,7 @@
 #![warn(unused_extern_crates)]
 #![warn(unused_lifetimes)]
 #![warn(unused_results)]
+#![cfg_attr(feature = "docsrs", feature(doc_cfg))]
 
 //! # tzdb — Time Zone Database
 //!
@@ -55,20 +56,21 @@
 //!
 //! let access_by_identifier = DateTime::now(tzdb::time_zone::EuropeKiev);
 //! let access_by_name = DateTime::now(TimeZone::from_db("Europe/Berlin").unwrap());
-//! let names_are_caseless = DateTime::now(TimeZone::from_db("ArCtIc/LongYeArByEn").unwrap());
+//! let names_are_case_insensitive = DateTime::now(TimeZone::from_db("ArCtIc/LongYeArByEn").unwrap());
 //! ```
+//!
+//! ## Feature flags
+#![cfg_attr(feature = "docsrs", doc = ::document_features::document_features!())]
 
 mod generated;
 
 use std::fmt;
 use std::ops::Deref;
 
-use byte_slice_cast::{AsByteSlice, AsMutByteSlice};
 use once_cell::race::OnceBox;
 use tz::TimeZone;
 
 pub use crate::generated::time_zone;
-use crate::generated::{tz_by_name, TIME_ZONES_LIST};
 
 /// A time zone
 #[derive(Clone, Copy)]
@@ -126,24 +128,34 @@ impl Deref for DbTimeZone {
 
 /// Import this trait to extend [tz::TimeZone]'s functionality
 pub trait TimeZoneExt {
-    /// Find a time zone by name, e.g. `"Europe/Berlin"` (caseless)
+    /// Find a time zone by name, e.g. `"Europe/Berlin"` (case-insensitive)
+    #[cfg(feature = "by-name")]
+    #[cfg_attr(feature = "docsrs", doc(cfg(feature = "by-name")))]
+    #[inline]
     fn from_db(s: &str) -> Option<&'static TimeZone> {
-        Some(&*tz_by_name(s)?)
+        Some(&*crate::generated::tz_by_name(s)?)
     }
 
     /// A list of all known time zones
+    #[cfg(feature = "list")]
+    #[cfg_attr(feature = "docsrs", doc(cfg(feature = "list")))]
+    #[inline]
     fn names_in_db() -> &'static [(&'static str, &'static DbTimeZone)] {
-        &TIME_ZONES_LIST[..]
+        &crate::generated::TIME_ZONES_LIST[..]
     }
 }
 
 impl TimeZoneExt for TimeZone {}
 
+#[cfg(feature = "by-name")]
 struct Lower32([u128; 2]);
 
+#[cfg(feature = "by-name")]
 impl Lower32 {
     #[inline]
     fn for_str<'a>(&'a mut self, s: &str) -> Option<&'a str> {
+        use byte_slice_cast::{AsByteSlice, AsMutByteSlice};
+
         self.0
             .as_mut_byte_slice()
             .get_mut(..s.len())?