Minhash Rs

https://docs.rs/minhash-rs/latest/minhash_rs/
Admin
MinHash-rs provides a Rust implementation of the MinHash algorithm for parsimonious-memory MinHash...
Tokens:40,201
Snippets:599
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Band Hashes Usage

Source: https://docs.rs/minhash-rs/latest/minhash_rs/min_hasher/trait.MinHasher.html

Example showing the setup for computing band hashes.

```rust
use minhash_rs::prelude::*;
```

--------------------------------

### MinHash Usage Examples

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates initializing MinHash with default parameters, custom hashers like FNV, and custom word/hash widths.

```rust
use minhash_rs::prelude::*;

// Default hasher (SipHash-1-3) and default hash width (u64):
let mut minhash = MinHash::<u64, 128>::new();
minhash.insert(42);
assert!(minhash.may_contain(42));

// FNV hasher:
let mut minhash = MinHash::<u64, 128, Fnv>::new();
minhash.insert(42);
assert!(minhash.may_contain(42));

// u32 word backed by u32 hash stream: half the storage per register.
let mut minhash = MinHash::<u32, 128, SipHashes13, u32>::new();
minhash.insert(42);
assert!(minhash.may_contain(42));
```

--------------------------------

### Usage of band_hash

Source: https://docs.rs/minhash-rs/latest/minhash_rs/lsh/fn.band_hash.html?search=

Example demonstrating how to compute and compare hashes for bands of MinHash registers.

```rust
use minhash_rs::lsh::band_hash;

let h = band_hash(&[1u64, 2, 3]);
let same = band_hash(&[1u64, 2, 3]);
assert_eq!(h, same);
```

--------------------------------

### Concurrent Insertion Example

Source: https://docs.rs/minhash-rs/latest/minhash_rs/atomic/trait.AtomicFetchInsert.html

Demonstrates how to perform concurrent insertions into a MinHash structure using the AtomicFetchInsert trait.

```rust
use core::sync::atomic::Ordering;
use minhash_rs::prelude::*;

let mut minhash = MinHash::<u64, 4>::new();
{
    let atomic = minhash.as_atomic();
    atomic.fetch_insert_with_siphashes13::<_, u64>(42u64, Ordering::Relaxed);
    atomic.fetch_insert_with_siphashes13::<_, u64>(47u64, Ordering::Relaxed);
}
assert!(!minhash.is_empty());
assert!(minhash.may_contain(42u64));
assert!(minhash.may_contain(47u64));
```

--------------------------------

### Estimate Jaccard Index Examples

Source: https://docs.rs/minhash-rs/latest/minhash_rs/min_hasher/trait.MinHasher.html

Demonstrates calculating Jaccard similarity for same-variant sparse sketches and cross-variant dense sketches.

```rust
use minhash_rs::prelude::*;

let a: SparseHashes<u64, 128> = (0u64..30).collect();
let b: SparseHashes<u64, 128> = (15u64..45).collect();
let j = <SparseHashes<u64, 128> as MinHasher<128>>::estimate_jaccard_index(&a, &b);
assert!((j - 15.0 / 45.0).abs() < 1e-9);
```

```rust
use minhash_rs::prelude::*;

let sh: SparseHashes<u64, 128> = (0u64..30).collect();
let sv: SparseValues<128> = (0u64..30).collect();
let dense_sh: MinHash<u64, 128> = sh.into();
let dense_sv: MinHash<u64, 128> = sv.into();
let j = dense_sh.estimate_jaccard_index(&dense_sv);
assert!((j - 1.0).abs() < 1e-9);
```

--------------------------------

### Rejected External Implementation

Source: https://docs.rs/minhash-rs/latest/minhash_rs/min_hasher/trait.MinHasher.html

Example of an implementation attempt that fails at compile time because the trait is sealed.

```rust
use minhash_rs::prelude::*;

struct External;

impl MinHasher<128> for External {
    type Word = u64;
    type Hash = u64;
    type Hasher = SipHashes13;
    type Value = u64;
    fn insert(&mut self, _value: u64) -> Outcome { Outcome::Inserted }
    fn may_contain(&self, _value: u64) -> bool { false }
    fn densify(&mut self) {}
    fn estimate_jaccard_index(&self, _other: &Self) -> f64 { 0.0 }
}
```

--------------------------------

### Using SipHash-1-3 with MinHash

Source: https://docs.rs/minhash-rs/latest/minhash_rs/atomic/trait.IterHashes.html?search=std%3A%3Avec

Demonstrates initializing a MinHash instance and performing basic containment checks using the default SipHash-1-3 configuration.

