Merge branch 'main' into density

Author: tisonkun

.github/workflows/ci.yml

@@ -85,19 +85,6 @@ jobs:
         run: |
           rustup toolchain install ${{ matrix.rust-version }}
           rustup default ${{ matrix.rust-version }}
-      - name: Run examples
-        shell: bash
-        working-directory: examples
-        run: |
-          set -x
-          METADATA=$( cargo metadata --format-version=1 --no-deps )
-          EXAMPLES=$( echo "$METADATA" | jq -r '.packages[] | select(.name == "examples") | .targets[].name' | tr -d '\r' )
-          while read -r example; do
-            if [ -n "$example" ]; then
-              echo "Running example: $example"
-              cargo run --bin "$example"
-            fi
-          done <<< "$EXAMPLES"
       - name: Setup Java
         uses: actions/setup-java@v5
         with:

Cargo.lock

@@ -16,7 +16,7 @@
 # under the License.
 
 [workspace]
-members = ["datasketches", "examples", "xtask"]
+members = ["datasketches", "xtask"]
 resolver = "3"
 
 [workspace.package]

Cargo.toml

@@ -1,5 +1,5 @@
 Apache DataSketches Rust
-Copyright 2025 The Apache Software Foundation
+Copyright 2025-2026 The Apache Software Foundation
 
 This product includes software developed at
 The Apache Software Foundation (http://www.apache.org/).

NOTICE

@@ -27,10 +27,8 @@ use crate::codec::assert::insufficient_data;
 use crate::codec::family::Family;
 use crate::common::NumStdDev;
 use crate::error::Error;
+use crate::hll::Coupon;
 use crate::hll::estimator::HipEstimator;
-use crate::hll::get_slot;
-use crate::hll::get_value;
-use crate::hll::pack_coupon;
 use crate::hll::serialization::COUPON_SIZE_BYTES;
 use crate::hll::serialization::CUR_MODE_HLL;
 use crate::hll::serialization::HLL_PREAMBLE_SIZE;
@@ -130,10 +128,10 @@ impl Array4 {
         };
     }
 
-    pub fn update(&mut self, coupon: u32) {
+    pub fn update(&mut self, coupon: Coupon) {
         let mask = (1 << self.lg_config_k) - 1;
-        let slot = get_slot(coupon) & mask;
-        let new_value = get_value(coupon);
+        let slot = coupon.slot() & mask;
+        let new_value = coupon.value();
 
         // Quick rejection: if new value <= cur_min, no update needed
         if new_value <= self.cur_min {
@@ -341,8 +339,9 @@ impl Array4 {
                         "expected {aux_count} aux coupons, failed at index {i}",
                     ))
                 })?;
-                let slot = get_slot(coupon) & ((1 << lg_config_k) - 1);
-                let value = get_value(coupon);
+                let coupon = Coupon(coupon);
+                let slot = coupon.slot() & ((1 << lg_config_k) - 1);
+                let value = coupon.value();
                 aux.insert(slot, value);
             }
             aux_map = Some(aux);
