fulmicoton commented on code in PR #116:
URL: https://github.com/apache/datasketches-rust/pull/116#discussion_r3094140674
##########
datasketches/src/hll/mod.rs:
##########
@@ -157,52 +157,102 @@ const COUPON_RSE: f64 = COUPON_RSE_FACTOR / (1 << 13) as
f64;
const RESIZE_NUMERATOR: u32 = 3; // Resize at 3/4 = 75% load factor
const RESIZE_DENOMINATOR: u32 = 4;
-/// Extract slot number (low 26 bits) from coupon
-#[inline]
-fn get_slot(coupon: u32) -> u32 {
- coupon & KEY_MASK_26
-}
+/// A coupon encodes a (slot, value) pair derived from hashing an input.
+///
+/// Format: `[value (6 bits) << 26] | [slot (26 bits)]`
+///
+/// The slot identifies an HLL register (derived from the lower bits of the
hash),
+/// and the value represents the number of leading zeros plus one (from the
upper bits).
+///
+/// Pre-computing coupons is useful when the same logical value must be
inserted into
+/// multiple independent sketches, because the (relatively expensive) hash
step is paid
+/// only once. A common pattern is dictionary-encoded data: compute the
coupon for each
+/// term id up front, cache it, and then call
[`HllSketch::update_with_coupon`] for
+/// each per-bucket sketch rather than calling [`HllSketch::update`]
repeatedly with the
+/// decoded string.
+///
+/// # Examples
+///
+/// ```
+/// # use datasketches::hll::{HllSketch, HllType, Coupon};
+/// let c = Coupon::from_hash("hello");
+///
+/// let mut sketch1 = HllSketch::new(10, HllType::Hll8);
+/// let mut sketch2 = HllSketch::new(12, HllType::Hll8);
+/// sketch1.update_with_coupon(c);
+/// sketch2.update_with_coupon(c);
+///
+/// assert!(sketch1.estimate() >= 1.0);
+/// assert!(sketch2.estimate() >= 1.0);
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Coupon(u32);
-/// Extract value (upper 6 bits) from coupon
-#[inline]
-fn get_value(coupon: u32) -> u8 {
- (coupon >> KEY_BITS_26) as u8
-}
+impl Coupon {
+ /// Sentinel value indicating an empty coupon slot.
+ const EMPTY: Self = Coupon(0);
Review Comment:
I think it is worth making EMPTY pub (if possible)
```suggestion
pub const EMPTY: Self = Coupon(0);
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