```rust
use minhash_rs::prelude::*;

let mut minhash = MinHash::<u64, 128>::new();
assert!(!minhash.may_contain(42));
minhash.insert(42);
assert!(minhash.may_contain(42));
```

--------------------------------

### Initialize and use SparseValues

Source: https://docs.rs/minhash-rs/latest/minhash_rs/sparse_values/struct.SparseValues.html

Demonstrates creating a SparseValues sketch, inserting values, checking for containment, and converting to a dense MinHash.

```rust
use minhash_rs::prelude::*;

let mut sketch = SparseValues::<128>::new();
for value in 0u64..64 {
    sketch.insert(value);
}
assert!(sketch.may_contain(0));
assert!(sketch.may_contain(63));
assert!(!sketch.may_contain(1000));

let dense: MinHash<u64, 128> = sketch.into();
assert!(dense.may_contain(42u64));
```

--------------------------------

### Using FNV-1a with MinHash

Source: https://docs.rs/minhash-rs/latest/minhash_rs/atomic/trait.IterHashes.html?search=std%3A%3Avec

Demonstrates initializing a MinHash instance specifically configured with the FNV-1a hasher.

```rust
use minhash_rs::prelude::*;

let mut minhash = MinHash::<u64, 128, Fnv>::new();
assert!(!minhash.may_contain(42));
minhash.insert(42);
assert!(minhash.may_contain(42));
```

--------------------------------

### Querying LshIndex for top-k candidates

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates initializing an LshIndex with signatures and performing a top-k query using a QueryState buffer.

```rust
use minhash_rs::prelude::*;
use minhash_rs::index::{LshIndex, NoStore, QueryState, Store};

let a: MinHash<u64, 128> = (0u64..30).collect();
let b: MinHash<u64, 128> = (15u64..45).collect();
let c: MinHash<u64, 128> = (200u64..230).collect();

let index: LshIndex<MinHash<u64, 128>, 128, 16, Store> =
    LshIndex::from_signatures([a, b, c]);

let mut state = QueryState::new();
let hits = index.top_k(&a, 2, &mut state);
assert_eq!(hits[0].0, 0);        // a is closest to itself
assert!((hits[0].1 - 1.0).abs() < 1e-9);
```

--------------------------------

### SparseHashes Usage and Promotion

Source: https://docs.rs/minhash-rs/latest/minhash_rs/sparse_hashes/struct.SparseHashes.html?search=

Demonstrates initializing a SparseHashes sketch, inserting values, and promoting it to a dense MinHash.

```rust
use minhash_rs::prelude::*;

let mut sketch = SparseHashes::<u64, 128>::new();
sketch.insert(42);
assert!(sketch.may_contain(42));

// Promoting yields a bit-identical MinHash.
let dense: MinHash<u64, 128> = sketch.into();
assert!(dense.may_contain(42));
```

--------------------------------

### QueryState::new

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/struct.QueryState.html?search=std%3A%3Avec

Creates a new, empty QueryState instance with no allocated capacity.

```APIDOC
### pub fn new() -> Self

Creates a fresh state with no allocated capacity. The buffer will grow on the first query.
```

--------------------------------

### LshIndex Construction and Metadata

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/struct.LshIndex.html?search=u32+-%3E+bool

Methods for building an index from signatures and checking its size.

```rust
pub fn from_signatures<I: IntoIterator<Item = K>>(signatures: I) -> Self
```

```rust
pub fn len(&self) -> usize
```

```rust
pub fn is_empty(&self) -> bool
```

--------------------------------

### Add dependency

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index.html?search=u32+-%3E+bool

Include the crate in your Cargo.toml file.

```toml
[dependencies]
minhash-rs = "0.5.0"
```

--------------------------------

### Implement SigStore for Store

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/trait.SigStore.html?search=u32+-%3E+bool

Implementation for Store which uses a Vec<K> to retain signatures for later retrieval.

```rust
impl<K> SigStore<K> for Store {
    type Storage = Vec<K>
}
```

--------------------------------

### MinHash::new

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html

Creates a new instance of a MinHash sketch.

```APIDOC
## pub fn new()

### Description
Creates a new instance of the MinHash sketch.
```

--------------------------------

### fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html?search=u32+-%3E+bool

Serializes the MinHash instance using the provided Serde serializer.

```APIDOC
## fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

### Description
Serializes this value into the given Serde serializer.
```

--------------------------------

### pub fn new() -> Self

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html?search=std%3A%3Avec

Creates a new instance of the MinHash structure.

