refactor: simplify hash and theta module layout

.gitignore

@@ -38,4 +38,4 @@
 **/target
 
 # Generated files
-*.sk
+*.sk

CHANGELOG.md

@@ -6,6 +6,7 @@ All significant changes to this project will be documented in this file.
 
 ### Breaking changes
 
+* Move the `hash_value` module to `hash::value`.
 * Remove `ThetaSketch::builder`, `ThetaUnion::builder`, and `TupleSketch::builder`. Construct `ThetaSketchBuilder`, `ThetaUnionBuilder`, and `TupleSketchBuilder` with `Default::default` instead.
 * Standardize Theta and Tuple set-operation constructors. Zero-configuration operators use
   `Default::default()`, `TupleIntersection::new(policy)` uses the default seed, and `with_seed`

datasketches/src/bloom/builder.rs

@@ -62,7 +62,8 @@ impl BloomFilterBuilder {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::BloomFilterBuilder;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// // Optimal for 10,000 items with 1% FPP
     /// let filter = BloomFilterBuilder::with_accuracy(10_000, 0.01)
     ///     .seed(42)
@@ -107,7 +108,8 @@ impl BloomFilterBuilder {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::BloomFilterBuilder;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let filter = BloomFilterBuilder::with_size(10_000, 7).build();
     /// ```
     pub fn with_size(num_bits: u64, num_hashes: u16) -> Self {
@@ -140,7 +142,8 @@ impl BloomFilterBuilder {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::BloomFilterBuilder;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let filter = BloomFilterBuilder::with_accuracy(100, 0.01)
     ///     .seed(12345)
     ///     .build();
@@ -176,7 +179,8 @@ impl BloomFilterBuilder {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::BloomFilterBuilder;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let bits = BloomFilterBuilder::suggest_num_bits(1000, 0.01);
     /// assert!(bits > 9000 && bits < 10000); // ~9585 bits
     /// ```
@@ -198,7 +202,8 @@ impl BloomFilterBuilder {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::BloomFilterBuilder;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let hashes = BloomFilterBuilder::suggest_num_hashes_from_accuracy(1000, 10000);
     /// assert_eq!(hashes, 7); // Optimal k ≈ 6.93
     /// ```
@@ -222,7 +227,8 @@ impl BloomFilterBuilder {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::BloomFilterBuilder;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let hashes = BloomFilterBuilder::suggest_num_hashes_from_fpp(0.01);
     /// assert_eq!(hashes, 7); // -log2(0.01) ≈ 6.64
     /// ```

datasketches/src/bloom/mod.rs

@@ -61,7 +61,8 @@
 //! Automatically calculates optimal size and hash functions:
 //!
 //! ```
-//! # use datasketches::bloom::BloomFilterBuilder;
+//! use datasketches::bloom::BloomFilterBuilder;
+//!
 //! let filter = BloomFilterBuilder::with_accuracy(
 //!     10_000, // Expected max items
 //!     0.01,   // Target false positive probability (1%)
@@ -75,7 +76,8 @@
 //! Specify requested bit count and hash functions (rounded up to a multiple of 64 bits):
 //!
 //! ```
-//! # use datasketches::bloom::BloomFilterBuilder;
+//! use datasketches::bloom::BloomFilterBuilder;
+//!
 //! let filter = BloomFilterBuilder::with_size(
 //!     95_851, // Number of bits
 //!     7,      // Number of hash functions
@@ -88,7 +90,8 @@
 //! Bloom filters support efficient set operations:
 //!
 //! ```
-//! # use datasketches::bloom::BloomFilterBuilder;
+//! use datasketches::bloom::BloomFilterBuilder;
+//!
 //! let mut filter1 = BloomFilterBuilder::with_accuracy(100, 0.01).build();
 //! let mut filter2 = BloomFilterBuilder::with_accuracy(100, 0.01).build();
 //!

datasketches/src/bloom/sketch.rs

@@ -61,7 +61,8 @@ impl BloomFilter {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::BloomFilterBuilder;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let mut filter = BloomFilterBuilder::with_accuracy(100, 0.01).build();
     /// filter.insert("apple");
     ///
@@ -85,7 +86,8 @@ impl BloomFilter {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::BloomFilterBuilder;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let mut filter = BloomFilterBuilder::with_accuracy(100, 0.01).build();
     ///
     /// let was_present = filter.contains_and_insert(&"apple");
@@ -108,7 +110,8 @@ impl BloomFilter {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::BloomFilterBuilder;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let mut filter = BloomFilterBuilder::with_accuracy(100, 0.01).build();
     ///
     /// filter.insert("apple");
@@ -129,7 +132,8 @@ impl BloomFilter {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::BloomFilterBuilder;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let mut filter = BloomFilterBuilder::with_accuracy(100, 0.01).build();
     /// filter.insert("apple");
     /// assert!(!filter.is_empty());
@@ -156,7 +160,8 @@ impl BloomFilter {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::BloomFilterBuilder;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let mut f1 = BloomFilterBuilder::with_accuracy(100, 0.01)
     ///     .seed(123)
     ///     .build();
@@ -198,7 +203,8 @@ impl BloomFilter {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::BloomFilterBuilder;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let mut f1 = BloomFilterBuilder::with_accuracy(100, 0.01)
     ///     .seed(123)
     ///     .build();
@@ -238,7 +244,8 @@ impl BloomFilter {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::BloomFilterBuilder;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let mut filter = BloomFilterBuilder::with_accuracy(100, 0.01).build();
     /// filter.insert("apple");
     ///
@@ -324,7 +331,9 @@ impl BloomFilter {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::{BloomFilter, BloomFilterBuilder};
+    /// use datasketches::bloom::BloomFilter;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let mut filter = BloomFilterBuilder::with_accuracy(100, 0.01).build();
     /// filter.insert("test");
     ///
@@ -387,7 +396,9 @@ impl BloomFilter {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::bloom::{BloomFilter, BloomFilterBuilder};
+    /// use datasketches::bloom::BloomFilter;
+    /// use datasketches::bloom::BloomFilterBuilder;
+    ///
     /// let original = BloomFilterBuilder::with_accuracy(100, 0.01).build();
     /// let bytes = original.serialize();
     ///

datasketches/src/common/resize.rs

@@ -36,7 +36,8 @@
 /// # Examples
 ///
 /// ```
-/// # use datasketches::common::ResizeFactor;
+/// use datasketches::common::ResizeFactor;
+///
 /// let factor = ResizeFactor::X4;
 /// assert_eq!(factor.value(), 4);
 /// assert_eq!(factor.lg_value(), 2);

datasketches/src/countmin/mod.rs

@@ -23,7 +23,8 @@
 //! # Usage
 //!
 //! ```
-//! # use datasketches::countmin::CountMinSketch;
+//! use datasketches::countmin::CountMinSketch;
+//!
 //! let mut sketch = CountMinSketch::<i64>::new(5, 256);
 //! sketch.update("apple");
 //! sketch.update_with_weight("banana", 3);
@@ -33,7 +34,8 @@
 //! # Configuration Helpers
 //!
 //! ```
-//! # use datasketches::countmin::CountMinSketch;
+//! use datasketches::countmin::CountMinSketch;
+//!
 //! let buckets = CountMinSketch::<i64>::suggest_num_buckets(0.01);
 //! let hashes = CountMinSketch::<i64>::suggest_num_hashes(0.99);
 //! let sketch = CountMinSketch::<i64>::new(hashes, buckets);

datasketches/src/countmin/sketch.rs

@@ -63,7 +63,8 @@ impl<T: CountMinValue> CountMinSketch<T> {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::countmin::CountMinSketch;
+    /// use datasketches::countmin::CountMinSketch;
+    ///
     /// let sketch = CountMinSketch::<i64>::new(4, 128);
     /// assert_eq!(sketch.num_buckets(), 128);
     /// ```
@@ -84,7 +85,8 @@ impl<T: CountMinValue> CountMinSketch<T> {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::countmin::CountMinSketch;
+    /// use datasketches::countmin::CountMinSketch;
+    ///
     /// let sketch = CountMinSketch::<i64>::with_seed(4, 64, 42);
     /// assert_eq!(sketch.seed(), 42);
     /// ```
@@ -155,7 +157,8 @@ impl<T: CountMinValue> CountMinSketch<T> {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::countmin::CountMinSketch;
+    /// use datasketches::countmin::CountMinSketch;
+    ///
     /// let mut sketch = CountMinSketch::<i64>::new(4, 128);
     /// sketch.update("apple");
     /// assert!(sketch.estimate("apple") >= 1);
@@ -169,7 +172,8 @@ impl<T: CountMinValue> CountMinSketch<T> {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::countmin::CountMinSketch;
+    /// use datasketches::countmin::CountMinSketch;
+    ///
     /// let mut sketch = CountMinSketch::<i64>::new(4, 128);
     /// sketch.update_with_weight("banana", 3);
     /// assert!(sketch.estimate("banana") >= 3);
@@ -193,7 +197,8 @@ impl<T: CountMinValue> CountMinSketch<T> {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::countmin::CountMinSketch;
+    /// use datasketches::countmin::CountMinSketch;
+    ///
     /// let mut sketch = CountMinSketch::<i64>::new(4, 128);
     /// sketch.update_with_weight("pear", 2);
     /// assert!(sketch.estimate("pear") >= 2);
@@ -233,7 +238,8 @@ impl<T: CountMinValue> CountMinSketch<T> {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::countmin::CountMinSketch;
+    /// use datasketches::countmin::CountMinSketch;
+    ///
     /// let mut left = CountMinSketch::<i64>::new(4, 128);
     /// let mut right = CountMinSketch::<i64>::new(4, 128);
     ///
@@ -263,9 +269,10 @@ impl<T: CountMinValue> CountMinSketch<T> {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::countmin::CountMinSketch;
-    /// # let mut sketch = CountMinSketch::<i64>::new(4, 128);
-    /// # sketch.update("apple");
+    /// use datasketches::countmin::CountMinSketch;
+    ///
+    /// let mut sketch = CountMinSketch::<i64>::new(4, 128);
+    /// sketch.update("apple");
     /// let bytes = sketch.serialize();
     /// let decoded = CountMinSketch::<i64>::deserialize(&bytes).unwrap();
     /// assert!(decoded.estimate("apple") >= 1);
@@ -308,10 +315,11 @@ impl<T: CountMinValue> CountMinSketch<T> {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::countmin::CountMinSketch;
-    /// # let mut sketch = CountMinSketch::<i64>::new(4, 64);
-    /// # sketch.update("apple");
-    /// # let bytes = sketch.serialize();
+    /// use datasketches::countmin::CountMinSketch;
+    ///
+    /// let mut sketch = CountMinSketch::<i64>::new(4, 64);
+    /// sketch.update("apple");
+    /// let bytes = sketch.serialize();
     /// let decoded = CountMinSketch::<i64>::deserialize(&bytes).unwrap();
     /// assert!(decoded.estimate("apple") >= 1);
     /// ```
@@ -324,10 +332,11 @@ impl<T: CountMinValue> CountMinSketch<T> {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::countmin::CountMinSketch;
-    /// # let mut sketch = CountMinSketch::<i64>::with_seed(4, 64, 7);
-    /// # sketch.update("apple");
-    /// # let bytes = sketch.serialize();
+    /// use datasketches::countmin::CountMinSketch;
+    ///
+    /// let mut sketch = CountMinSketch::<i64>::with_seed(4, 64, 7);
+    /// sketch.update("apple");
+    /// let bytes = sketch.serialize();
     /// let decoded = CountMinSketch::<i64>::deserialize_with_seed(&bytes, 7).unwrap();
     /// assert!(decoded.estimate("apple") >= 1);
     /// ```
@@ -425,7 +434,8 @@ impl<T: UnsignedCountMinValue> CountMinSketch<T> {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::countmin::CountMinSketch;
+    /// use datasketches::countmin::CountMinSketch;
+    ///
     /// let mut sketch = CountMinSketch::<u64>::new(4, 128);
     /// sketch.update_with_weight("apple", 3);
     /// sketch.halve();
@@ -446,7 +456,8 @@ impl<T: UnsignedCountMinValue> CountMinSketch<T> {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::countmin::CountMinSketch;
+    /// use datasketches::countmin::CountMinSketch;
+    ///
     /// let mut sketch = CountMinSketch::<u64>::new(4, 128);
     /// sketch.update_with_weight("apple", 3);
     /// sketch.decay(0.5);

datasketches/src/cpc/sketch.rs

@@ -171,24 +171,24 @@ impl CpcSketch {
 
     /// Update the sketch with a hashable value.
     ///
-    /// You may use [`hash_value`](crate::hash_value) wrappers when matching other datasketches
-    /// implementations require a specific value hashing strategy.
+    /// You may use [`hash::value`](crate::hash::value) wrappers when another DataSketches
+    /// implementation requires a specific value hashing strategy.
     ///
     /// # Examples
     ///
     /// ```rust
     /// use datasketches::cpc::CpcSketch;
-    /// use datasketches::hash_value;
+    /// use datasketches::hash::value::canonical_float;
     ///
     /// let mut sketch = CpcSketch::with_seed(11, 123);
     /// sketch.update(1);
     /// sketch.update(2);
     /// sketch.update(3);
     ///
     /// let mut sketch = CpcSketch::with_seed(11, 123);
-    /// sketch.update(hash_value::canonical_float::from_f64(1.5));
-    /// sketch.update(hash_value::canonical_float::from_f64(2.5));
-    /// sketch.update(hash_value::canonical_float::from_f64(3.5));
+    /// sketch.update(canonical_float::from_f64(1.5));
+    /// sketch.update(canonical_float::from_f64(2.5));
+    /// sketch.update(canonical_float::from_f64(3.5));
     /// ```
     pub fn update<T: Hash>(&mut self, value: T) {
         let mut hasher = MurmurHash3X64128::with_seed(self.seed);

datasketches/src/cpc/union.rs

@@ -121,8 +121,8 @@ impl CpcUnion {
     /// # Examples
     ///
     /// ```
-    /// # use datasketches::cpc::CpcUnion;
-    /// # use datasketches::cpc::CpcSketch;
+    /// use datasketches::cpc::CpcSketch;
+    /// use datasketches::cpc::CpcUnion;
     ///
     /// let mut s1 = CpcSketch::new(12);
     /// s1.update(&"apple");