This is an automated email from the ASF dual-hosted git repository.
tisonkun pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datasketches-rust.git
The following commit(s) were added to refs/heads/main by this push:
new 612a77c refactor(frequencies): rename update_with_count to
update_with_weight (#348)
612a77c is described below
commit 612a77ca9540180f37323c33960ff08c1e333636
Author: tison <[email protected]>
AuthorDate: Thu Nov 12 08:44:41 2026 +0800
refactor(frequencies): rename update_with_count to update_with_weight (#348)
---
CHANGELOG.md | 1 +
datasketches/src/frequencies/mod.rs | 4 +-
datasketches/src/frequencies/sketch.rs | 61 +++++++++++-----------
tests-integration/tests/frequencies_test/update.rs | 28 +++++-----
tests-integration/tests/serde_tests/frequencies.rs | 14 ++---
5 files changed, 55 insertions(+), 53 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 95d631a..910b81d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ All significant changes to this project will be documented in
this file.
* `BloomFilter::contains` and `BloomFilter::contains_and_insert` now take
`item: T` (`T: Hash`) by value instead of `&T`, matching `BloomFilter::insert`.
Pass `&item` to retain owned values such as `String` or `Vec<u8>` without
cloning, and remove explicit turbofish type arguments (or change `T` to `&T`)
on borrowed calls such as `contains::<u64>(&value)`.
* `CountMinSketch::new` and `CountMinSketch::with_seed` now create serial
version 2 sketches, require `num_hashes` in `1..=127`, and emit images that
require a version 2 reader. Version 2 enables cross-language interchange when
using `i64` counters and the documented input encodings, while existing version
1 images remain readable, updatable, and serializable as version 1.
`CountMinSketch::merge` rejects mixing version 1 and version 2 sketches;
upgrade readers before writers and rebuild [...]
* `CpcSketch::max_serialized_bytes` and `ReqSketch::serialized_size_bytes` are
removed; serialize the sketch and inspect `len()` on the returned byte buffer
when the encoded size is needed.
+* `FrequentItemsSketch::update_with_count` and
`FrequentItemsSketch::update_with_count_ref` are renamed to
`update_with_weight` and `update_with_weight_ref` to match weighted update
naming across the crate.
### New features
diff --git a/datasketches/src/frequencies/mod.rs
b/datasketches/src/frequencies/mod.rs
index b8ffdf8..0baf640 100644
--- a/datasketches/src/frequencies/mod.rs
+++ b/datasketches/src/frequencies/mod.rs
@@ -80,7 +80,7 @@
//! use datasketches::frequencies::FrequentItemsSketch;
//!
//! let mut sketch = FrequentItemsSketch::<i64>::new(64).unwrap();
-//! sketch.update_with_count(1, 3);
+//! sketch.update_with_weight(1, 3);
//! sketch.update(2);
//! let rows = sketch.frequent_items(ErrorType::NoFalseNegatives);
//! assert!(rows.iter().any(|row| *row.item() == 1));
@@ -95,7 +95,7 @@
//! use datasketches::frequencies::FrequentItemsSketch;
//!
//! let mut sketch = FrequentItemsSketch::<i64>::new(64).unwrap();
-//! sketch.update_with_count(42, 2);
+//! sketch.update_with_weight(42, 2);
//!
//! let bytes = sketch.serialize();
//! let decoded = FrequentItemsSketch::<i64>::deserialize(&bytes).unwrap();
diff --git a/datasketches/src/frequencies/sketch.rs
b/datasketches/src/frequencies/sketch.rs
index 617b98e..0ecb50e 100644
--- a/datasketches/src/frequencies/sketch.rs
+++ b/datasketches/src/frequencies/sketch.rs
@@ -193,7 +193,8 @@ impl<T: Eq + Hash> FrequentItemsSketch<T> {
/// Returns the total weight of the stream.
///
- /// This is the sum of all counts passed to `update` and
`update_with_count`.
+ /// This is the sum of all weights passed to `update`,
`update_with_weight`, `update_ref`, and
+ /// `update_with_weight_ref`.
pub fn total_weight(&self) -> u64 {
self.stream_weight
}
@@ -208,7 +209,7 @@ impl<T: Eq + Hash> FrequentItemsSketch<T> {
/// use datasketches::frequencies::FrequentItemsSketch;
///
/// let mut sketch = FrequentItemsSketch::<i64>::new(64).unwrap();
- /// sketch.update_with_count(10, 2);
+ /// sketch.update_with_weight(10, 2);
/// assert!(sketch.estimate(&10) >= 2);
/// ```
pub fn estimate<Q>(&self, item: &Q) -> u64
@@ -328,7 +329,7 @@ impl<T: Eq + Hash> FrequentItemsSketch<T> {
self.hash_map.estimated_size()
}
- /// Updates the sketch with a count of one.
+ /// Updates the sketch with a weight of one.
///
/// # Panics
///
@@ -344,12 +345,12 @@ impl<T: Eq + Hash> FrequentItemsSketch<T> {
/// assert!(sketch.estimate(&42) >= 1);
/// ```
pub fn update(&mut self, item: T) {
- self.update_with_count(item, 1);
+ self.update_with_weight(item, 1);
}
- /// Updates the sketch with an item and count.
+ /// Updates the sketch with an item and weight.
///
- /// A count of zero is a no-op.
+ /// A weight of zero is a no-op.
///
/// # Panics
///
@@ -361,22 +362,22 @@ impl<T: Eq + Hash> FrequentItemsSketch<T> {
/// use datasketches::frequencies::FrequentItemsSketch;
///
/// let mut sketch = FrequentItemsSketch::<i64>::new(64).unwrap();
- /// sketch.update_with_count(10, 3);
+ /// sketch.update_with_weight(10, 3);
/// assert!(sketch.estimate(&10) >= 3);
/// ```
- pub fn update_with_count(&mut self, item: T, count: u64) {
- if count == 0 {
+ pub fn update_with_weight(&mut self, item: T, weight: u64) {
+ if weight == 0 {
return;
}
self.stream_weight = self
.stream_weight
- .checked_add(count)
+ .checked_add(weight)
.expect("total stream weight overflow");
- self.hash_map.adjust_or_put_value(item, count);
+ self.hash_map.adjust_or_put_value(item, weight);
self.maybe_resize_or_purge();
}
- /// Updates the sketch with a borrowed item and a count of one.
+ /// Updates the sketch with a borrowed item and a weight of one.
///
/// Equivalent to [`update`](Self::update) but takes the item by reference
and
/// only allocates an owned item when it is newly inserted, so updating an
@@ -401,14 +402,14 @@ impl<T: Eq + Hash> FrequentItemsSketch<T> {
T: Borrow<Q>,
Q: Eq + Hash + ToOwned<Owned = T> + ?Sized,
{
- self.update_with_count_ref(item, 1);
+ self.update_with_weight_ref(item, 1);
}
- /// Updates the sketch with a borrowed item and count.
+ /// Updates the sketch with a borrowed item and weight.
///
- /// Equivalent to [`update_with_count`](Self::update_with_count) but takes
the
+ /// Equivalent to [`update_with_weight`](Self::update_with_weight) but
takes the
/// item by reference and only allocates an owned item when it is newly
- /// inserted. A count of zero is a no-op.
+ /// inserted. A weight of zero is a no-op.
///
/// # Panics
///
@@ -420,22 +421,22 @@ impl<T: Eq + Hash> FrequentItemsSketch<T> {
/// use datasketches::frequencies::FrequentItemsSketch;
///
/// let mut sketch = FrequentItemsSketch::<String>::new(64).unwrap();
- /// sketch.update_with_count_ref("gzip", 3);
+ /// sketch.update_with_weight_ref("gzip", 3);
/// assert!(sketch.estimate("gzip") >= 3);
/// ```
- pub fn update_with_count_ref<Q>(&mut self, item: &Q, count: u64)
+ pub fn update_with_weight_ref<Q>(&mut self, item: &Q, weight: u64)
where
T: Borrow<Q>,
Q: Eq + Hash + ToOwned<Owned = T> + ?Sized,
{
- if count == 0 {
+ if weight == 0 {
return;
}
self.stream_weight = self
.stream_weight
- .checked_add(count)
+ .checked_add(weight)
.expect("total stream weight overflow");
- self.hash_map.adjust_or_put_value_ref(item, count);
+ self.hash_map.adjust_or_put_value_ref(item, weight);
self.maybe_resize_or_purge();
}
@@ -456,7 +457,7 @@ impl<T: Eq + Hash> FrequentItemsSketch<T> {
/// let mut left = FrequentItemsSketch::<i64>::new(64).unwrap();
/// let mut right = FrequentItemsSketch::<i64>::new(64).unwrap();
/// left.update(1);
- /// right.update_with_count(2, 2);
+ /// right.update_with_weight(2, 2);
/// left.merge(&right);
/// assert!(left.estimate(&2) >= 2);
/// ```
@@ -472,7 +473,7 @@ impl<T: Eq + Hash> FrequentItemsSketch<T> {
.checked_add(other.stream_weight)
.expect("total stream weight overflow");
for (item, count) in other.hash_map.iter() {
- self.update_with_count_ref(item, count);
+ self.update_with_weight_ref(item, count);
}
self.offset += other.offset;
self.stream_weight = merged_total;
@@ -494,7 +495,7 @@ impl<T: Eq + Hash> FrequentItemsSketch<T> {
/// use datasketches::frequencies::FrequentItemsSketch;
///
/// let mut sketch = FrequentItemsSketch::<i64>::new(64).unwrap();
- /// sketch.update_with_count(1, 5);
+ /// sketch.update_with_weight(1, 5);
/// sketch.update(2);
/// let rows = sketch.frequent_items(ErrorType::NoFalseNegatives);
/// assert!(rows.iter().any(|row| *row.item() == 1));
@@ -520,7 +521,7 @@ impl<T: Eq + Hash> FrequentItemsSketch<T> {
/// use datasketches::frequencies::FrequentItemsSketch;
///
/// let mut sketch = FrequentItemsSketch::<i64>::new(64).unwrap();
- /// sketch.update_with_count(1, 5);
+ /// sketch.update_with_weight(1, 5);
/// sketch.update(2);
/// let rows =
sketch.frequent_items_with_threshold(ErrorType::NoFalsePositives, 3);
/// assert!(rows.iter().any(|row| *row.item() == 1));
@@ -743,7 +744,7 @@ impl<T: Eq + Hash> FrequentItemsSketch<T> {
let mut sketch = Self::with_lg_map_sizes(lg_max, lg_cur);
for (item, value) in items.into_iter().zip(values) {
- sketch.update_with_count(item, value);
+ sketch.update_with_weight(item, value);
}
sketch.stream_weight = stream_weight;
sketch.offset = offset_val;
@@ -765,7 +766,7 @@ impl<T: FrequentItemValue> FrequentItemsSketch<T> {
/// use datasketches::frequencies::FrequentItemsSketch;
///
/// let mut sketch = FrequentItemsSketch::<i64>::new(64).unwrap();
- /// sketch.update_with_count(7, 2);
+ /// sketch.update_with_weight(7, 2);
/// let bytes = sketch.serialize();
/// let decoded = FrequentItemsSketch::<i64>::deserialize(&bytes).unwrap();
/// assert!(decoded.estimate(&7) >= 2);
@@ -778,7 +779,7 @@ impl<T: FrequentItemValue> FrequentItemsSketch<T> {
///
/// let mut sketch = FrequentItemsSketch::<String>::new(64).unwrap();
/// let apple = "apple".to_string();
- /// sketch.update_with_count(apple.clone(), 2);
+ /// sketch.update_with_weight(apple.clone(), 2);
/// let bytes = sketch.serialize();
/// let decoded =
FrequentItemsSketch::<String>::deserialize(&bytes).unwrap();
/// assert!(decoded.estimate(&apple) >= 2);
@@ -805,7 +806,7 @@ impl<T: FrequentItemValue> FrequentItemsSketch<T> {
/// use datasketches::frequencies::FrequentItemsSketch;
///
/// let mut sketch = FrequentItemsSketch::<i64>::new(64).unwrap();
- /// sketch.update_with_count(7, 2);
+ /// sketch.update_with_weight(7, 2);
/// let bytes = sketch.serialize();
/// let decoded = FrequentItemsSketch::<i64>::deserialize(&bytes).unwrap();
/// assert!(decoded.estimate(&7) >= 2);
@@ -818,7 +819,7 @@ impl<T: FrequentItemValue> FrequentItemsSketch<T> {
///
/// let mut sketch = FrequentItemsSketch::<String>::new(64).unwrap();
/// let apple = "apple".to_string();
- /// sketch.update_with_count(apple.clone(), 2);
+ /// sketch.update_with_weight(apple.clone(), 2);
/// let bytes = sketch.serialize();
/// let decoded =
FrequentItemsSketch::<String>::deserialize(&bytes).unwrap();
/// assert!(decoded.estimate(&apple) >= 2);
diff --git a/tests-integration/tests/frequencies_test/update.rs
b/tests-integration/tests/frequencies_test/update.rs
index 4dec64e..82d6b40 100644
--- a/tests-integration/tests/frequencies_test/update.rs
+++ b/tests-integration/tests/frequencies_test/update.rs
@@ -32,7 +32,7 @@ use googletest::prelude::near;
#[test]
fn test_longs_update_with_zero_count_is_noop() {
let mut sketch: FrequentItemsSketch<i64> =
FrequentItemsSketch::new(8).unwrap();
- sketch.update_with_count(1, 0);
+ sketch.update_with_weight(1, 0);
assert!(sketch.is_empty());
assert_eq!(sketch.total_weight(), 0);
@@ -87,8 +87,8 @@ fn test_items_borrowed_key_updates_and_queries() {
sketch.update_ref("alpha");
sketch.update_ref("alpha");
- sketch.update_with_count_ref("beta", 3);
- sketch.update_with_count_ref("ignored", 0);
+ sketch.update_with_weight_ref("beta", 3);
+ sketch.update_with_weight_ref("ignored", 0);
for item in [
"gamma", "delta", "epsilon", "zeta", "eta", "theta", "iota", "kappa",
"lambda", "mu",
] {
@@ -198,11 +198,11 @@ fn test_items_several_items_with_resize_no_purge() {
#[test]
fn test_longs_estimation_mode() {
let mut sketch: FrequentItemsSketch<i64> =
FrequentItemsSketch::new(8).unwrap();
- sketch.update_with_count(1, 10);
+ sketch.update_with_weight(1, 10);
for item in 2..=6 {
sketch.update(item);
}
- sketch.update_with_count(7, 15);
+ sketch.update_with_weight(7, 15);
for item in 8..=12 {
sketch.update(item);
}
@@ -226,7 +226,7 @@ fn test_longs_estimation_mode() {
#[test]
fn test_longs_purge_keeps_heavy_hitters() {
let mut sketch: FrequentItemsSketch<i64> =
FrequentItemsSketch::new(8).unwrap();
- sketch.update_with_count(1, 10);
+ sketch.update_with_weight(1, 10);
for item in 2..=7 {
sketch.update(item);
}
@@ -245,7 +245,7 @@ fn test_longs_purge_keeps_heavy_hitters() {
#[test]
fn test_longs_merge_estimation_mode() {
let mut sketch1: FrequentItemsSketch<i64> =
FrequentItemsSketch::new(16).unwrap();
- sketch1.update_with_count(1, 9);
+ sketch1.update_with_weight(1, 9);
for item in 2..=14 {
sketch1.update(item);
}
@@ -255,7 +255,7 @@ fn test_longs_merge_estimation_mode() {
for item in 8..=20 {
sketch2.update(item);
}
- sketch2.update_with_count(21, 11);
+ sketch2.update_with_weight(21, 11);
assert_that!(sketch2.maximum_error(), gt(0));
sketch1.merge(&sketch2);
@@ -345,7 +345,7 @@ fn test_purged_state_survives_merge_and_reset() {
#[test]
fn test_update_weight_overflow_preserves_state() {
let mut sketch = FrequentItemsSketch::<String>::new(8).unwrap();
- sketch.update_with_count_ref("a", u64::MAX - 1);
+ sketch.update_with_weight_ref("a", u64::MAX - 1);
sketch.update("b".to_string());
assert_eq!(sketch.total_weight(), u64::MAX);
let before = sketch.serialize();
@@ -360,7 +360,7 @@ fn test_update_weight_overflow_preserves_state() {
#[test]
fn test_merge_weight_overflow_preserves_state() {
let mut sketch = FrequentItemsSketch::<i64>::new(8).unwrap();
- sketch.update_with_count(1, u64::MAX - 7);
+ sketch.update_with_weight(1, u64::MAX - 7);
let mut purged = FrequentItemsSketch::<i64>::new(8).unwrap();
for item in 0..7 {
purged.update(item);
@@ -379,8 +379,8 @@ fn test_merge_weight_overflow_preserves_state() {
#[test]
fn test_longs_reset() {
let mut sketch: FrequentItemsSketch<i64> =
FrequentItemsSketch::new(8).unwrap();
- sketch.update_with_count(1, 3);
- sketch.update_with_count(2, 2);
+ sketch.update_with_weight(1, 3);
+ sketch.update_with_weight(2, 2);
sketch.reset();
assert!(sketch.is_empty());
@@ -420,13 +420,13 @@ fn test_colliding_items_preserve_frequency_bounds() {
*count = 100;
}
for (item, &count) in counts.iter().enumerate() {
- sketch.update_with_count(CollidingItem(item), count);
+ sketch.update_with_weight(CollidingItem(item), count);
}
assert!(sketch.maximum_error() > 0);
// Exercise subsequent updates to both a heavy hitter and a light item.
for item in [0, 1] {
- sketch.update_with_count(CollidingItem(item), 10);
+ sketch.update_with_weight(CollidingItem(item), 10);
counts[item] += 10;
}
assert_eq!(sketch.total_weight(), counts.iter().sum::<u64>());
diff --git a/tests-integration/tests/serde_tests/frequencies.rs
b/tests-integration/tests/serde_tests/frequencies.rs
index 9c1df36..d78bdca 100644
--- a/tests-integration/tests/serde_tests/frequencies.rs
+++ b/tests-integration/tests/serde_tests/frequencies.rs
@@ -55,7 +55,7 @@ impl FrequentItemValue for NonCloneSerializableItem {
fn test_longs_round_trip() {
let mut sketch: FrequentItemsSketch<i64> =
FrequentItemsSketch::new(32).unwrap();
for i in 1..=100 {
- sketch.update_with_count(i, i as u64);
+ sketch.update_with_weight(i, i as u64);
}
let bytes = sketch.serialize();
let restored = FrequentItemsSketch::<i64>::deserialize(&bytes).unwrap();
@@ -67,9 +67,9 @@ fn test_longs_round_trip() {
#[test]
fn test_items_round_trip() {
let mut sketch = FrequentItemsSketch::new(32).unwrap();
- sketch.update_with_count("alpha".to_string(), 3);
- sketch.update_with_count("beta".to_string(), 5);
- sketch.update_with_count("gamma".to_string(), 7);
+ sketch.update_with_weight("alpha".to_string(), 3);
+ sketch.update_with_weight("beta".to_string(), 5);
+ sketch.update_with_weight("gamma".to_string(), 7);
let bytes = sketch.serialize();
let restored = FrequentItemsSketch::<String>::deserialize(&bytes).unwrap();
@@ -94,8 +94,8 @@ fn test_string_deserialize_rejects_length_larger_than_input()
{
#[test]
fn test_non_clone_item_round_trip() {
let mut sketch =
FrequentItemsSketch::<NonCloneSerializableItem>::new(32).unwrap();
- sketch.update_with_count(NonCloneSerializableItem(1), 2);
- sketch.update_with_count(NonCloneSerializableItem(2), 5);
+ sketch.update_with_weight(NonCloneSerializableItem(1), 2);
+ sketch.update_with_weight(NonCloneSerializableItem(2), 5);
let bytes = sketch.serialize();
let restored =
FrequentItemsSketch::<NonCloneSerializableItem>::deserialize(&bytes).unwrap();
@@ -192,7 +192,7 @@ fn test_java_frequent_strings_purged() {
#[test]
fn test_deserialize_rejects_zero_stream_weight() {
let mut active_sketch = FrequentItemsSketch::<i64>::new(32).unwrap();
- active_sketch.update_with_count(7, 3);
+ active_sketch.update_with_weight(7, 3);
let mut purged_sketch = FrequentItemsSketch::<i64>::new(32).unwrap();
for item in 0..=(32 * 3 / 4) {
purged_sketch.update(item);
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]