```APIDOC
## pub fn new() -> Self

### Description
Initializes and returns a new instance of the MinHash structure.
```

--------------------------------

### QueryState::new

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/struct.QueryState.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new, empty QueryState instance with no allocated capacity. The buffer will grow automatically upon the first query.

```APIDOC
## pub fn new() -> Self

### Description
Creates a fresh QueryState instance with no allocated capacity. The internal buffer grows on the first query execution.

### Returns
- **Self** - A new instance of QueryState.
```

--------------------------------

### Store Implementation

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/trait.SigStore.html

Implementation of SigStore that retains signatures in a Vec.

```rust
impl<K> SigStore<K> for Store {
    type Storage = Vec<K>;
}
```

--------------------------------

### LshIndex Methods

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/struct.LshIndex.html?search=std%3A%3Avec

Methods for building, querying, and managing the LshIndex.

```rust
pub fn from_signatures<I: IntoIterator<Item = K>>(signatures: I) -> Self
```

```rust
pub fn len(&self) -> usize
```

```rust
pub fn is_empty(&self) -> bool
```

```rust
pub fn candidates<'state>( &self, query: &K, state: &'state mut QueryState, ) -> &'state [Candidate]
```

```rust
pub fn into_repr(self) -> LshIndexRepr<Vec<BandEntry>, BANDS>
```

```rust
pub fn from_repr(repr: LshIndexRepr<Vec<BandEntry>, BANDS>) -> Self
```

```rust
pub fn signature(&self, id: u32) -> &K
```

```rust
pub fn top_k( &self, query: &K, k: usize, state: &mut QueryState, ) -> Vec<(u32, f64)>
```

--------------------------------

### Initialize and iterate BandMatches

Source: https://docs.rs/minhash-rs/latest/minhash_rs/lsh/struct.BandMatches.html

Demonstrates creating a new BandMatches instance from two arrays of band hashes and iterating through the matching indices.

```rust
use minhash_rs::prelude::*;

let a = band_hash(&[1u64]);
let b = band_hash(&[2u64]);
let c = band_hash(&[1u64]); // same as `a`
let left = [a, b];
let right = [c, b];
let mut matches = BandMatches::new(&left, &right);
assert_eq!(matches.next(), Some(0));
assert_eq!(matches.next(), Some(1));
assert_eq!(matches.next(), None);
```

--------------------------------

### Hasher::build

Source: https://docs.rs/minhash-rs/latest/minhash_rs/hasher/trait.Hasher.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Constructs a fresh instance of the concrete hasher associated with the implementation.

```APIDOC
## fn build() -> Self::Concrete

### Description
Construct a fresh hasher instance.

### Returns
- **Self::Concrete** - A concrete implementation of the hasher.
```

--------------------------------

### Initialize a new MinHash

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new MinHash instance. Note that a zero-permutation sketch is rejected at compile time.

```rust
use minhash_rs::prelude::*;

let minhash = MinHash::<u64, 128>::new();
assert!(minhash.is_empty());
```

```rust
use minhash_rs::prelude::*;

let _bad = MinHash::<u64, 0>::new();
```

--------------------------------

### NoStore Implementation

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/trait.SigStore.html

Implementation of SigStore that drops signatures on insert.

```rust
impl<K> SigStore<K> for NoStore {
    type Storage = ();
}
```

--------------------------------

### Implement SigStore for NoStore

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/trait.SigStore.html?search=u32+-%3E+bool

Implementation for NoStore which uses the unit type for storage, effectively dropping signatures.

```rust
impl<K> SigStore<K> for NoStore {
    type Storage = ()
}
```

--------------------------------

### Persist and Load LshIndexRepr with epserde

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index.html?search=u32+-%3E+bool

Demonstrates saving an LshIndexRepr to disk and loading it via memory mapping using epserde.

```rust
use epserde::prelude::*;
use minhash_rs::index::{BandEntry, LshIndex, LshIndexRepr, NoStore};
use minhash_rs::prelude::*;

const P: usize = 128;
const BANDS: usize = 16;

let path = std::env::temp_dir()
    .join(format!("minhash_rs_readme_epserde_{}.bin", std::process::id()));

let signatures: Vec<MinHash<u64, P>> = (0..1_000_u64)
    .map(|i| {
        let mut s = MinHash::new();
        s.insert(i);
        s
    })
    .collect();
let index: LshIndex<MinHash<u64, P>, P, BANDS, NoStore> =
    LshIndex::from_signatures(signatures);
let repr = index.into_repr();
unsafe { repr.store(&path)? };

let mem_case = unsafe {
    <LshIndexRepr<Vec<BandEntry>, BANDS>>::mmap(&path, Flags::empty())?
};
let loaded = mem_case.uncase();

let mut query = MinHash::<u64, P>::new();
query.insert(42_u64);
let mut state = QueryState::new();
let hits: Vec<_> = loaded.candidates::<_, P>(&query, &mut state).to_vec();
assert!(!hits.is_empty());
assert!(hits.iter().any(|c| c.id == 42));

drop(mem_case);
let _ = std::fs::remove_file(&path);
```