@@ -418,8 +417,7 @@ impl Array4 {
 
         // Write aux map entries if present
         for (slot, value) in aux_entries.iter().copied() {
-            let coupon = pack_coupon(slot, value);
-            bytes.write_u32_le(coupon);
+            bytes.write_u32_le(Coupon::pack(slot, value).raw());
         }
 
         bytes.into_bytes()
@@ -429,8 +427,7 @@ impl Array4 {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::hll::coupon;
-    use crate::hll::pack_coupon;
+    use crate::hll::Coupon;
 
     #[test]
     fn test_get_set_raw() {
@@ -463,8 +460,7 @@ mod tests {
 
         // Add some unique values to different slots
         for i in 0..10_000u32 {
-            let coupon = coupon(i);
-            arr.update(coupon);
+            arr.update(Coupon::from_hash(i));
         }
 
         // Estimate should be positive and roughly in the ballpark
@@ -492,8 +488,8 @@ mod tests {
         let mut arr = Array4::new(8); // 256 buckets
 
         // Test that values < 32 and >= 32 are handled correctly
-        arr.update(pack_coupon(0, 10)); // value < 32, goes to kxq0
-        arr.update(pack_coupon(1, 40)); // value >= 32, goes to kxq1
+        arr.update(Coupon::pack(0, 10)); // value < 32, goes to kxq0
+        arr.update(Coupon::pack(1, 40)); // value >= 32, goes to kxq1
 
         // Verify registers were updated (not exact values, just check they changed)
         // kxq0 should have decreased (we removed a 0 and added a 10)

datasketches/src/hll/array4.rs

@@ -27,9 +27,8 @@ use crate::codec::assert::insufficient_data;
 use crate::codec::family::Family;
 use crate::common::NumStdDev;
 use crate::error::Error;
+use crate::hll::Coupon;
 use crate::hll::estimator::HipEstimator;
-use crate::hll::get_slot;
-use crate::hll::get_value;
 use crate::hll::serialization::CUR_MODE_HLL;
 use crate::hll::serialization::HLL_PREAMBLE_SIZE;
 use crate::hll::serialization::HLL_PREINTS;
@@ -124,10 +123,10 @@ impl Array6 {
     }
 
     /// Update with a coupon
-    pub fn update(&mut self, coupon: u32) {
+    pub fn update(&mut self, coupon: Coupon) {
         let mask = (1 << self.lg_config_k) - 1;
-        let slot = get_slot(coupon) & mask;
-        let new_value = get_value(coupon);
+        let slot = coupon.slot() & mask;
+        let new_value = coupon.value();
 
         let old_value = self.get_raw(slot);
 
@@ -285,8 +284,7 @@ fn num_bytes_for_k(k: u32) -> usize {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::hll::coupon;
-    use crate::hll::pack_coupon;
+    use crate::hll::Coupon;
 
     #[test]
     fn test_num_bytes_calculation() {
@@ -358,8 +356,7 @@ mod tests {
 
         // Add some unique values using real coupon hashing
         for i in 0..10_000u32 {
-            let coupon = coupon(i);
-            arr.update(coupon);
+            arr.update(Coupon::from_hash(i));
         }
 
         let estimate = arr.estimate();
@@ -392,8 +389,8 @@ mod tests {
         let mut arr = Array6::new(8); // 256 buckets
 
         // Test that values < 32 and >= 32 are handled correctly
-        arr.update(pack_coupon(0, 10)); // value < 32, goes to kxq0
-        arr.update(pack_coupon(1, 40)); // value >= 32, goes to kxq1
+        arr.update(Coupon::pack(0, 10)); // value < 32, goes to kxq0
+        arr.update(Coupon::pack(1, 40)); // value >= 32, goes to kxq1
 
         // Initial kxq0 = 256 (all zeros = 1.0 each)
         assert!(arr.estimator.kxq0() < 256.0, "kxq0 should have decreased");

datasketches/src/hll/array6.rs

@@ -26,9 +26,8 @@ use crate::codec::assert::insufficient_data;
 use crate::codec::family::Family;
 use crate::common::NumStdDev;
 use crate::error::Error;
+use crate::hll::Coupon;
 use crate::hll::estimator::HipEstimator;
-use crate::hll::get_slot;
-use crate::hll::get_value;
 use crate::hll::serialization::CUR_MODE_HLL;
 use crate::hll::serialization::HLL_PREAMBLE_SIZE;
 use crate::hll::serialization::HLL_PREINTS;
@@ -78,10 +77,10 @@ impl Array8 {
     }
 
     /// Update with a coupon
-    pub fn update(&mut self, coupon: u32) {
+    pub fn update(&mut self, coupon: Coupon) {
         let mask = (1 << self.lg_config_k) - 1;
-        let slot = get_slot(coupon) & mask;
-        let new_value = get_value(coupon);
+        let slot = coupon.slot() & mask;
+        let new_value = coupon.value();
 
         let old_value = self.get(slot);
 
@@ -350,8 +349,7 @@ impl Array8 {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::hll::coupon;
-    use crate::hll::pack_coupon;
+    use crate::hll::Coupon;
 
     #[test]
     fn test_array8_basic() {
@@ -391,20 +389,20 @@ mod tests {
         let mut arr = Array8::new(4);
 
         // Update slot 0 with value 5
-        arr.update(pack_coupon(0, 5));
+        arr.update(Coupon::pack(0, 5));
         assert_eq!(arr.get(0), 5);
 
         // Update with a smaller value (should be ignored)
-        arr.update(pack_coupon(0, 3));
+        arr.update(Coupon::pack(0, 3));
         assert_eq!(arr.get(0), 5);
 
         // Update with a larger value
-        arr.update(pack_coupon(0, 42));
+        arr.update(Coupon::pack(0, 42));
         assert_eq!(arr.get(0), 42);
 
         // Test value at max coupon range (63)
-        // Note: pack_coupon only stores 6 bits (0-63)
-        arr.update(pack_coupon(1, 63));
+        // Note: Coupon::pack only stores 6 bits (0-63)
+        arr.update(Coupon::pack(1, 63));
         assert_eq!(arr.get(1), 63);
     }
 
@@ -417,8 +415,7 @@ mod tests {
 
         // Add some unique values using real coupon hashing
         for i in 0..10_000u32 {
-            let coupon = coupon(i);
-            arr.update(coupon);
+            arr.update(Coupon::from_hash(i));
         }
 
         let estimate = arr.estimate();
@@ -471,8 +468,8 @@ mod tests {
         let mut arr = Array8::new(8); // 256 buckets
 
         // Test that values < 32 and >= 32 are handled correctly
-        arr.update(pack_coupon(0, 10)); // value < 32, goes to kxq0
-        arr.update(pack_coupon(1, 50)); // value >= 32, goes to kxq1
+        arr.update(Coupon::pack(0, 10)); // value < 32, goes to kxq0
+        arr.update(Coupon::pack(1, 50)); // value >= 32, goes to kxq1
 
         // Initial kxq0 = 256 (all zeros = 1.0 each)
         assert!(arr.estimator.kxq0() < 256.0, "kxq0 should have decreased");