Struct HyperLogLogBuilder 

pub struct HyperLogLogBuilder<H, W = usize, const BETA: bool = true> { /* private fields */ }

Builder for HyperLogLog cardinality-estimation logic.

The builder lets you configure:

• the upper bound on the number of distinct elements (new / num_elements);
• the number of registers, either directly (log2_num_regs) or via a target relative standard deviation (rsd);
• the backend word type (word_type);
• the hash function (build_hasher);
• whether LogLog-β bias correction is enabled (beta).

Call build to obtain the configured HyperLogLog logic.

Implementations

impl HyperLogLogBuilder<BuildHasherDefault<DefaultHasher>>

pub const fn new(num_elements: usize) -> Self

Creates a new builder for a HyperLogLog logic with the default word type (the fixed-size equivalent of usize).

Panics

If num_elements is zero.

impl<H, W: Word, const BETA: bool> HyperLogLogBuilder<H, W, BETA>

pub fn rsd(self, rsd: f64) -> Self

Sets the desired relative standard deviation.

This is a high-level alternative to Self::log2_num_regs. Calling one after the other invalidates the work done by the first one.

Arguments

• rsd: the relative standard deviation to be attained.

Panics

If the resulting number of registers is less than 16 (i.e., rsd is too large).

pub const fn log2_num_regs(self, log2_num_regs: u32) -> Self

Sets the base-2 logarithm of the number of registers.

This is a low-level alternative to Self::rsd. Calling one after the other invalidates the work done by the first one.

Arguments

• log2_num_regs: the logarithm of the number of registers per estimator.

Panics

If log2_num_regs is less than 4.

pub fn min_log2_num_regs(&self) -> u32

Returns the minimum value allowed for Self::log2_num_regs given the current value of Self::num_elements.

pub fn word_type<W2>(self) -> HyperLogLogBuilder<H, W2, BETA>

Sets the type W to use to represent backends.

Note that the returned builder will have a different type if W2 is different from W.

See the logic documentation for the limitations on the choice of W2.

pub fn beta<const BETA2: bool>(self) -> HyperLogLogBuilder<H, W, BETA2>

Enables or disables the LogLog-β bias correction in the estimate.

When enabled (the default), the estimate uses the LogLog-β formula for log_num_regs 4–18, which provides better accuracy across the full cardinality range without a separate linear-counting correction, at the cost of roughly 20ns per estimate call when some registers are still zero. When all registers are populated, the correction is skipped and performance is identical to the classic formula.

When disabled, the classic HyperLogLog formula with linear-counting fallback is used.

// Disable LogLog-β correction
let logic = HyperLogLogBuilder::new(1_000_000)
    .log2_num_regs(8)
    .beta::<false>()
    .build::<usize>().unwrap();

pub const fn num_elements(self, num_elements: usize) -> Self

Sets the upper bound on the number of elements.

Panics

If n is zero.

pub fn build_hasher<H2>( self, build_hasher: H2, ) -> HyperLogLogBuilder<H2, W, BETA>

Sets the BuildHasher to use.

Using this method you can select a specific hasher based on one or more seeds.

pub fn build<T>(self) -> Result<HyperLogLog<T, H, W, BETA>, HyperLogLogError>

Builds the logic.

The type of objects the estimators keep track of is defined here by T, but it is usually inferred by the compiler.

Errors

Returns HyperLogLogError::RegisterSizeTooLarge if the register size derived from num_elements exceeds the maximum supported by the hash type.

Returns HyperLogLogError::UnalignedBackend if the estimator size in bits is not divisible by the bit width of W.

Trait Implementations

impl<H: Clone, W: Clone, const BETA: bool> Clone for HyperLogLogBuilder<H, W, BETA>

fn clone(&self) -> HyperLogLogBuilder<H, W, BETA>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<H: Debug, W: Debug, const BETA: bool> Debug for HyperLogLogBuilder<H, W, BETA>

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

Formats the value using the given formatter.