--------------------------------

### Inspect MinHash properties

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html

Retrieve metadata about the MinHash configuration and memory usage.

```rust
use minhash_rs::prelude::*;

assert_eq!(MinHash::<u64, 128>::new().number_of_permutations(), 128);
```

```rust
use minhash_rs::prelude::*;

assert_eq!(MinHash::<u64, 128>::new().memory(), 128 * 64);
assert_eq!(MinHash::<u32, 128>::new().memory(), 128 * 32);
```

--------------------------------

### Check distinct values and densification

Source: https://docs.rs/minhash-rs/latest/minhash_rs/sparse_values/struct.SparseValues.html

Shows how to track distinct values in sparse mode and how the count becomes unavailable after densification.

```rust
use minhash_rs::prelude::*;

let mut sketch = SparseValues::<128>::new();
sketch.insert(1);
sketch.insert(2);
sketch.insert(1); // duplicate
assert_eq!(sketch.distinct_values(), Some(2));

sketch.densify();
assert_eq!(sketch.distinct_values(), None);
```

--------------------------------

### MinHash::new()

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new instance of the MinHash structure.

```APIDOC
## pub fn new() -> Self

### Description
Creates a new instance of the MinHash structure.
```

--------------------------------

### Build LshIndex from Signatures

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/struct.LshIndex.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Constructs an index from an iterator of signatures. Panics if the iterator exceeds u32::MAX signatures.

```rust
pub fn from_signatures<I: IntoIterator<Item = K>>(signatures: I) -> Self
```

--------------------------------

### MinHashArray::new

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash_array/struct.MinHashArray.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new instance of MinHashArray containing N empty MinHash sketches.

```APIDOC
## pub fn new() -> Self

### Description
Creates an array of N empty MinHash sketches.

### Returns
- **Self** - A new instance of MinHashArray initialized with empty sketches.
```

--------------------------------

### MinHashArray::new

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash_array/struct.MinHashArray.html?search=u32+-%3E+bool

Creates a new instance of MinHashArray containing N empty MinHash sketches.

```APIDOC
## pub fn new()

### Description
Creates an array of N empty MinHash sketches.

### Signature
`pub fn new() -> Self`
```

--------------------------------

### Perform LSH indexing

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index.html?search=u32+-%3E+bool

Create a banded index over MinHash signatures and perform top-k similarity queries.

```rust
use minhash_rs::prelude::*;

let a: MinHash<u64, 128> = (0u64..30).collect();
let b: MinHash<u64, 128> = (15u64..45).collect();
let c: MinHash<u64, 128> = (200u64..230).collect();

let index: LshIndex<MinHash<u64, 128>, 128, 16, Store> =
    LshIndex::from_signatures([a, b, c]);

let mut state = QueryState::new();
let hits = index.top_k(&a, 2, &mut state);
assert_eq!(hits[0].0, 0);
assert!((hits[0].1 - 1.0).abs() < 1e-9);
```

--------------------------------

### Tracking Distinct Hashes

Source: https://docs.rs/minhash-rs/latest/minhash_rs/sparse_hashes/struct.SparseHashes.html?search=

Shows how to track the count of distinct hashes in sparse mode and how this information becomes unavailable after densification.

```rust
use minhash_rs::prelude::*;

let mut sketch = SparseHashes::<u64, 128>::new();
sketch.insert(42u64);
sketch.insert(7u64);
sketch.insert(42u64); // duplicate
assert_eq!(sketch.distinct_hashes(), Some(2));

sketch.densify();
assert_eq!(sketch.distinct_hashes(), None);
```

--------------------------------

### MinHash::new()

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html

Creates a new instance of the MinHash struct.

```APIDOC
## pub fn new() -> Self

### Description
Creates a new instance of the MinHash struct.
```

--------------------------------

### MinHash::is_full

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html?search=std%3A%3Avec

Checks if the sketch is fully populated.

