refactor: gate sketches with feature flags

.github/workflows/ci.yml

@@ -52,8 +52,10 @@ jobs:
       - uses: taiki-e/install-action@v2
         with:
           tool: typos-cli,taplo-cli,hawkeye
-      - name: Check all
+      - name: Check linters
         run: cargo x lint
+      - name: Check feature matrix
+        run: cargo x check
 
   msrv:
     name: Resolve MSRV

CONTRIBUTING.md

@@ -27,7 +27,7 @@ Rustup will read the `rust-toolchain.toml` file and set up everything else autom
 
 ```shell
 cargo version
-# cargo 1.85.0 (<hash> 2024-12-31)
+# cargo 1.86.0 (<hash> <date>)
 ```
 
 To keep code style consistent, run `cargo x lint --fix` to automatically fix any style issues before committing your changes.

Cargo.toml

@@ -25,7 +25,7 @@ homepage = "https://datasketches.apache.org"
 license = "Apache-2.0"
 readme = "README.md"
 repository = "https://github.com/apache/datasketches-rust"
-rust-version = "1.85.0"
+rust-version = "1.86.0"
 
 [workspace.dependencies]
 # Workspace dependencies
@@ -35,7 +35,7 @@ datasketches = { path = "datasketches" }
 clap = { version = "4.5.20", features = ["derive"] }
 insta = { version = "1.46.1" }
 googletest = { version = "0.14.2" }
-rand = { version = "0.9.2" }
+cargo_metadata = { version = "0.23.1" }
 which = { version = "8.0.0" }
 
 [workspace.lints.rust]

README.md

@@ -21,15 +21,15 @@
 
 [![Crates.io][crates-badge]][crates-url]
 [![Documentation][docs-badge]][docs-url]
-[![MSRV 1.85.0][msrv-badge]](https://www.whatrustisit.com)
+[![MSRV 1.86.0][msrv-badge]](https://www.whatrustisit.com)
 [![Apache 2.0 licensed][license-badge]][license-url]
 [![Build Status][actions-badge]][actions-url]
 
 [crates-badge]: https://img.shields.io/crates/v/datasketches.svg
 [crates-url]: https://crates.io/crates/datasketches
 [docs-badge]: https://img.shields.io/docsrs/datasketches
 [docs-url]: https://docs.rs/datasketches
-[msrv-badge]: https://img.shields.io/badge/MSRV-1.85.0-green?logo=rust
+[msrv-badge]: https://img.shields.io/badge/MSRV-1.86.0-green?logo=rust
 [license-badge]: https://img.shields.io/crates/l/datasketches
 [license-url]: LICENSE
 [actions-badge]: https://github.com/apache/datasketches-rust/workflows/CI/badge.svg

datasketches/Cargo.toml

@@ -34,6 +34,18 @@ keywords = ["sketch", "hyperloglog", "probabilistic"]
 all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
 
+[features]
+default = []
+
+# Each sketch has its own feature, so that users can opt in to only the sketches they need.
+bloom = []
+countmin = []
+cpc = []
+frequencies = []
+hll = []
+tdigest = []
+theta = []
+
 [dev-dependencies]
 googletest = { workspace = true }
 insta = { workspace = true }

datasketches/src/codec/family.rs

@@ -27,13 +27,16 @@ pub struct Family {
     /// The name for this family.
     pub name: &'static str,
     /// The minimum preamble size for this family in longs (8-bytes integer).
+    #[allow(dead_code)] // only some sketches need to check this field
     pub min_pre_longs: u8,
     /// The maximum preamble size for this family in longs (8-bytes integer).
+    #[allow(dead_code)] // only some sketches need to check this field
     pub max_pre_longs: u8,
 }
 
 impl Family {
     /// Theta Sketch for cardinality estimation.
+    #[cfg(feature = "theta")]
     pub const THETA: Family = Family {
         id: 3,
         name: "THETA",
@@ -42,6 +45,7 @@ impl Family {
     };
 
     /// The HLL family of sketches.
+    #[cfg(feature = "hll")]
     pub const HLL: Family = Family {
         id: 7,
         name: "HLL",
@@ -50,6 +54,7 @@ impl Family {
     };
 
     /// The Frequency family of sketches.
+    #[cfg(feature = "frequencies")]
     pub const FREQUENCY: Family = Family {
         id: 10,
         name: "FREQUENCY",
@@ -58,6 +63,7 @@ impl Family {
     };
 
     /// Compressed Probabilistic Counting (CPC) Sketch.
+    #[cfg(feature = "cpc")]
     pub const CPC: Family = Family {
         id: 16,
         name: "CPC",
@@ -66,6 +72,7 @@ impl Family {
     };
 
     /// CountMin Sketch
+    #[cfg(feature = "countmin")]
     pub const COUNTMIN: Family = Family {
         id: 18,
         name: "COUNTMIN",
@@ -74,6 +81,7 @@ impl Family {
     };
 
     /// T-Digest for estimating quantiles and ranks.
+    #[cfg(feature = "tdigest")]
     pub const TDIGEST: Family = Family {
         id: 20,
         name: "TDIGEST",
@@ -82,6 +90,7 @@ impl Family {
     };
 
     /// Bloom Filter.
+    #[cfg(feature = "bloom")]
     pub const BLOOMFILTER: Family = Family {
         id: 21,
         name: "BLOOMFILTER",

datasketches/src/codec/mod.rs

@@ -17,12 +17,30 @@
 
 //! Codec utilities for datasketches crate.
 
-// public common codec utilities for datasketches crate
 mod decode;
 mod encode;
 pub use self::decode::SketchSlice;
 pub use self::encode::SketchBytes;
 
-// private to datasketches crate
+#[cfg(any(
+    feature = "bloom",
+    feature = "countmin",
+    feature = "cpc",
+    feature = "frequencies",
+    feature = "hll",
+    feature = "tdigest",
+    feature = "theta"
+))]
+#[allow(dead_code)] // some utilities are only used for certain sketches
 pub(crate) mod assert;
+
+#[cfg(any(
+    feature = "bloom",
+    feature = "countmin",
+    feature = "cpc",
+    feature = "frequencies",
+    feature = "hll",
+    feature = "tdigest",
+    feature = "theta"
+))]
 pub(crate) mod family;

datasketches/src/common/mod.rs

@@ -17,12 +17,12 @@
 
 //! Data structures and functions that may be used across all the sketch families.
 
-// public common components for datasketches crate
 mod num_std_dev;
 mod resize;
 pub use self::num_std_dev::NumStdDev;
 pub use self::resize::ResizeFactor;
 
-// private to datasketches crate
+#[cfg(feature = "theta")]
 pub(crate) mod binomial_bounds;
+#[cfg(feature = "cpc")]
 pub(crate) mod inv_pow2_table;

datasketches/src/error.rs

@@ -89,7 +89,8 @@ impl Error {
     }
 }
 
-// Convenient constructors used within datasketches crate.
+// pub(crate) convenient constructors
+#[allow(dead_code)] // some constructors are only used for certain sketches
 impl Error {
     pub(crate) fn invalid_argument(msg: impl Into<String>) -> Self {
         Self::new(ErrorKind::InvalidArgument, msg)

datasketches/src/hash/mod.rs

@@ -15,10 +15,26 @@
 // specific language governing permissions and limitations
 // under the License.
 
+#[cfg(any(
+    feature = "countmin",
+    feature = "cpc",
+    feature = "frequencies",
+    feature = "hll",
+    feature = "theta"
+))]
 mod murmurhash;
-mod xxhash;
-
+#[cfg(any(
+    feature = "countmin",
+    feature = "cpc",
+    feature = "frequencies",
+    feature = "hll",
+    feature = "theta"
+))]
 pub(crate) use self::murmurhash::MurmurHash3X64128;
