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 c4fb158 docs: align cross-language hashing guidance (#340)
c4fb158 is described below
commit c4fb15857e4b82a8ff6417c81664ae8c29da2859
Author: tison <[email protected]>
AuthorDate: Tue Nov 10 14:45:57 2026 +0800
docs: align cross-language hashing guidance (#340)
---
datasketches/src/bloom/mod.rs | 12 +++++
datasketches/src/bloom/sketch.rs | 2 +
datasketches/src/countmin/mod.rs | 64 +++++++++++++++++++++-----
datasketches/src/countmin/sketch.rs | 39 +++++-----------
datasketches/src/cpc/mod.rs | 11 +++++
datasketches/src/cpc/sketch.rs | 3 --
datasketches/src/hash/value/canonical_float.rs | 2 -
datasketches/src/hash/value/mod.rs | 60 +++++-------------------
datasketches/src/hash/value/natural_extend.rs | 3 --
datasketches/src/hash/value/raw_bytes.rs | 12 ++---
datasketches/src/hash/value/sign_extend.rs | 3 +-
datasketches/src/hll/mod.rs | 18 ++++++--
datasketches/src/hll/sketch.rs | 3 --
datasketches/src/thetafamily/theta/mod.rs | 11 +++++
datasketches/src/thetafamily/theta/sketch.rs | 5 +-
datasketches/src/thetafamily/tuple/mod.rs | 11 +++++
datasketches/src/thetafamily/tuple/sketch.rs | 2 +
datasketches/src/xor/filter.rs | 4 ++
datasketches/src/xor/mod.rs | 20 ++++----
19 files changed, 160 insertions(+), 125 deletions(-)
diff --git a/datasketches/src/bloom/mod.rs b/datasketches/src/bloom/mod.rs
index 5b2fbce..e5d6765 100644
--- a/datasketches/src/bloom/mod.rs
+++ b/datasketches/src/bloom/mod.rs
@@ -33,6 +33,18 @@
//! [`difference()`](BloomFilter::difference) excludes the right filter's
items exactly, but
//! may also drop left items whose hash positions collide with the right
filter.
//!
+//! # Cross-language hashing
+//!
+//! For cross-language use, apply the following input conventions:
+//!
+//! * Use `i64`/`u64` for 64-bit integers and
[`natural_extend`](crate::hash::value::natural_extend)
+//! for narrower integers.
+//! * Use [`canonical_float`](crate::hash::value::canonical_float) for
floating-point values.
+//! * Use [`raw_bytes`](crate::hash::value::raw_bytes) for UTF-8 strings and
byte slices.
+//!
+//! Skip empty strings and byte slices before inserting into the filter. For
these inputs,
+//! return `false` without querying the filter, including for queries combined
with insertion.
+//!
//! # Usage
//!
//! ```
diff --git a/datasketches/src/bloom/sketch.rs b/datasketches/src/bloom/sketch.rs
index 4dce8ab..b6dfbe1 100644
--- a/datasketches/src/bloom/sketch.rs
+++ b/datasketches/src/bloom/sketch.rs
@@ -38,6 +38,8 @@ const EMPTY_FLAG_MASK: u8 = 1 << 2;
/// * No false negatives (inserted items always return `true`)
/// * Tunable false positive rate
/// * Constant space usage
+///
+/// See the [module level documentation](super) for more.
#[derive(Debug, Clone, PartialEq)]
pub struct BloomFilter {
/// Hash seed for all hash functions
diff --git a/datasketches/src/countmin/mod.rs b/datasketches/src/countmin/mod.rs
index 03c9283..14855a1 100644
--- a/datasketches/src/countmin/mod.rs
+++ b/datasketches/src/countmin/mod.rs
@@ -20,30 +20,70 @@
//! The CountMin sketch provides approximate frequency counts for streaming
data
//! with configurable relative error and confidence bounds.
//!
-//! Serial version 2 sketches with `i64` counters support cross-language
binary interchange when
-//! items use compatible hashing; see [`CountMinSketch`] and
[`hash::value`](crate::hash::value).
+//! # Cross-language hashing
+//!
+//! For cross-language use, apply the following input conventions:
+//!
+//! * Use `i64`/`u64` for 64-bit integers and
[`natural_extend`](crate::hash::value::natural_extend)
+//! for narrower integers.
+//! * Use [`canonical_float`](crate::hash::value::canonical_float) for
floating-point values.
+//! * Use [`raw_bytes`](crate::hash::value::raw_bytes) for UTF-8 strings and
byte slices.
+//!
+//! Use `i64` counters for cross-language interchange. Skip empty strings and
byte slices before
+//! updating the sketch. For these inputs, return zero for the estimate and
both bounds without
+//! querying the sketch.
//!
//! # Usage
//!
+//! Choose the number of buckets and hash functions from the desired relative
error and
+//! confidence, then update the sketch as items arrive:
+//!
//! ```
//! use datasketches::countmin::CountMinSketch;
-//! use datasketches::hash::value::raw_bytes;
//!
-//! let mut sketch = CountMinSketch::<i64>::new(5, 256).unwrap();
-//! sketch.update(raw_bytes::from_str("apple"));
-//! sketch.update_with_weight(raw_bytes::from_str("banana"), 3);
-//! assert!(sketch.estimate(raw_bytes::from_str("banana")) >= 3);
+//! let buckets = CountMinSketch::<i64>::suggest_num_buckets(0.01)?;
+//! let hashes = CountMinSketch::<i64>::suggest_num_hashes(0.99)?;
+//! let mut sketch = CountMinSketch::<i64>::new(hashes, buckets)?;
+//! sketch.update(42i64);
+//! sketch.update_with_weight(42i64, 5);
+//!
+//! assert_eq!(sketch.estimate(42i64), 6);
+//! assert!(sketch.lower_bound(42i64) <= 6);
+//! assert!(sketch.upper_bound(42i64) >= 6);
+//! # Ok::<(), datasketches::error::Error>(())
//! ```
//!
-//! # Configuration Helpers
+//! ## Empty inputs
+//!
+//! This example handles empty strings before updating or querying. Byte
slices use the same
+//! `is_empty()` checks with `raw_bytes::from_slice`.
//!
//! ```
//! use datasketches::countmin::CountMinSketch;
+//! use datasketches::hash::value::raw_bytes;
+//!
+//! let mut sketch = CountMinSketch::<i64>::new(3, 1000)?;
+//! for input in ["", "apple", ""] {
+//! let item = raw_bytes::from_str(input);
+//! if !item.is_empty() {
+//! sketch.update_with_weight(item, 5);
+//! }
+//! }
+//! assert_eq!(sketch.total_weight(), 5);
+//! assert_eq!(sketch.estimate(raw_bytes::from_str("apple")), 5);
//!
-//! let buckets = CountMinSketch::<i64>::suggest_num_buckets(0.01).unwrap();
-//! let hashes = CountMinSketch::<i64>::suggest_num_hashes(0.99).unwrap();
-//! let sketch = CountMinSketch::<i64>::new(hashes, buckets).unwrap();
-//! assert_eq!(sketch.estimate(1i64), 0);
+//! let item = raw_bytes::from_str("");
+//! let (estimate, lower, upper) = if item.is_empty() {
+//! (0, 0, 0)
+//! } else {
+//! (
+//! sketch.estimate(item),
+//! sketch.lower_bound(item),
+//! sketch.upper_bound(item),
+//! )
+//! };
+//! assert_eq!((estimate, lower, upper), (0, 0, 0));
+//! # Ok::<(), datasketches::error::Error>(())
//! ```
mod sketch;
diff --git a/datasketches/src/countmin/sketch.rs
b/datasketches/src/countmin/sketch.rs
index f36b2fe..88bf287 100644
--- a/datasketches/src/countmin/sketch.rs
+++ b/datasketches/src/countmin/sketch.rs
@@ -45,14 +45,7 @@ const MAX_TABLE_ENTRIES: usize = 1 << 30;
/// The sketch provides upper and lower bounds on estimated item frequencies
/// with configurable relative error and confidence.
///
-/// New sketches use serial version 2. Deserialized version 1 sketches retain
their legacy
-/// hashing and serialization format, and sketches of different versions
cannot be merged.
-///
-/// For cross-language version 2 interchange, use `i64` counters and encode
inputs consistently:
-/// * `i64` and `u64` values are hashed as eight little-endian bytes; use
-/// [`crate::hash::value::natural_extend`] for narrower integers.
-/// * Use [`crate::hash::value::raw_bytes`] for UTF-8 strings and byte slices,
and skip empty inputs
-/// when interoperating with implementations that ignore them.
+/// See the [module level documentation](super) for more.
#[derive(Debug, Clone, PartialEq)]
pub struct CountMinSketch<T: CountMinValue> {
num_hashes: u8,
@@ -320,9 +313,6 @@ impl<T: CountMinValue> CountMinSketch<T> {
/// Updates the sketch with a single occurrence of the item.
///
- /// Use [`hash::value`](crate::hash::value) wrappers to select an input
encoding for
- /// cross-language hashing.
- ///
/// # Panics
///
/// Panics without modifying the sketch if the total absolute weight would
exceed `T::MAX`.
@@ -342,9 +332,6 @@ impl<T: CountMinValue> CountMinSketch<T> {
/// Updates the sketch with the given item and weight.
///
- /// Use [`hash::value`](crate::hash::value) wrappers to select an input
encoding for
- /// cross-language hashing.
- ///
/// # Panics
///
/// Panics without modifying the sketch if the absolute weight or the
total absolute weight
@@ -452,11 +439,7 @@ impl<T: CountMinValue> CountMinSketch<T> {
/// Serializes this sketch into the Count-Min binary format.
///
- /// New sketches are written as version 2. A sketch deserialized from a
version 1 image
- /// retains its legacy hashing for queries and updates and is written back
as version 1.
- ///
- /// Version 1 images are not portable across implementations. Version 2
supports cross-language
- /// interchange with `i64` counters and the input encodings documented on
[`CountMinSketch`].
+ /// A sketch restored by [`deserialize`](Self::deserialize) retains its
original format.
///
/// # Examples
///
@@ -507,13 +490,15 @@ impl<T: CountMinValue> CountMinSketch<T> {
/// Deserializes a sketch from bytes using the default seed.
///
- /// Accepts versions 1 and 2, preserving the image's hashing and
serialization version.
- /// Counter values must fit `T`. See [`CountMinSketch`] for input
encodings and compatibility.
+ /// Accepts the current format and legacy version 1 images. Legacy images
retain their original
+ /// hashing and serialization format and cannot be merged with newly
created sketches. Use the
+ /// same input encodings that were used to create the image; version 1
images are not portable
+ /// across implementations. Counter values must fit `T`.
///
/// # Errors
///
- /// Returns `InvalidData` if the image is malformed or its seed hash does
not match the default
- /// seed.
+ /// Returns `InvalidData` if the image is malformed, its serialization
version is unsupported,
+ /// or its seed hash does not match the default seed.
///
/// # Examples
///
@@ -532,13 +517,13 @@ impl<T: CountMinValue> CountMinSketch<T> {
/// Deserializes a sketch from bytes using the provided seed.
///
- /// Accepts versions 1 and 2, preserving the image's hashing and
serialization version.
- /// Counter values must fit `T`. See [`CountMinSketch`] for input
encodings and compatibility.
+ /// The format and counter requirements are the same as for
[`deserialize`](Self::deserialize).
///
/// # Errors
///
- /// Returns `InvalidData` if the image is malformed, its seed hash does
not match `seed`, or
- /// `seed` itself computes to the reserved zero seed hash.
+ /// Returns `InvalidData` if the image is malformed, its serialization
version is unsupported,
+ /// its seed hash does not match `seed`, or `seed` itself computes to the
reserved zero seed
+ /// hash.
///
/// # Examples
///
diff --git a/datasketches/src/cpc/mod.rs b/datasketches/src/cpc/mod.rs
index 6102dea..10c81b3 100644
--- a/datasketches/src/cpc/mod.rs
+++ b/datasketches/src/cpc/mod.rs
@@ -34,6 +34,17 @@
//! configurations of K.
//!
//! For additional security this sketch can be configured with a
user-specified hash seed.
+//!
+//! # Cross-language hashing
+//!
+//! For cross-language use, apply the following input conventions:
+//!
+//! * Use `i64`/`u64` for 64-bit integers and
[`sign_extend`](crate::hash::value::sign_extend) for
+//! narrower integers.
+//! * Use [`canonical_float`](crate::hash::value::canonical_float) for
floating-point values.
+//! * Use [`raw_bytes`](crate::hash::value::raw_bytes) for UTF-8 strings and
byte slices.
+//!
+//! Skip empty strings and byte slices before updating the sketch.
mod compression;
mod compression_data;
diff --git a/datasketches/src/cpc/sketch.rs b/datasketches/src/cpc/sketch.rs
index d4f688a..9e0eee5 100644
--- a/datasketches/src/cpc/sketch.rs
+++ b/datasketches/src/cpc/sketch.rs
@@ -179,9 +179,6 @@ impl CpcSketch {
/// Updates the sketch with a hashable value.
///
- /// Use [`hash::value`](crate::hash::value) wrappers to select an input
encoding for
- /// cross-language hashing.
- ///
/// # Examples
///
/// ```rust
diff --git a/datasketches/src/hash/value/canonical_float.rs
b/datasketches/src/hash/value/canonical_float.rs
index 8b31232..56a1e08 100644
--- a/datasketches/src/hash/value/canonical_float.rs
+++ b/datasketches/src/hash/value/canonical_float.rs
@@ -20,8 +20,6 @@
//! [`CanonicalFloat`] maps `f32` and `f64` values through a canonical `f64`
bit pattern before
//! hashing. Signed zero values hash the same, all NaN values use one
canonical NaN bit pattern,
//! and equal `f32`/`f64` values hash the same.
-//!
-//! Use this encoding to match floating-point hashing in DataSketches Java and
DataSketches C++.
use std::hash::Hash;
use std::hash::Hasher;
diff --git a/datasketches/src/hash/value/mod.rs
b/datasketches/src/hash/value/mod.rs
index 803aba5..e84df55 100644
--- a/datasketches/src/hash/value/mod.rs
+++ b/datasketches/src/hash/value/mod.rs
@@ -19,58 +19,20 @@
//!
//! Sketch update APIs accept any value that implements [`Hash`]. For most
Rust values,
//! passing the value directly is sufficient. This module provides value
wrappers for
-//! cases where the default implementation does not match a sketch's
compatibility rules.
+//! cases where the default implementation does not match the required input
encoding.
//!
-//! ## Floating-point Numbers
+//! ## Encoding strategies
//!
-//! [`canonical_float::CanonicalFloat`] maps `f32` and `f64` values through a
canonical `f64` bit
-//! pattern before hashing. Signed zero values hash the same, all NaN values
use one canonical NaN
-//! bit pattern, and equal `f32`/`f64` values hash the same.
+//! * [`canonical_float`] widens floating-point values to `f64`, normalizes
signed zero to `+0.0`,
+//! and maps all NaNs to one bit pattern before hashing.
+//! * [`sign_extend`] interprets integers as signed at their original width
and sign-extends them to
+//! 64 bits before hashing.
+//! * [`natural_extend`] widens signed integers to `i64` and unsigned integers
to `u64` before
+//! hashing.
+//! * [`raw_bytes`] hashes byte slices as their contents and strings as UTF-8
bytes, without length
+//! prefixes or terminators.
//!
-//! Use this encoding to match floating-point hashing in DataSketches Java and
DataSketches C++.
-//!
-//! The concrete wrapper documentation provides more details and examples.
-//!
-//! * [`canonical_float::from_f32`]
-//! * [`canonical_float::from_f64`]
-//!
-//! ## Integers
-//!
-//! [`sign_extend::SignExtend`] first sign-extends values to 64-bits, and then
hashes the resulting
-//! integers. Use this encoding to match short-integer hashing in DataSketches
C++'s HLL and CPC
-//! sketches.
-//!
-//! The concrete wrapper documentation provides more details and examples.
-//!
-//! * [`sign_extend::from_i8`], [`sign_extend::from_u8`]
-//! * [`sign_extend::from_i16`], [`sign_extend::from_u16`]
-//! * [`sign_extend::from_i32`], [`sign_extend::from_u32`]
-//!
-//! [`natural_extend::NaturalExtend`] first widens signed values to `i64` and
unsigned values to
-//! `u64`, and then hashes the resulting integers. Use this encoding to match
short-integer hashing
-//! in DataSketches C++'s Bloom filters and Count-Min sketches.
-//!
-//! The concrete wrapper documentation provides more details and examples.
-//!
-//! * [`natural_extend::from_i8`], [`natural_extend::from_u8`]
-//! * [`natural_extend::from_i16`], [`natural_extend::from_u16`]
-//! * [`natural_extend::from_i32`], [`natural_extend::from_u32`]
-//!
-//! ## Raw Bytes
-//!
-//! [`raw_bytes::RawBytes`] hashes byte and string inputs as raw bytes without
Rust's slice or
-//! string length prefix.
-//!
-//! Use this encoding to match byte and UTF-8 string hashing in DataSketches
Java and
-//! DataSketches C++. Their string update APIs skip empty strings; check
`is_empty` before updating
-//! here as well.
-//!
-//! The concrete wrapper documentation provides more details and examples.
-//!
-//! * [`raw_bytes::from_vec`]
-//! * [`raw_bytes::from_string`]
-//! * [`raw_bytes::from_slice`]
-//! * [`raw_bytes::from_str`]
+//! Each strategy module provides constructors and examples.
pub mod canonical_float;
pub mod natural_extend;
diff --git a/datasketches/src/hash/value/natural_extend.rs
b/datasketches/src/hash/value/natural_extend.rs
index 780116f..6d437bd 100644
--- a/datasketches/src/hash/value/natural_extend.rs
+++ b/datasketches/src/hash/value/natural_extend.rs
@@ -19,9 +19,6 @@
//!
//! [`NaturalExtend`] first widens signed values to `i64` and unsigned values
to `u64`, and then
//! hashes the resulting integers.
-//!
-//! Use this encoding to match short-integer hashing in DataSketches C++'s
Bloom filters and
-//! Count-Min sketches.
use std::hash::Hash;
use std::hash::Hasher;
diff --git a/datasketches/src/hash/value/raw_bytes.rs
b/datasketches/src/hash/value/raw_bytes.rs
index a31c397..cc6299a 100644
--- a/datasketches/src/hash/value/raw_bytes.rs
+++ b/datasketches/src/hash/value/raw_bytes.rs
@@ -17,12 +17,8 @@
//! Raw byte and string hash value wrappers.
//!
-//! [`RawBytes`] hashes byte and string inputs as raw bytes without Rust's
slice or string length
-//! prefix.
-//!
-//! Use this encoding to match byte and UTF-8 string hashing in DataSketches
Java and
-//! DataSketches C++. Their string update APIs skip empty strings; check
`is_empty` before updating
-//! here as well.
+//! [`RawBytes`] hashes byte slices as their contents and strings as UTF-8
bytes, without length
+//! prefixes or terminators.
use std::hash::Hasher;
@@ -62,7 +58,7 @@ pub fn from_vec(v: Vec<u8>) -> RawBytes<Vec<u8>> {
/// Creates a raw-byte hashable value from a string.
///
-/// This hashes the UTF-8 bytes of the string without Rust's string length
prefix.
+/// This hashes the UTF-8 bytes of the string without a length prefix or
terminator.
///
/// # Examples
///
@@ -106,7 +102,7 @@ pub fn from_slice(v: &[u8]) -> RawBytes<&[u8]> {
/// Creates a raw-byte hashable value from a string slice.
///
-/// This hashes the UTF-8 bytes of the string slice without Rust's string
length prefix.
+/// This hashes the UTF-8 bytes of the string slice without a length prefix or
terminator.
///
/// # Examples
///
diff --git a/datasketches/src/hash/value/sign_extend.rs
b/datasketches/src/hash/value/sign_extend.rs
index eaaec9d..5486c0a 100644
--- a/datasketches/src/hash/value/sign_extend.rs
+++ b/datasketches/src/hash/value/sign_extend.rs
@@ -18,8 +18,7 @@
//! Sign-extended integer hash value wrappers.
//!
//! [`SignExtend`] first sign-extends values to 64-bits and then hashes the
resulting integers.
-//!
-//! Use this encoding to match short-integer hashing in DataSketches C++'s HLL
and CPC sketches.
+//! Unsigned values are interpreted as signed at their original width before
extension.
use std::hash::Hash;
use std::hash::Hasher;
diff --git a/datasketches/src/hll/mod.rs b/datasketches/src/hll/mod.rs
index 06db8d3..ed6651c 100644
--- a/datasketches/src/hll/mod.rs
+++ b/datasketches/src/hll/mod.rs
@@ -21,8 +21,17 @@
//! [`HllType`] controls register storage; `lg_k` controls the register count
and accuracy.
//!
//! The binary serialization format supports cross-language interchange.
-//! Cross-language updates must also use compatible hashing; see
-//! [`hash::value`](crate::hash::value).
+//!
+//! # Cross-language hashing
+//!
+//! For cross-language use, apply the following input conventions:
+//!
+//! * Use `i64`/`u64` for 64-bit integers and
[`sign_extend`](crate::hash::value::sign_extend) for
+//! narrower integers.
+//! * Use [`canonical_float`](crate::hash::value::canonical_float) for
floating-point values.
+//! * Use [`raw_bytes`](crate::hash::value::raw_bytes) for UTF-8 strings and
byte slices.
+//!
+//! Skip empty strings and byte slices before updating the sketch.
//!
//! # Usage
//!
@@ -113,6 +122,8 @@ const RESIZE_DENOMINATOR: u32 = 4;
/// Compute a coupon once with [`Coupon::from_value`] and pass it to
/// [`HllSketch::update_with_coupon`] on sketches with any `lg_k` or
[`HllType`].
///
+/// See the [module level documentation](crate::hll) for more.
+///
/// # Examples
///
/// ```
@@ -149,9 +160,6 @@ impl Coupon {
/// Computes the HLL coupon for a hashable value.
///
- /// Use [`hash::value`](crate::hash::value) wrappers to select an input
encoding for
- /// cross-language hashing.
- ///
/// # Examples
///
/// ```
diff --git a/datasketches/src/hll/sketch.rs b/datasketches/src/hll/sketch.rs
index 910a730..a62bea9 100644
--- a/datasketches/src/hll/sketch.rs
+++ b/datasketches/src/hll/sketch.rs
@@ -137,9 +137,6 @@ impl HllSketch {
/// Updates the sketch with a value.
///
- /// Use [`hash::value`](crate::hash::value) wrappers to select an input
encoding for
- /// cross-language hashing.
- ///
/// To reuse the hash across sketches, see [`Coupon`] and
/// [`update_with_coupon`](Self::update_with_coupon).
///
diff --git a/datasketches/src/thetafamily/theta/mod.rs
b/datasketches/src/thetafamily/theta/mod.rs
index c65fa09..2c8bb04 100644
--- a/datasketches/src/thetafamily/theta/mod.rs
+++ b/datasketches/src/thetafamily/theta/mod.rs
@@ -30,6 +30,17 @@
//! * [`ThetaSketch`]: Mutable sketch for building from input data.
//! * [`CompactThetaSketch`]: Immutable sketch with a compact memory layout.
//!
+//! # Cross-language hashing
+//!
+//! For cross-language use, apply the following input conventions:
+//!
+//! * Use `i64`/`u64` for 64-bit integers and
[`sign_extend`](crate::hash::value::sign_extend) for
+//! narrower integers.
+//! * Use [`canonical_float`](crate::hash::value::canonical_float) for
floating-point values.
+//! * Use [`raw_bytes`](crate::hash::value::raw_bytes) for UTF-8 strings and
byte slices.
+//!
+//! Skip empty strings and byte slices before updating the sketch.
+//!
//! # Usage
//!
//! ```
diff --git a/datasketches/src/thetafamily/theta/sketch.rs
b/datasketches/src/thetafamily/theta/sketch.rs
index 4ec71b7..e7d0b9b 100644
--- a/datasketches/src/thetafamily/theta/sketch.rs
+++ b/datasketches/src/thetafamily/theta/sketch.rs
@@ -203,6 +203,8 @@ impl<'a> From<&'a CompactThetaSketch> for
ThetaSketchView<'a> {
}
/// Mutable theta sketch for building from input data.
+///
+/// See the [module level documentation](super) for more.
#[derive(Debug)]
pub struct ThetaSketch {
table: ThetaHashTable,
@@ -218,9 +220,6 @@ impl ThetaSketch {
/// Updates the sketch with a hashable value.
///
- /// Use [`hash::value`](crate::hash::value) wrappers to select an input
encoding for
- /// cross-language hashing.
- ///
/// # Examples
///
/// ```
diff --git a/datasketches/src/thetafamily/tuple/mod.rs
b/datasketches/src/thetafamily/tuple/mod.rs
index c057ee5..c6424b0 100644
--- a/datasketches/src/thetafamily/tuple/mod.rs
+++ b/datasketches/src/thetafamily/tuple/mod.rs
@@ -28,6 +28,17 @@
//! summaries of shared keys through [`SummaryCombinePolicy`]; the union
defaults to
//! [`DefaultUnionPolicy`].
//!
+//! # Cross-language hashing
+//!
+//! For cross-language use, apply the following input conventions:
+//!
+//! * Use `i64`/`u64` for 64-bit integers and
[`sign_extend`](crate::hash::value::sign_extend) for
+//! narrower integers.
+//! * Use [`canonical_float`](crate::hash::value::canonical_float) for
floating-point values.
+//! * Use [`raw_bytes`](crate::hash::value::raw_bytes) for UTF-8 strings and
byte slices.
+//!
+//! These encodings apply to keys. Skip empty string and byte-slice keys
before updating the sketch.
+//!
//! # Usage
//!
//! ```
diff --git a/datasketches/src/thetafamily/tuple/sketch.rs
b/datasketches/src/thetafamily/tuple/sketch.rs
index 0fee821..37bd946 100644
--- a/datasketches/src/thetafamily/tuple/sketch.rs
+++ b/datasketches/src/thetafamily/tuple/sketch.rs
@@ -245,6 +245,8 @@ impl<'a, S> From<&'a CompactTupleSketch<S>> for
TupleSketchView<'a, S> {
/// [`P::Summary`](SummaryPolicy::Summary), while each accepted update type is
selected by a
/// [`SummaryUpdatePolicy<U>`] implementation.
///
+/// See the [module level documentation](super) for more.
+///
/// # Examples
///
/// ```
diff --git a/datasketches/src/xor/filter.rs b/datasketches/src/xor/filter.rs
index b378c8a..8cd8c1f 100644
--- a/datasketches/src/xor/filter.rs
+++ b/datasketches/src/xor/filter.rs
@@ -101,6 +101,8 @@ impl Fingerprints {
///
/// Query values with [`XorFilter::contains`] and precomputed hashes with
/// [`XorFilter::contains_hash`].
+///
+/// See the [module level documentation](super) for more.
#[derive(Debug)]
pub struct XorFilterBuilder {
filter_type: XorFilterType,
@@ -161,6 +163,8 @@ impl XorFilterBuilder {
/// `true` may be a false positive, with probability determined by
[`XorFilterType`], even for an
/// empty input set. Values cannot be added after construction; rebuild the
filter when the set
/// changes.
+///
+/// See the [module level documentation](super) for more.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct XorFilter {
// Cache the derived length to avoid division on every query.
diff --git a/datasketches/src/xor/mod.rs b/datasketches/src/xor/mod.rs
index 3f14674..f31448a 100644
--- a/datasketches/src/xor/mod.rs
+++ b/datasketches/src/xor/mod.rs
@@ -22,14 +22,18 @@
//!
//! # Cross-language hashing
//!
-//! Rust's [`Hash`](std::hash::Hash) may encode a value differently from other
languages. Use
-//! [`crate::hash::value`] to match the input encoding of another DataSketches
implementation.
-//! For precomputed hashes, use the same hash function when building and
querying the filter.
-//!
-//! Java hashes integer scalars as 64-bit little-endian values and strings as
UTF-8 bytes with
-//! xxHash64 seed `0`. Use `u64`/`i64` and [`crate::hash::value::raw_bytes`]
accordingly. Java
-//! skips empty strings; callers must do so explicitly here. External hashes
(for example XXH3)
-//! must use the precomputed-hash APIs throughout; Java's typed query API will
not match them.
+//! For cross-language use, apply the following input conventions:
+//!
+//! * Use `i64`/`u64` for 64-bit integers and
[`natural_extend`](crate::hash::value::natural_extend)
+//! for narrower integers.
+//! * Use [`canonical_float`](crate::hash::value::canonical_float) for
floating-point values.
+//! * Use [`raw_bytes`](crate::hash::value::raw_bytes) for UTF-8 strings and
byte slices.
+//!
+//! Skip empty strings and byte slices when building the filter. For these
inputs, return
+//! `false` without querying the filter.
+//!
+//! Value-based APIs use xxHash64 with seed `0`. For precomputed hashes, use
the same hash function
+//! when building and querying the filter, and use the precomputed-hash APIs
throughout.
//!
//! # Examples
//!
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]