```APIDOC
## pub fn is_full(&self) -> bool

### Description
Returns `true` if the sketch is fully populated, meaning every register is strictly below the `Maximal` sentinel.
```

--------------------------------

### fetch_insert_with_fnv

Source: https://docs.rs/minhash-rs/latest/minhash_rs/atomic/trait.AtomicFetchInsert.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Atomically inserts a value into the MinHash structure using FNV-1a as the raw hasher.

```APIDOC
### fn fetch_insert_with_fnv<V, Hash>(&self, value: V, ordering: Ordering)

#### Description
Inserts a value atomically using FNV-1a with the default seed as the raw hasher and `Hash` as the internal hash stream width.

#### Parameters
- **value** (V) - The value to insert, must implement CoreHash.
- **ordering** (Ordering) - The memory ordering for the atomic operation.

#### Constraints
- **V**: CoreHash
- **Hash**: HashType + Primitive<Self::Word>
```

--------------------------------

### fetch_insert_with_fnv

Source: https://docs.rs/minhash-rs/latest/minhash_rs/atomic/trait.AtomicFetchInsert.html?search=std%3A%3Avec

Atomically inserts a value into the MinHash structure using FNV-1a as the raw hasher.

```APIDOC
### fn fetch_insert_with_fnv<V, Hash>(&self, value: V, ordering: Ordering)

#### Description
Insert atomically using FNV-1a with the default seed as the raw hasher and `Hash` as the internal hash stream width.

#### Parameters
- **value** (V) - The value to insert, must implement CoreHash.
- **ordering** (Ordering) - The memory ordering to use for the atomic operation.

#### Constraints
- **V**: CoreHash
- **Hash**: HashType + Primitive<Self::Word>
```

--------------------------------

### MinHash::new

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html?search=std%3A%3Avec

Creates a new empty MinHash instance where every register is set to the Maximal sentinel value.

```APIDOC
## pub fn new() -> Self

### Description
Creates a new empty MinHash instance. Every register is initialized to the `Maximal` sentinel value. Note that a zero-permutation sketch is rejected at compile time.
```

--------------------------------

### MinHash::new

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html?search=u32+-%3E+bool

Creates a new empty MinHash instance where every register is set to the Maximal sentinel value.

```APIDOC
## pub fn new() -> Self

### Description
Creates a new empty MinHash instance. Every register is initialized to the Maximal sentinel value. A zero-permutation sketch is rejected at compile time.

### Signature
`pub fn new<Word, const PERMUTATIONS: usize, H, Hash, Value>() -> Self`
```

--------------------------------

### MinHash::new

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html?search=

Creates a new empty MinHash instance where every register is set to the Maximal sentinel value.

```APIDOC
## pub fn new() -> Self

### Description
Creates a new empty MinHash instance. Every register is initialized to the `Maximal` sentinel value. Note that a zero-permutation sketch is rejected at compile time.

### Example
```rust
use minhash_rs::prelude::*;
let minhash = MinHash::<u64, 128>::new();
assert!(minhash.is_empty());
```
```

--------------------------------

### from_signatures

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/struct.LshIndex.html

Builds an LshIndex from an iterator of signatures. Signature IDs are assigned based on the iterator's yield order.

```APIDOC
## pub fn from_signatures<I: IntoIterator<Item = K>>(signatures: I) -> Self

### Description
Build an index over the given signatures, sorting each band's slice of the flat entry vector once at the end. Signature ids are assigned in the iterator's yield order starting at zero.

### Parameters
- **signatures** (I: IntoIterator<Item = K>) - Required - The iterator of signatures to index.

### Panics
Panics if the iterator yields more than u32::MAX signatures.
```

--------------------------------

### fetch_insert_with_fnv

Source: https://docs.rs/minhash-rs/latest/minhash_rs/atomic/trait.AtomicFetchInsert.html?search=u32+-%3E+bool

Atomically inserts a value into the MinHash structure using the FNV-1a hashing algorithm.

```APIDOC
### fn fetch_insert_with_fnv<V, Hash>(&self, value: V, ordering: Ordering)

#### Description
Insert atomically using FNV-1a with the default seed as the raw hasher and `Hash` as the internal hash stream width.

#### Parameters
- **value** (V) - The value to insert, must implement CoreHash.
- **ordering** (Ordering) - The memory ordering for the atomic operation.

#### Constraints
- **V**: CoreHash
- **Hash**: HashType + Primitive<Self::Word>
```

--------------------------------

### SparseHashes Methods

Source: https://docs.rs/minhash-rs/latest/minhash_rs/sparse_hashes/struct.SparseHashes.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Public methods for interacting with SparseHashes instances.