+
+#[cfg(feature = "bloom")]
+mod xxhash;
+#[cfg(feature = "bloom")]
 pub(crate) use self::xxhash::XxHash64;
 
 /// The seed 9001 used in the sketch update methods is a prime number that was chosen very early
@@ -34,6 +50,14 @@ pub(crate) use self::xxhash::XxHash64;
 /// and seed are identical for both sketches, otherwise the assumed 1:1 relationship between the
 /// original source key value and the hashed bit string would be violated. Once you have developed
 /// a history of stored sketches you are stuck with it.
+#[cfg(any(
+    feature = "bloom",
+    feature = "countmin",
+    feature = "cpc",
+    feature = "frequencies",
+    feature = "hll",
+    feature = "theta"
+))]
 pub(crate) const DEFAULT_UPDATE_SEED: u64 = 9001;
 
 /// Computes and checks the 16-bit seed hash from the given long seed.
@@ -44,6 +68,7 @@ pub(crate) const DEFAULT_UPDATE_SEED: u64 = 9001;
 /// # Panics
 ///
 /// Panics if the computed seed hash is zero.
+#[cfg(any(feature = "countmin", feature = "cpc", feature = "theta"))]
 pub(crate) fn compute_seed_hash(seed: u64) -> u16 {
     use std::hash::Hasher;
 
@@ -60,6 +85,14 @@ pub(crate) fn compute_seed_hash(seed: u64) -> u16 {
 /// # Panics
 ///
 /// Panics if `bytes.len()` is greater than 8.
+#[cfg(any(
+    feature = "bloom",
+    feature = "countmin",
+    feature = "cpc",
+    feature = "frequencies",
+    feature = "hll",
+    feature = "theta"
+))]
 fn read_u64_le(bytes: &[u8]) -> u64 {
     let mut buf = [0u8; 8];
     buf[..bytes.len()].copy_from_slice(bytes);