Struct minisketch_rs::Minisketch

pub struct Minisketch { /* fields omitted */ }

Describes decoded sketches and holding underlying opaque type inside.

Implementations

impl Minisketch

pub fn try_new(
    bits: u32,
    implementation: u32,
    capacity: usize
) -> Result<Self, MinisketchError>

Tries to create a new empty sketch.

Errors

If the combination of bits and implementation is unavailable, or if capacity is 0, an Err(MinisketchError) is returned.

Examples

use minisketch_rs::Minisketch;
let sketch = Minisketch::try_new(12, 0, 4)?;

pub fn bits_supported(bits: u32) -> bool

Determine whether support for elements of size of bits bits was compiled in.

pub fn implementation_max() -> u32

Determine the maximum number of implementations available.

Multiple implementations may be available for a given element size, with different performance characteristics on different hardware.

Each implementation is identified by a number from 0 to the output of this function call, inclusive. Note that not every combination of implementation and element size may exist.

pub fn bits(&self) -> u32

Returns element size in a sketch in bits.

pub fn capacity(&self) -> usize

Returns capacity of a sketch in number of elements.

pub fn implementation(&self) -> u32

Returns implementation version number.

pub fn serialized_size(&self) -> usize

Returns the size in bytes for serializing a given sketch.

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

Adds a u64 element to a sketch.

If the element to be added is too large for the sketch, the most significant bits of the element are dropped. More precisely, if the element size of sketch is b bits, then this function adds the unsigned integer represented by the b least significant bits of element to sketch.

If the element to be added is 0 (after potentially dropping the most significant bits), then this function is a no-op. Sketches cannot contain an element with the value 0.

Note that adding the same element a second time removes it again, as sketches have set semantics, not multiset semantics.

Examples

use minisketch_rs::Minisketch;
let mut sketch = Minisketch::try_new(12, 0, 4)?;
sketch.add(42);

pub fn set_seed(&mut self, seed: u64)

Set the seed for randomizing algorithm choices to a fixed value.

By default, sketches are initialized with a random seed. This is important to avoid scenarios where an attacker could force worst-case behavior.

This function initializes the seed to a user-provided value (any 64-bit integer is acceptable, regardless of field size).

When seed is std::u64::MAX, a fixed internal value with predictable behavior is used. It is only intended for testing.

Examples

use minisketch_rs::Minisketch;
let mut sketch = Minisketch::try_new(12, 0, 4)?;
sketch.set_seed(42);

pub fn merge(&mut self, other: &Self) -> Result<usize, MinisketchError>

Merge the elements of another sketch into this sketch.

After merging, sketch will contain every element that existed in one but not both of the input sketches. It can be seen as an exclusive or operation on the set elements. If the capacity of other_sketch is lower than sketch's, merging reduces the capacity of sketch to that of other_sketch.

Returns the Ok(capacity) of sketch after merging has been performed (where this capacity is at least 1)

It is also possible to perform this operation directly on the serializations of two sketches with the same element size and capacity by performing a bitwise XOR of the serializations.

You can also merge two sketches by doing xor-assignment (^=).

Errors

Returns Err(MinisketchError) to indicate that merging has failed because the two input sketches differ in their element size or implementation. If Err is returned, sketch (and its capacity) have not been modified.

Examples

use minisketch_rs::Minisketch;
let mut sketch_a = Minisketch::try_new(12, 0, 4)?;
sketch_a.add(10);
sketch_a.add(43);

let mut sketch_b = Minisketch::try_new(12, 0, 4)?;
sketch_b.add(42);
sketch_b.add(43);

// Merge two sketches and extract a difference
let num_diffs = sketch_a.merge(&sketch_b)?;

// Extract difference
let mut differences = vec![0u64; num_diffs];
sketch_a.decode(&mut differences)?;

assert!((differences[0] == 42 || differences[0] == 10) && (differences[1] == 10 || differences[1] == 42));

pub fn decode(&self, elements: &mut [u64]) -> Result<usize, MinisketchError>

Decode a sketch.

elements is a mutable reference to a buffer of u64, which will be filled with the elements in this sketch.

Returns Ok(num. of decoded elements)

Errors

Returns Err(MinisketchError) if decoding failed for any reason.

Examples

use minisketch_rs::Minisketch;
let mut sketch = Minisketch::try_new(12, 0, 2)?;
sketch.add(42);
sketch.add(10);
let mut elements = [0u64; 2];
sketch.decode(&mut elements)?;

// Elements may come in arbitrary order, so check all possible variants
assert!((elements[0] == 42 || elements[0] == 10) && (elements[1] == 10 || elements[1] == 42));

pub fn deserialize(&mut self, buf: &[u8])

Deserialize a sketch from bytes.

Examples

use minisketch_rs::Minisketch;

// Create Alice's sketch
let mut sketch_alice = Minisketch::try_new(12, 0, 2)?;
sketch_alice.add(42);
sketch_alice.add(10);

// Serialize sketch on Alice's side
let mut message = vec![0u8; sketch_alice.serialized_size()];
sketch_alice.serialize(&mut message);

// ... message is sent from Alice to Bob ...

// Deserialize sketch from Alice on Bob's side
let mut sketch_bob = Minisketch::try_new(12, 0, 2)?;
sketch_bob.deserialize(&message);

// Decode received sketch
let mut elements = [0u64; 2];
sketch_bob.decode(&mut elements)?;
// Elements may come in arbitrary order, so check all possible variants
assert!((elements[0] == 42 || elements[0] == 10) && (elements[1] == 10 || elements[1] == 42));

pub fn serialize(&self, buf: &mut [u8]) -> Result<(), MinisketchError>

Serialize a sketch to bytes.

Errors

Returns Err(MinisketchError) if .len() of the provided buffer buf is less than a size in bytes of the serialized representation of the sketch.

Examples

use minisketch_rs::Minisketch;
let mut sketch = Minisketch::try_new(12, 0, 2)?;
sketch.add(42);
sketch.add(10);

let mut buf = vec![0u8; sketch.serialized_size()];
sketch.serialize(&mut buf);

Trait Implementations

impl BitXorAssign<Minisketch> for Minisketch

Custom ^= operator implementation on two sketches that performs merging.

Example

use minisketch_rs::Minisketch;
let mut sketch_a = Minisketch::try_new(12, 0, 4)?;
sketch_a.add(10);
sketch_a.add(43);

let mut sketch_b = Minisketch::try_new(12, 0, 4)?;
sketch_b.add(42);
sketch_b.add(43);

// Merge two sketches with ^= operator
sketch_a ^= sketch_b;

// Extract difference
let mut differences = vec![0u64; 2];
sketch_a.decode(&mut differences)?;

assert!((differences[0] == 42 || differences[0] == 10) && (differences[1] == 10 || differences[1] == 42));

fn bitxor_assign(&mut self, rhs: Minisketch)

Performs the ^= operation.

impl Debug for Minisketch

Custom Debug implementation that shows basic information about opaque minisketch.

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

Formats the value using the given formatter.