```APIDOC
## pub fn new() -> Self

### Description
Creates a new empty sketch in sparse mode.

## pub fn is_sparse(&self) -> bool

### Description
Returns true if the sketch is still holding the sparse hash list.

## pub fn is_dense(&self) -> bool

### Description
Returns true if the sketch has been promoted to dense mode.

## pub fn count(&self) -> usize

### Description
Returns the number of distinct digests currently held in sparse mode. Returns 0 in dense mode.

## pub fn distinct_hashes(&self) -> Option<usize>

### Description
Returns the number of distinct digests currently held. Returns Some(count) while the sketch is still in sparse mode, and None once it has densified.

## pub fn hashes(&self) -> Option<impl Iterator<Item = Hash> + '_>

### Description
Iterates the distinct digests currently held, in ascending order. Returns Some(iterator) while the sketch is still in sparse mode, and None once it has densified.
```

--------------------------------

### MinHashArray::new()

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash_array/struct.MinHashArray.html?search=std%3A%3Avec

Creates a new instance of MinHashArray containing N empty MinHash sketches.

```APIDOC
## pub fn new() -> Self

### Description
Creates an array of N empty MinHash sketches.

### Signature
`pub fn new() -> Self`
```

--------------------------------

### MinHash::is_full

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html?search=u32+-%3E+bool

Checks if the MinHash sketch is fully populated.

```APIDOC
## pub fn is_full(&self) -> bool

### Description
Returns true if the sketch is fully populated, meaning every register is strictly below the Maximal sentinel value.
```

--------------------------------

### LshIndexRepr Method Implementations

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/struct.LshIndexRepr.html?search=std%3A%3Avec

Methods available on LshIndexRepr for querying candidates and checking index size.

```rust
pub fn candidates<'state, K, const PERMUTATIONS: usize>( &self, query: &K, state: &'state mut QueryState, ) -> &'state [Candidate]
where K: MinHasher<PERMUTATIONS>, K::Word: CoreHash,
```

```rust
pub fn len(&self) -> usize
```

```rust
pub fn is_empty(&self) -> bool
```

--------------------------------

### Iterate over sparse values

Source: https://docs.rs/minhash-rs/latest/minhash_rs/sparse_values/struct.SparseValues.html

Demonstrates retrieving an iterator for the raw values stored in the sketch while it is in sparse mode.

```rust
use minhash_rs::prelude::*;

let mut sketch = SparseValues::<128>::new();
sketch.insert(1);
sketch.insert(2);
sketch.insert(3);
let values: Vec<u64> =
    sketch.values().expect("still sparse").collect();
assert_eq!(values, vec![3, 2, 1]);
sketch.densify();
assert!(sketch.values().is_none());
```

--------------------------------

### Retrieve MinHash configuration

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Access the number of permutations configured for the MinHash instance.

```rust
use minhash_rs::prelude::*;

assert_eq!(MinHash::<u64, 128>::new().number_of_permutations(), 128);
```

--------------------------------

### SparseHashes::new

Source: https://docs.rs/minhash-rs/latest/minhash_rs/sparse_hashes/struct.SparseHashes.html?search=std%3A%3Avec

Creates a new empty sketch in sparse mode.

```APIDOC
## pub fn new() -> Self

### Description
Create a new empty sketch in sparse mode.

### Returns
- **Self** - A new instance of SparseHashes.
```

--------------------------------

### Construct SparseHashes from an Iterator

Source: https://docs.rs/minhash-rs/latest/minhash_rs/sparse_hashes/struct.SparseHashes.html?search=

Demonstrates building a SparseHashes instance using the FromIterator trait.

```rust
use minhash_rs::prelude::*;

let sketch: SparseHashes<u64, 128> = (0u64..30).collect();
assert!(sketch.is_sparse());
assert_eq!(sketch.count(), 30);
assert!(sketch.may_contain(0u64));
assert!(!sketch.may_contain(1_000u64));
```

--------------------------------

### fetch_insert_with_siphashes13

Source: https://docs.rs/minhash-rs/latest/minhash_rs/atomic/trait.AtomicFetchInsert.html?search=std%3A%3Avec

Atomically inserts a value into the MinHash structure using SipHash-1-3 as the raw hasher.

```APIDOC
### fn fetch_insert_with_siphashes13<V, Hash>(&self, value: V, ordering: Ordering)

#### Description
Insert atomically using SipHash-1-3 with default keys as the raw hasher and `Hash` as the internal hash stream width.

#### Parameters
- **value** (V) - The value to insert, must implement CoreHash.
- **ordering** (Ordering) - The memory ordering to use for the atomic operation.

#### Constraints
- **V**: CoreHash
- **Hash**: HashType + Primitive<Self::Word>
```

