Struct HyperLogLog 

pub struct HyperLogLog { /* private fields */ }

A HyperLogLog distinct-count estimator over m = 2^precision byte registers.

Construct with HyperLogLog::new, feed elements with HyperLogLog::add (or build directly with HyperLogLog::from_u64_iter), then read the estimated cardinality with HyperLogLog::estimate. The struct holds only the precision and the register array, so it is cheap to clone and fully deterministic.

Implementations

impl HyperLogLog

pub fn new(precision: u8) -> Result<Self, CardinalityError>

Creates an empty estimator with 2^precision zeroed registers.

Arguments

• precision — the register-index bit width p; must lie in [4, 18]. The register count is m = 2^p and the relative standard error is ≈ 1.04 / √m.

Returns

An estimator whose estimate is 0 until elements are added.

Errors

Returns CardinalityError::InvalidPrecision if precision is outside [4, 18].

Examples

use stats_claw::algorithms::cardinality::HyperLogLog;

let mut hll = HyperLogLog::new(14)?;
for x in 0_u64..1000 {
    hll.add(x);
}
// 1000 distinct elements, estimated within HLL's ~0.8% standard error at p=14.
let est = hll.estimate();
assert!((est - 1000.0).abs() / 1000.0 < 0.05, "estimate was {est}");

pub fn from_u64_iter<I>( precision: u8, values: I, ) -> Result<Self, CardinalityError>

where I: IntoIterator<Item = u64>,

Builds an estimator at precision from an iterator of u64 elements.

Equivalent to HyperLogLog::new followed by HyperLogLog::add for each element, but reads as a single expression for the common “estimate the distinct count of this stream” call. Because the register update is an order-independent maximum, the result is independent of the iteration order.

Arguments

• precision — the register-index bit width p; must lie in [4, 18].
• values — the elements to record; duplicates count once.

Returns

An estimator populated with every element of values.

Errors

Returns CardinalityError::InvalidPrecision if precision is outside [4, 18].

Examples

use stats_claw::algorithms::cardinality::HyperLogLog;

// 200 distinct values, each seen twice — the distinct count is 200.
let stream = (0_u64..200).chain(0_u64..200);
let hll = HyperLogLog::from_u64_iter(12, stream)?;
let est = hll.estimate();
assert!((est - 200.0).abs() / 200.0 < 0.1, "estimate was {est}");

pub const fn precision(&self) -> u8

The precision p (register-index bit width) this estimator was built with.

pub const fn register_count(&self) -> usize

The register count m = 2^precision.

pub fn add(&mut self, value: u64)

Adds a 64-bit element to the estimator, updating one register.

The element is scattered by a fixed bijective finalizer; the leading precision bits of the hash select the register, and the register is raised to max(current, 1 + leading_zeros(remaining bits)). The update is a maximum, so it is idempotent in the element (re-adding the same value never changes any register) and order-independent across distinct elements — which is what makes the estimate deterministic for a given input multiset.

Non-u64 elements are added by first reducing them to a u64 key; integer streams pass their value directly.

Arguments

• value — the element to record. Equal values are treated as one distinct element; the count is over the set of values seen.

pub fn estimate(&self) -> f64

Estimates the number of distinct elements added so far.

A pure function of the register array: the harmonic-mean raw estimate with the small-range (linear-counting) and large-range corrections applied as the register state warrants. An estimator with nothing added returns 0 exactly.

The result is an approximation with relative standard error ≈ 1.04 / √m (m = 2^precision); it is not the exact count, and callers needing the true distinct count must use an exact structure instead.

Returns

The estimated distinct-element count, ≥ 0.

Trait Implementations

impl Clone for HyperLogLog

fn clone(&self) -> HyperLogLog

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HyperLogLog

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.