--------------------------------

### fetch_insert_with_siphashes13

Source: https://docs.rs/minhash-rs/latest/minhash_rs/atomic/trait.AtomicFetchInsert.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Atomically inserts a value into the MinHash structure using SipHash-1-3 as the raw hasher.

```APIDOC
### fn fetch_insert_with_siphashes13<V, Hash>(&self, value: V, ordering: Ordering)

#### Description
Inserts a value atomically using SipHash-1-3 with default keys as the raw hasher and `Hash` as the internal hash stream width.

#### Parameters
- **value** (V) - The value to insert, must implement CoreHash.
- **ordering** (Ordering) - The memory ordering for the atomic operation.

#### Constraints
- **V**: CoreHash
- **Hash**: HashType + Primitive<Self::Word>
```

--------------------------------

### SparseValues::new

Source: https://docs.rs/minhash-rs/latest/minhash_rs/sparse_values/struct.SparseValues.html

Creates a new empty sketch in sparse-value mode.

```APIDOC
## pub fn new() -> Self

### Description
Create a new empty sketch in sparse-value mode.
```

--------------------------------

### Signature Storage and Ranking

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/struct.LshIndex.html?search=u32+-%3E+bool

Methods for retrieving stored signatures and ranking candidates by Jaccard similarity, available under Store.

```rust
pub fn signature(&self, id: u32) -> &K
```

```rust
pub fn top_k( &self, query: &K, k: usize, state: &mut QueryState, ) -> Vec<(u32, f64)>
```

--------------------------------

### QueryState Definition

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/struct.QueryState.html?search=std%3A%3Avec

The definition of the QueryState struct.

```rust
pub struct QueryState { /* private fields */ }
```

--------------------------------

### Iterating Sparse Hashes

Source: https://docs.rs/minhash-rs/latest/minhash_rs/sparse_hashes/struct.SparseHashes.html?search=

Demonstrates retrieving an iterator over the distinct hashes held in sparse mode, which returns None after densification.

```rust
use minhash_rs::prelude::*;

let mut sketch = SparseHashes::<u64, 128>::new();
sketch.insert(1u64);
sketch.insert(2u64);
sketch.insert(3u64);
let digests: Vec<u64> =
    sketch.hashes().expect("still sparse").collect();
assert_eq!(digests.len(), 3);
// Digests are stored in ascending order.
assert!(digests.windows(2).all(|w| w[0] < w[1]));

sketch.densify();
assert!(sketch.hashes().is_none());
```

--------------------------------

### compute_candidates

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/fn.compute_candidates.html?search=

Queries a compressed sparse row band layout for candidates that collide with the provided query.

```APIDOC
## compute_candidates

### Description
Queries a compressed sparse row band layout for candidates that collide with `query`, ranked by descending collision count then ascending id. This function is used by `LshIndex::candidates` and mmap-loaded `LshIndexRepr::DeserType`.

### Signature
`pub fn compute_candidates<'state, K, const PERMUTATIONS: usize, const BANDS: usize>(band_starts: &[u32; BANDS], band_entries: &[BandEntry], query: &K, state: &'state mut QueryState) -> &'state [Candidate]`

### Parameters
- **band_starts** (&[u32; BANDS]) - The starting indices of bands in the layout.
- **band_entries** (&[BandEntry]) - The slice of band entries to search.
- **query** (&K) - The query object implementing `MinHasher<PERMUTATIONS>`.
- **state** (&'state mut QueryState) - The mutable query state used during the search.

### Returns
- **&'state [Candidate]** - A slice of candidates that collide with the query, ranked by descending collision count then ascending ID.
```

--------------------------------

### fetch_insert_with_siphashes13

Source: https://docs.rs/minhash-rs/latest/minhash_rs/atomic/trait.AtomicFetchInsert.html?search=u32+-%3E+bool

Atomically inserts a value into the MinHash structure using the SipHash-1-3 hashing algorithm.

```APIDOC
### fn fetch_insert_with_siphashes13<V, Hash>(&self, value: V, ordering: Ordering)

#### Description
Insert atomically using SipHash-1-3 with default keys as the raw hasher and `Hash` as the internal hash stream width.

#### Parameters
- **value** (V) - The value to insert, must implement CoreHash.
- **ordering** (Ordering) - The memory ordering for the atomic operation.

#### Constraints
- **V**: CoreHash
- **Hash**: HashType + Primitive<Self::Word>
```

--------------------------------

### fn xorshift(self) -> Self

Source: https://docs.rs/minhash-rs/latest/minhash_rs/xorshift/trait.XorShift.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Advances the current value through the xorshift sequence and returns the next value.

```APIDOC
## fn xorshift(self) -> Self

### Description
Returns the next value in the xorshift sequence.

### Signature
`fn xorshift(self) -> Self`

### Implementations
- `u32`
- `u64`
```

--------------------------------

### LshIndex::top_k

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/index.html?search=std%3A%3Avec

Queries the LSH index to find the top K candidates for a given query signature, using a provided QueryState buffer.

```APIDOC
## LshIndex::top_k

### Description
Queries the index for the top K candidates that collide with the provided query signature. Candidates are ranked by the number of bands they collided in.

### Signature
`pub fn top_k(&self, query: &K, k: usize, state: &mut QueryState) -> Vec<(usize, f64)>`

### Parameters
- **query** (&K) - The signature to query against the index.
- **k** (usize) - The number of top candidates to return.
- **state** (&mut QueryState) - A reusable scratch buffer for the query operation.
```

--------------------------------

### SparseHashes Methods

Source: https://docs.rs/minhash-rs/latest/minhash_rs/sparse_hashes/struct.SparseHashes.html?search=

Methods available for interacting with the SparseHashes sketch, including creation, status checks, and data retrieval.

```APIDOC
## pub fn new() -> Self

### Description
Creates a new empty sketch in sparse mode.

## pub fn is_sparse(&self) -> bool

### Description
Returns true if the sketch is still holding the sparse hash list.

## pub fn is_dense(&self) -> bool

### Description
Returns true if the sketch has been promoted to dense mode.

## pub fn count(&self) -> usize

### Description
Returns the number of distinct digests currently held in sparse mode. Returns 0 in dense mode.

## pub fn distinct_hashes(&self) -> Option<usize>

### Description
Returns the number of distinct digests currently held. Returns Some(count) while the sketch is in sparse mode, and None once it has densified.

## pub fn hashes(&self) -> Option<impl Iterator<Item = Hash> + '_>

### Description
Iterates the distinct digests currently held, in ascending order. Returns Some(iterator) while the sketch is in sparse mode, and None once it has densified.
```

--------------------------------

### pub fn compute_candidates

Source: https://docs.rs/minhash-rs/latest/minhash_rs/index/fn.compute_candidates.html

Queries a compressed sparse row band layout for candidates that collide with the provided query.

```APIDOC
## compute_candidates

### Description
Queries a compressed sparse row band layout for candidates that collide with `query`, ranked by descending collision count then ascending id. This function is used by `LshIndex::candidates` and mmap-loaded `LshIndexRepr::DeserType`.

### Signature
`pub fn compute_candidates<'state, K, const PERMUTATIONS: usize, const BANDS: usize>(band_starts: &[u32; BANDS], band_entries: &[BandEntry], query: &K, state: &'state mut QueryState) -> &'state [Candidate]`

### Parameters
- **band_starts** (&[u32; BANDS]) - The starting indices of bands in the compressed sparse row layout.
- **band_entries** (&[BandEntry]) - The slice of band entries to search.
- **query** (&K) - The query object implementing `MinHasher`.
- **state** (&'state mut QueryState) - Mutable reference to the query state used for tracking.

### Returns
- **&'state [Candidate]** - A slice of candidates that collide with the query, ranked by descending collision count and ascending ID.
```

--------------------------------

### MinHash Operations

Source: https://docs.rs/minhash-rs/latest/minhash_rs/minhash/struct.MinHash.html?search=std%3A%3Avec

Core methods for interacting with the MinHash sketch, including insertion, membership testing, and similarity estimation.

```APIDOC
## fn insert(&mut self, value: Value) -> Outcome

### Description
Inserts a value into the sketch. Returns an `Outcome` indicating the result of the insertion.

## fn may_contain(&self, value: Value) -> bool

### Description
Returns `true` if the sketch may contain the specified value. Dense sketches follow the classical MinHash false-positive profile.

## fn estimate_jaccard_index(&self, other: &Self) -> f64

### Description
Estimates the Jaccard similarity between two sketches of the same variant.

## fn band_hashes<const BANDS: usize>(&self) -> [u64; BANDS]

### Description
Computes `BANDS` band hashes over the dense representation of the sketch. Sparse operands materialize their dense representation once per call before hashing.
```
Tokens:
Raw