Boomphf

https://docs.rs/boomphf/latest/
Admin
Boomphf is a Rust library that implements the BBHash method for constructing minimal perfect hash...
Tokens:52,885
Snippets:443
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### BitVector Iteration Example

Source: https://docs.rs/boomphf/latest/src/boomphf/bitvector.rs.html

Demonstrates iterating over the set bits in a BitVector after insertions. Ensure the BitVector is initialized and elements are inserted before iterating.

```rust
bitvec.insert(99);
assert_eq!(
    bitvec.iter().collect::<Vec<_>>(),
    [1, 10, 19, 62, 63, 64, 65, 66, 99]
);
```

```rust
bitvec.insert(0);
bitvec.insert(127);
bitvec.insert(191);
bitvec.insert(255);
bitvec.insert(319);
assert_eq!(bitvec.iter().collect::<Vec<_>>(), [0, 127, 191, 255, 319]);
```

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

### Parallel Construction with Seed

Source: https://docs.rs/boomphf/latest/boomphf/struct.Mphf.html

Constructs an MPHF in parallel using the rayon threadpool. Allows specifying a starting seed for reproducibility.

```rust
pub fn new_parallel(
 gamma: f64,
 objects: &[T],
 starting_seed: Option<u64>,
) -> Mphf<T>
```

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

### Crossbeam Thread Scope Example

Source: https://docs.rs/boomphf/latest/src/boomphf/lib.rs.html

Demonstrates the use of `crossbeam_utils::thread::scope` for managing threads and joining their results. This test is conditional on the 'parallel' feature.

```rust
fn check_crossbeam_scope() {
    crossbeam_utils::thread::scope(|scope| {
        let mut handles = vec![];
        for i in 0..2 {
            let h = scope.spawn(move |_| i * i);
            handles.push(h);
        }

        for (i, h) in handles.into_iter().enumerate() {
            assert_eq!(i * i, h.join().unwrap());
        }
    })
    .unwrap()
}
```

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

### ConstructibleKey Trait Implementation Example

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/trait.ConstructibleKey.html

Shows how the ConstructibleKey trait can be implemented for any type T that satisfies the Hash, Debug, PartialEq, Send, and Sync bounds. This implementation is available only when the 'parallel' crate feature is enabled.

```rust
impl<T> ConstructibleKey for T
where T: Hash + Debug + PartialEq + Send + Sync,
Available on **crate feature`parallel`** only.
```

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

### get

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Retrieves the primary and auxiliary values associated with a given key. It's crucial to use keys that were present during the hash map's creation. Querying with an unknown key might return `Some` with arbitrary data or `None`.

```APIDOC
## get

### Description
Retrieves an immutable reference to the primary and auxiliary values associated with a key. This method is intended for use with keys that were originally inserted into the hash map. Providing a key not used during creation may result in unpredictable behavior, returning `Some` with random data or `None`.

### Signature
```rust
pub fn get<Q: ?Sized>(&self, kmer: &Q) -> Option<(&D1, &D2)>
where
    K: Borrow<Q>,
    Q: Hash + Eq,
```

### Parameters
* `kmer`: A reference to the key to look up. The key type `Q` must implement `Hash` and `Eq`, and the map's key type `K` must be able to borrow `Q`.

### Returns
An `Option` containing a tuple of immutable references to the primary (`D1`) and auxiliary (`D2`) values if the key is found and successfully hashed. Returns `None` if the key cannot be hashed to a valid position.
```

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

### Get mutable value from BoomHashMap2

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Retrieves a mutable reference to a key-value pair from `BoomHashMap2`. Similar to `get`, it uses hashing to find the potential position and verifies the key before returning mutable references.

```rust
pub fn get_mut<Q: ?Sized>(&mut self, kmer: &Q) -> Option<(&mut D1, &mut D2)>
    where
        K: Borrow<Q>,
        Q: Hash + Eq,
    {
        let maybe_pos = self.mphf.try_hash(kmer);
        match maybe_pos {
            Some(pos) => {
                let hashed_kmer = &self.keys[pos as usize];
                if kmer == hashed_kmer.borrow() {
                    Some((
                        &mut self.values[pos as usize],
                        &mut self.aux_values[pos as usize],
                    ))
                } else {
                    None
                }
            }
            None => None,
        }
    }
```

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

### Generate and Use Minimal Perfect Hash Function (MPHF)

Source: https://docs.rs/boomphf/latest/boomphf

Demonstrates how to generate an MPHF from a set of objects and then retrieve the hash values for each object. Ensure that the input objects are hashable and that the generated hashes are sorted to compare against the expected contiguous range.

```rust
use boomphf::*;
// Generate MPHF
let possible_objects = vec![1, 10, 1000, 23, 457, 856, 845, 124, 912];
let n = possible_objects.len();
let phf = Mphf::new(1.7, &possible_objects);
// Get hash value of all objects
let mut hashes = Vec::new();
for v in possible_objects {
    hashes.push(phf.hash(&v));
}
hashes.sort();

// Expected hash output is set of all integers from 0..n
let expected_hashes: Vec<u64> = (0 .. n as u64).collect();
assert!(hashes == expected_hashes)
```

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

### Mutably Get Value from BoomHashMap

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Provides mutable access to the value associated with a key. Similar to `get`, it uses the MPHF for efficient lookup. Be aware that querying with a non-existent key might yield unexpected results.

```rust
pub fn get_mut<Q: ?Sized>(&mut self, kmer: &Q) -> Option<&mut D>
where
    K: Borrow<Q>,
    Q: Hash + Eq,
{
    let maybe_pos = self.mphf.try_hash(kmer);
    match maybe_pos {
        Some(pos) => {
            let hashed_kmer = &self.keys[pos as usize];
            if kmer == hashed_kmer.borrow() {
                Some(&mut self.values[pos as usize])
            } else {
                None
            }
        }
        None => None,
    }
}
```

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

### Parallel MPHF Construction Loop

Source: https://docs.rs/boomphf/latest/src/boomphf/lib.rs.html

This snippet illustrates the main loop for constructing a parallel MPHF. It manages iteration limits, remaining keys, buffer sizes, and spawns threads for parallel processing. It also handles the accumulation of bitvectors and processes any buffered keys after the main loop.

```rust
            if max_iters.is_some() && iter > max_iters.unwrap() {
                error!("ran out of key space. items: {:?}", global.done_keys.len());
                panic!("counldn't find unique hashes");
            }

            let keys_remaining = if iter == 0 {
                n
            } else {
                n - global.done_keys.len()
            };
            if keys_remaining == 0 {
                break;
            }
            if keys_remaining < MAX_BUFFER_SIZE && keys_remaining < min_buffer_keys_threshold {
                global.buffer_keys.store(true, Ordering::SeqCst);
            }

            let size = std::cmp::max(255, (gamma * keys_remaining as f64) as u64);
            let cx = Arc::new(IterContext {
                done_keys_count: AtomicU64::new(0),
                work_queue: Mutex::new(Queue::new(objects, n)),
                collide: BitVector::new(size),
                a: BitVector::new(size),
            });

            crossbeam_utils::thread::scope(|scope| {
                for _ in 0..num_threads {
                    let global = global.clone();
                    let cx = cx.clone();

                    scope.spawn(move |_| {
                        loop {
                            let (mut node, job_id, offset, num_keys) =
                                match cx.work_queue.lock().unwrap().next(&cx.done_keys_count) {
                                    None => break,
                                    Some(val) => val,
                                };

                            let mut node_pos = 0;
                            for index in 0..num_keys {
                                let key_index = offset + index;
                                if global.done_keys.contains(key_index) {
                                    continue;
                                }

                                let key = node.nth((index - node_pos) as usize).unwrap();
                                node_pos = index + 1;

                                let idx = hashmod(iter, &key, size);
                                let collision = cx.collide.contains(idx);
                                if job_id == 0 {
                                    if !collision && !cx.a.insert(idx) {
                                        cx.collide.insert(idx);
                                    }
                                }
                                 else if collision {
                                    cx.a.remove(idx);
                                    if global.buffer_keys.load(Ordering::SeqCst) {
                                        global.buffered_keys.lock().unwrap().push(key);
                                    }
                                }
                                 else {
                                    global.done_keys.insert(key_index);
                                }
                            }

                            cx.done_keys_count.fetch_add(num_keys, Ordering::SeqCst);
                        } //end-loop
                    }); //end-scope
                } //end-threads-for
            })
            .unwrap(); //end-crossbeam

            match Arc::try_unwrap(cx) {
                Ok(cx) => bitvecs.push(cx.a),
                Err(_) => unreachable!(),
            }

            iter += 1;
            if global.buffer_keys.load(Ordering::SeqCst) {
                break;
            }
        } //end-loop

        let buffered_keys_vec = global.buffered_keys.lock().unwrap();
        if buffered_keys_vec.len() > 1 {
            let mut buffered_mphf = Mphf::new_parallel(1.7, &buffered_keys_vec, Some(iter));

            for i in 0..buffered_mphf.bitvecs.len() {
                let buff_vec =
                    std::mem::replace(&mut buffered_mphf.bitvecs[i].0, BitVector::new(0));
                bitvecs.push(buff_vec);
            }
        }

        Mphf {
            bitvecs: Self::compute_ranks(bitvecs),
            phantom: PhantomData,
        }
    }
}
```

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

### Mutably Get Value from NoKeyBoomHashMap2

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Provides mutable access to the values associated with a key. Similar to `get`, the key must have been present during map creation. Modifying values for unknown keys is not supported and may lead to undefined behavior.

```rust
pub fn get_mut<Q: ?Sized>(&mut self, kmer: &Q) -> Option<(&mut D1, &mut D2)>
    where
        K: Borrow<Q>,
        Q: Hash + Eq,
    {
        let maybe_pos = self.mphf.try_hash(kmer);
        maybe_pos.map(|pos| {
            (
                &mut self.values[pos as usize],
                &mut self.aux_values[pos as usize],
            )
        })
    }
```

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

### take

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomIterator.html

Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner.

```APIDOC
## fn take(self, n: usize) -> Take<Self>

### Description
Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner.

### Parameters
- `n`: The maximum number of elements to yield.
```

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

### Get Mutable Value from NoKeyBoomHashMap

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.NoKeyBoomHashMap.html

Provides mutable access to the value associated with a given key. Similar to `get`, this method requires a key that was used during the map's initialization. Incorrect keys may lead to unexpected results.

```rust
pub fn get_mut<Q>(&mut self, kmer: &Q) -> Option<&mut D1>
where K: Borrow<Q>, Q: Hash + Eq + ?Sized,
```

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

### Get Length of BoomHashMap2

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomHashMap2.html

Returns the number of key-value pairs stored in the hash map.

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

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

### QuickCheck for u64 HashSet

Source: https://docs.rs/boomphf/latest/src/boomphf/lib.rs.html

Uses QuickCheck to verify the correctness of the MPHF for HashSets of u64.

```rust
quickcheck! {
    fn check_u64(v: HashSet<u64>) -> bool {
        check_mphf(v)
    }
}
```

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

### Get Type ID

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomHashMap2.html

Returns the `TypeId` of the current type. This is a fundamental method for runtime type identification.

```rust
fn type_id(&self) -> TypeId
```

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

### Get Key by ID from BoomHashMap2

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomHashMap2.html

Retrieves a reference to the key associated with a given internal ID (index).

```rust
pub fn get_key(&self, id: usize) -> Option<&K>
```

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

### NoKeyBoomHashMap2 Initialization and Memory Management

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.NoKeyBoomHashMap2.html

Provides functions for initializing, dereferencing, and dropping elements within the NoKeyBoomHashMap2.

```APIDOC
## unsafe fn init(init: <T as Pointable>::Init) -> usize

### Description
Initializes a with the given initializer.

### Parameters
- **init** (<T as Pointable>::Init) - Description of the initializer.

### Returns
- usize - The pointer to the initialized object.
```

```APIDOC
## unsafe fn deref<'a>(ptr: usize) -> &'a T

### Description
Dereferences the given pointer to provide immutable access to the object.

### Parameters
- **ptr** (usize) - The pointer to dereference.

### Returns
- &'a T - An immutable reference to the object.
```

```APIDOC
## unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

### Description
Mutably dereferences the given pointer to provide mutable access to the object.

### Parameters
- **ptr** (usize) - The pointer to mutably dereference.

### Returns
- &'a mut T - A mutable reference to the object.
```

```APIDOC
## unsafe fn drop(ptr: usize)

### Description
Drops the object pointed to by the given pointer, releasing its resources.

### Parameters
- **ptr** (usize) - The pointer to the object to be dropped.
```

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

### QuickCheck for Vec<u8> HashSet

Source: https://docs.rs/boomphf/latest/src/boomphf/lib.rs.html

Uses QuickCheck to verify the correctness of the MPHF for HashSets of Vec<u8>.

```rust
quickcheck! {
    fn check_vec_u8(v: HashSet<Vec<u8>>) -> bool {
        check_mphf(v)
    }
}
```

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

### Iterator for Boom2Iterator

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.Boom2Iterator.html

Core iterator functionality, including getting the next item, size hints, and consuming operations.

```APIDOC
### impl<'a, K: Hash, D1, D2> Iterator for Boom2Iterator<'a, K, D1, D2>

#### type Item = (&'a K, &'a D1, &'a D2)
The type of the elements being iterated over.

#### fn next(&mut self) -> Option<Self::Item>
Advances the iterator and returns the next value.

#### fn size_hint(&self) -> (usize, Option<usize>)
Returns the bounds on the remaining length of the iterator.

#### fn next_chunk<const N: usize>( &mut self, ) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>
Advances the iterator and returns an array containing the next `N` values. (Nightly-only experimental API)

#### fn count(self) -> usize
Consumes the iterator, counting the number of iterations and returning it.

#### fn last(self) -> Option<Self::Item>
Consumes the iterator, returning the last element.

#### fn advance_by(&mut self, n: usize) -> Result<(), NonZero<usize>>
Advances the iterator by `n` elements. (Nightly-only experimental API)

#### fn nth(&mut self, n: usize) -> Option<Self::Item>
Returns the `n`th element of the iterator.

#### fn step_by(self, step: usize) -> StepBy<Self>
Creates an iterator starting at the same point, but stepping by the given amount at each iteration.

#### fn chain<U>(self, other: U) -> Chain<Self, <U as IntoIterator>::IntoIter>
Takes two iterators and creates a new iterator over both in sequence.

#### fn zip<U>(self, other: U) -> Zip<Self, <U as IntoIterator>::IntoIter>
‘Zips up’ two iterators into a single iterator of pairs.

#### fn intersperse(self, separator: Self::Item) -> Intersperse<Self>
Creates a new iterator which places a copy of `separator` between adjacent items of the original iterator. (Nightly-only experimental API)

#### fn intersperse_with<G>(self, separator: G) -> IntersperseWith<Self, G>
Creates a new iterator which places an item generated by `separator` between adjacent items of the original iterator. (Nightly-only experimental API)

#### fn map<B, F>(self, f: F) -> Map<Self, F>
Takes a closure and creates an iterator which calls that closure on each element.

#### fn for_each<F>(self, f: F)
Calls a closure on each element of an iterator.

#### fn filter<P>(self, predicate: P) -> Filter<Self, P>
Creates an iterator which uses a closure to determine if an element should be yielded.

#### fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F>
Creates an iterator that both filters and maps.

#### fn enumerate(self) -> Enumerate<Self>
Creates an iterator which gives the current iteration count as well as the next value.

#### fn peekable(self) -> Peekable<Self>
Creates an iterator which can use the `peek` and `peek_mut` methods to look at the next element of the iterator without consuming it.

#### fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P>
Creates an iterator that `skip`s elements based on a predicate.

#### fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P>
Creates an iterator that yields elements based on a predicate.
```

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

### Get key by ID in BoomHashMap2

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Retrieves a reference to a key given its index (ID). Returns `None` if the ID is out of bounds.

```rust
pub fn get_key(&self, id: usize) -> Option<&K> {
        let max_key_id = self.len();
        if id > max_key_id {
            None
        } else {
            Some(&self.keys[id])
        }
    }
```

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

### QuickCheck for isize HashSet

Source: https://docs.rs/boomphf/latest/src/boomphf/lib.rs.html

Uses QuickCheck to verify the correctness of the MPHF for HashSets of isize.

```rust
quickcheck! {
    fn check_isize(v: HashSet<isize>) -> bool {
        check_mphf(v)
    }
}
```

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

### Get word from BitVector (non-parallel)

Source: https://docs.rs/boomphf/latest/src/boomphf/bitvector.rs.html

Retrieves the value of a specific word (64-bit chunk) from the BitVector. This is used when the 'parallel' feature is not enabled.

```rust
return self.vector[word] as u64;
```

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

### QuickCheck for u32 HashSet

Source: https://docs.rs/boomphf/latest/src/boomphf/lib.rs.html

Uses QuickCheck to verify the correctness of the MPHF for HashSets of u32.

```rust
quickcheck! {
    fn check_u32(v: HashSet<u32>) -> bool {
        check_mphf(v)
    }
}
```

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

### Create BoomHashMap2 with Parallel Construction

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomHashMap2.html

Constructs a new BoomHashMap2 using a parallel algorithm for Mphf construction. This is beneficial for performance when dealing with large datasets.

```rust
pub fn new_parallel( keys: Vec<K>, data: Vec<D1>, aux_data: Vec<D2>, ) -> BoomHashMap2<K, D1, D2>
```

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

### BoomHashMap::get_mut

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomHashMap.html

Provides mutable access to the value associated with a given key. Similar to `get`, it returns `None` for unknown keys.

```APIDOC
## BoomHashMap::get_mut

### Description
Mutably get the value associated with `key`. You must use a key that was supplied during the creation of the BoomHashMap. Querying for a new key will yield `Some` with a random value, or `None`. Querying with a valid key will always return `Some`.

### Signature
```rust
pub fn get_mut<Q>(&mut self, kmer: &Q) -> Option<&mut D>
where
    K: Borrow<Q>,
    Q: Hash + Eq + ?Sized,
```
```

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

### NoKeyBoomHashMap::get_mut

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.NoKeyBoomHashMap.html

Retrieves a mutable reference to the value associated with a given key. Similar to `get`, keys must have been present during creation.

```APIDOC
## NoKeyBoomHashMap::get_mut

### Description
Mutably get the value associated with `key`. You must use a key that was supplied during the creation of the BoomHashMap. Querying for a new key will yield `Some` with a random value, or `None`. Querying with a valid key will always return `Some`.

### Signature
```rust
pub fn get_mut<Q>(&mut self, kmer: &Q) -> Option<&mut D1>
```

### Parameters
- `kmer`: A reference to the key to query.

### Returns
- `Some(&mut D1)`: If the key is found, returns a mutable reference to the associated value.
- `None`: If the key is not found (or if a new key is queried).
```

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

### Implement Iterator for KeyValIter

Source: https://docs.rs/boomphf/latest/src/boomphf/par_iter.rs.html

Provides the core iteration logic for `KeyValIter`, including `next`, `size_hint`, and `next_back` for double-ended iteration.

```rust
impl<'data, K, V> Iterator for KeyValIter<'data, K, V> {
    type Item = (&'data K, &'data V);

    fn next(&mut self) -> Option<Self::Item> {
        if self.keys.is_empty() {
            return None;
        }
        let item = (&self.keys[0], &self.values[0]);
        self.keys = &self.keys[1..];
        self.values = &self.values[1..];
        Some(item)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        (self.keys.len(), Some(self.keys.len()))
    }
}

impl<'data, K, V> ExactSizeIterator for KeyValIter<'data, K, V> {}

impl<'data, K, V> DoubleEndedIterator for KeyValIter<'data, K, V> {
    fn next_back(&mut self) -> Option<Self::Item> {
        if self.keys.is_empty() {
            return None;
        }
        let len = self.keys.len();
        let item = (&self.keys[len - 1], &self.values[len - 1]);
        self.keys = &self.keys[..len - 1];
        self.values = &self.values[..len - 1];
        Some(item)
    }
}
```

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

### Get Rank of a Hash

Source: https://docs.rs/boomphf/latest/src/boomphf/lib.rs.html

Retrieves the rank of a given hash within a specific level of the MPHF. This is a crucial internal method for hash lookups.

```rust
fn get_rank(&self, hash: u64, i: usize) -> u64 {
        let idx = hash as usize;
        let (bv, ranks) = self.bitvecs.get(i).expect("that level doesn't exist");

        // Last pre-computed rank
        let mut rank = ranks[idx / 512];

        // Add rank of intervening words
        for j in (idx / 64) & !7..idx / 64 {
            rank += bv.get_word(j).count_ones() as u64;
        }

        // Add rank of final word up to hash
        let final_word = bv.get_word(idx / 64);
        if idx % 64 > 0 {
            rank += (final_word << (64 - (idx % 64))).count_ones() as u64;
        }
        rank
    }
```

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

### BitVector Equality Comparison (eq)

Source: https://docs.rs/boomphf/latest/src/boomphf/bitvector.rs.html

Demonstrates the equality (`==`) and inequality (`!=`) operators for BitVectors. Ensure both vectors have the same capacity and bit pattern for equality.

```rust
let mut bitvec = BitVector::new(50);
for i in &[0, 1, 3, 5, 11, 12, 19, 23] {
    bitvec.insert(*i);
}
let mut bitvec2 = BitVector::new(50);
for i in &[0, 1, 3, 5, 7, 11, 13, 17, 19, 23] {
    bitvec2.insert(*i);
}
let mut bitvec3 = BitVector::new(50);
for i in &[0, 1, 3, 5, 11, 12, 19, 23] {
    bitvec3.insert(*i);
}

assert!(bitvec != bitvec2);
assert!(bitvec == bitvec3);
assert!(bitvec2 != bitvec3);
```

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

### partition

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomIterator.html

Consumes an iterator, creating two collections based on a predicate.

```APIDOC
## fn partition<B, F>(self, f: F) -> (B, B)

### Description
Consumes an iterator, creating two collections from it.

### Parameters
- `f`: A closure that takes a reference to an item and returns `bool` to determine which collection it belongs to.

### Constraints
- `B` must implement `Default` and `Extend<Self::Item>`.
```

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

### Get Key by ID in BoomHashMap

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Retrieves a reference to the key at a specific index. This method includes bounds checking to ensure the provided ID is valid.

```rust
pub fn get_key(&self, id: usize) -> Option<&K> {
    let max_key_id = self.len();
    if id > max_key_id {
        None
    } else {
        Some(&self.keys[id])
    }
}
```

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

### map_windows

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.Boom2Iterator.html

Calls a function for each contiguous window of size `N` over the iterator and returns an iterator over the results. This is a nightly-only experimental API.

```APIDOC
## fn map_windows<F, R, const N: usize>(self, f: F) -> MapWindows<Self, F, N>

### Description
Calls the given function `f` for each contiguous window of size `N` over `self` and returns an iterator over the outputs of `f`. Like `slice::windows()`, the windows during mapping overlap as well.

### Constraints
- This is a nightly-only experimental API.

### Parameters
- `f`: A closure that takes a slice representing the window and returns a value `R`.
```

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

### Get Key ID in BoomHashMap

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomHashMap.html

Finds the index (position in the MPHF) of a given key. This can be useful for internal operations or when needing the key's identifier.

```rust
pub fn get_key_id<Q>(&self, kmer: &Q) -> Option<usize>
where K: Borrow<Q>, Q: Hash + Eq + ?Sized,
```

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

### Create BoomHashMap with new_parallel

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomHashMap.html

Constructs a new BoomHashMap using a parallelized method for building the internal MPHF. This can be faster for large datasets.

```rust
pub fn new_parallel(keys: Vec<K>, data: Vec<D>) -> BoomHashMap<K, D>
```

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

### NoKeyBoomHashMap::get_mut

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Provides mutable access to the value associated with a given key. Similar to `get`, it's essential to use original keys for reliable results.

```APIDOC
## NoKeyBoomHashMap::get_mut

### Description
Mutably get the value associated with `key`. You must use a key that was supplied during the creation of the BoomHashMap. Querying for a new key will yield `Some` with a random value, or `None`. Querying with a valid key will always return `Some`.

### Signature
```rust
pub fn get_mut<Q: ?Sized>(&mut self, kmer: &Q) -> Option<&mut D1>
```

### Parameters
- `kmer`: The key to look up. Must implement `Hash` and `Eq`, and be borrowable from `K`.

### Returns
An `Option` containing a mutable reference to the associated value if the key is found, otherwise `None`.
```

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

### Quickcheck for String Slices

Source: https://docs.rs/boomphf/latest/src/boomphf/lib.rs.html

A QuickCheck test that verifies the `check_mphf` function with a HashSet of String vectors.

```rust
fn check_string(v: HashSet<Vec<String>>) -> bool {
    check_mphf(v)
}
```

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

### BitVector Ones Initialization

Source: https://docs.rs/boomphf/latest/src/boomphf/bitvector.rs.html

Tests the `BitVector::ones` constructor, which creates a BitVector of a given capacity with all bits set to one. Verifies that all bits are present using `contains` and iteration.

```rust
let bvec = BitVector::ones(60);
for i in 0..60 {
    assert!(bvec.contains(i));
}
assert_eq!(bvec.iter().collect::<Vec<_>>(), (0..60).collect::<Vec<_>>());
```

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

### Get word from BitVector (parallel)

Source: https://docs.rs/boomphf/latest/src/boomphf/bitvector.rs.html

Retrieves the value of a specific word (64-bit chunk) from the BitVector using atomic load. This is used when the 'parallel' feature is enabled.

```rust
return self.vector[word].load(Ordering::Relaxed) as u64;
```

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

### Get the Number of Elements in BitVector

Source: https://docs.rs/boomphf/latest/src/boomphf/bitvector.rs.html

Calculates and returns the total number of set bits (elements) in the BitVector. It iterates through the internal vector, counting set bits in each word.

```rust
pub fn len(&self) -> u64 {
    self.vector.iter().fold(0u64, |x0, x| {
        #[cfg(feature = "parallel")]
        return x0 + x.load(Ordering::Relaxed).count_ones() as u64;

        #[cfg(not(feature = "parallel"))]
        return x0 + x.count_ones() as u64;
    })
}
```

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

### Quickcheck for Integer Slices

Source: https://docs.rs/boomphf/latest/src/boomphf/lib.rs.html

A QuickCheck test that verifies the `check_chunked_mphf` and `check_chunked_mphf_parallel` functions with various integer slice configurations.

```rust
fn check_int_slices(v: HashSet<u64>, lens: Vec<usize>) -> bool {

    let mut lens = lens;

    let items: Vec<u64> = v.iter().cloned().collect();
    if lens.is_empty() || lens.iter().all(|x| *x == 0) {
        lens.clear();
        lens.push(items.len())
    }

    let mut slices: Vec<Vec<u64>> = Vec::new();

    let mut total = 0_usize;
    for slc_len in lens {
        let end = std::cmp::min(items.len(), total.saturating_add(slc_len));
        let slc = Vec::from(&items[total..end]);
        slices.push(slc);
        total = end;

        if total == items.len() {
            break;
        }
    }

    check_chunked_mphf(slices.clone(), total as u64) && check_chunked_mphf_parallel(slices, total as u64)
}
```

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

### Get Value from BoomHashMap

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomHashMap.html

Retrieves an optional reference to the value associated with a given key. Querying with a key not present during creation might return `Some` with a random value or `None`.

```rust
pub fn get<Q>(&self, kmer: &Q) -> Option<&D>
where K: Borrow<Q>, Q: Hash + Eq + ?Sized,
```

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

### Into Implementation

Source: https://docs.rs/boomphf/latest/boomphf/struct.Mphf.html

Enables converting an Mphf instance into another type that implements `From<Mphf<T>>`.

```rust
fn into(self) -> U
where
 U: From<T>,
```

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

### Get key ID from BoomHashMap2

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Returns the index (ID) of a key within `BoomHashMap2` if it exists. This method is useful for scenarios where you need the position of a key rather than its associated values.

```rust
pub fn get_key_id<Q: ?Sized>(&self, kmer: &Q) -> Option<usize>
    where
        K: Borrow<Q>,
        Q: Hash + Eq,
    {
        let maybe_pos = self.mphf.try_hash(kmer);
        match maybe_pos {
            Some(pos) => {
                let hashed_kmer = &self.keys[pos as usize];
                if kmer == hashed_kmer.borrow() {
                    Some(pos as usize)
                } else {
                    None
                }
            }
            None => None,
        }
    }
```

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

### Create NoKeyBoomHashMap2 with Keys

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.NoKeyBoomHashMap2.html

Constructs a new NoKeyBoomHashMap2 instance using a vector of keys, primary values, and auxiliary values. Ensure keys are unique and constructible.

```rust
pub fn new( keys: Vec<K>, values: Vec<D1>, aux_values: Vec<D2>, ) -> NoKeyBoomHashMap2<K, D1, D2>
```

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

### Get Mutable Value from BoomHashMap

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomHashMap.html

Retrieves a mutable reference to the value associated with a given key. Use with caution, as modifying values might affect data integrity if not handled properly.

```rust
pub fn get_mut<Q>(&mut self, kmer: &Q) -> Option<&mut D>
where K: Borrow<Q>, Q: Hash + Eq + ?Sized,
```

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

### Parallel MPHF Construction

Source: https://docs.rs/boomphf/latest/src/boomphf/lib.rs.html

Constructs a minimal perfect hash function in parallel using the rayon threadpool. Allows configuration of thread count via the rayon threadpool.

```rust
pub fn new_parallel(gamma: f64, objects: &[T], starting_seed: Option<u64>) -> Mphf<T> {
        assert!(gamma > 1.01);
        let mut bitvecs = Vec::new();
        let mut iter = 0;

        let cx = Context::new(
            std::cmp::max(255, (gamma * objects.len() as f64) as u64),
            starting_seed.unwrap_or(0) + iter,
        );

        objects.into_par_iter().for_each(|v| cx.find_collisions(v));
        let mut redo_keys = objects
            .into_par_iter()
            .filter_map(|v| cx.filter(v))
            .collect::<Vec<_>>();

        bitvecs.push(cx.a);
        iter += 1;

        while !redo_keys.is_empty() {
            let cx = Context::new(
                std::cmp::max(255, (gamma * redo_keys.len() as f64) as u64),
                starting_seed.unwrap_or(0) + iter,
            );

            (&redo_keys)
                .into_par_iter()
                .for_each(|&v| cx.find_collisions(v));
            redo_keys = (&redo_keys)
                .into_par_iter()
                .filter_map(|&v| cx.filter(v))
                .collect();

            bitvecs.push(cx.a);
            iter += 1;
            if iter > MAX_ITERS {
                println!("ran out of key space. items: {:?}", redo_keys);
                panic!("counldn't find unique hashes");
            }
        }
        Mphf {
            bitvecs: Self::compute_ranks(bitvecs),
            phantom: PhantomData,
        }
    }
```

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

### Create NoKeyBoomHashMap with Existing Mphf

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.NoKeyBoomHashMap.html

Initializes a NoKeyBoomHashMap using a pre-existing Mphf and a vector of values. This is useful when the Mphf has already been constructed or needs to be reused.

```rust
pub fn new_with_mphf(mphf: Mphf<K>, values: Vec<D1>) -> NoKeyBoomHashMap<K, D1>
```

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

### Get Key ID from BoomHashMap2

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomHashMap2.html

Retrieves the internal ID (index) of a key within the hash map. The key must implement `Borrow<Q>` where `Q` is the type of the lookup key.

```rust
pub fn get_key_id<Q>(&self, kmer: &Q) -> Option<usize>
```

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

### Create NoKeyBoomHashMap2 with Mphf

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Constructs a NoKeyBoomHashMap2 using a pre-existing Mphf, keys, and associated values. Ensure keys are unique and suitable for Mphf.

```rust
pub fn new_with_mphf(
        mphf: Mphf<K>,
        values: Vec<D1>,
        aux_values: Vec<D2>,
    ) -> NoKeyBoomHashMap2<K, D1, D2> {
        NoKeyBoomHashMap2 {
            mphf,
            values,
            aux_values,
        }
    }
```

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

### Get Values from BoomHashMap2

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomHashMap2.html

Retrieves references to the two associated values (D1 and D2) for a given key. The key must implement `Borrow<Q>` where `Q` is the type of the lookup key.

```rust
pub fn get<Q>(&self, kmer: &Q) -> Option<(&D1, &D2))>
```

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

### BoomHashMap2::new

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Constructs a new `BoomHashMap2` from provided vectors of keys, values, and auxiliary values. It internally creates a minimal perfect hash function.

```APIDOC
## BoomHashMap2::new

### Description
Constructs a new `BoomHashMap2` from provided vectors of keys, values, and auxiliary values. It internally creates a minimal perfect hash function.

### Signature
```rust
pub fn new(keys: Vec<K>, values: Vec<D1>, aux_values: Vec<D2>) -> BoomHashMap2<K, D1, D2>
```

### Parameters
- **keys** (Vec<K>): A vector of keys to be stored in the hash map.
- **values** (Vec<D1>): A vector of primary values associated with the keys.
- **aux_values** (Vec<D2>): A vector of auxiliary values associated with the keys.
```

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

### Get Value from NoKeyBoomHashMap2

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Retrieves the values associated with a key. The key must have been present during map creation for guaranteed results. Querying with unknown keys may return `Some` with arbitrary data or `None`.

```rust
pub fn get<Q: ?Sized>(&self, kmer: &Q) -> Option<(&D1, &D2)>
    where
        K: Borrow<Q>,
        Q: Hash + Eq,
    {
        let maybe_pos = self.mphf.try_hash(kmer);
        maybe_pos.map(|pos| (&self.values[pos as usize], &self.aux_values[pos as usize]))
    }
```

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

### Mphf::new Constructor

Source: https://docs.rs/boomphf/latest/src/boomphf/lib.rs.html

Generates a minimal perfect hash function for a given set of objects. Ensures no duplicate items are present and uses `gamma` to balance construction time, runtime speed, and data structure size.

```rust
pub fn new(gamma: f64, objects: &[T]) -> Mphf<T> {
        assert!(gamma > 1.01);
        let mut bitvecs = Vec::new();
        let mut iter = 0;

        let mut cx = Context::new(
            std::cmp::max(255, (gamma * objects.len() as f64) as u64),
            iter,
        );

        objects.iter().for_each(|v| cx.find_collisions_sync(v));
        let mut redo_keys = objects
            .iter()
            .filter_map(|v| cx.filter(v))
            .collect::<Vec<_>>();

        bitvecs.push(cx.a);
        iter += 1;

        while !redo_keys.is_empty() {
            let mut cx = Context::new(
                std::cmp::max(255, (gamma * redo_keys.len() as f64) as u64),
                iter,
            );

            
```

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

### Get Key ID in BoomHashMap

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Returns the index (ID) of a key within the internal dense array if the key exists. This can be useful for scenarios where you need to reference the key's position directly.

```rust
pub fn get_key_id<Q: ?Sized>(&self, kmer: &Q) -> Option<usize>
where
    K: Borrow<Q>,
    Q: Hash + Eq,
{
    let maybe_pos = self.mphf.try_hash(kmer);
    match maybe_pos {
        Some(pos) => {
            let hashed_kmer = &self.keys[pos as usize];
            if kmer == hashed_kmer.borrow() {
                Some(pos as usize)
            } else {
                None
            }
        }
        None => None,
    }
}
```

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

### Create NoKeyBoomHashMap2 in Parallel

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.NoKeyBoomHashMap2.html

Constructs a new NoKeyBoomHashMap2 instance in parallel, using a vector of keys, primary values, and auxiliary values. This can be faster for large datasets.

```rust
pub fn new_parallel( keys: Vec<K>, values: Vec<D1>, aux_values: Vec<D2>, ) -> NoKeyBoomHashMap2<K, D1, D2>
```

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

### NoKeyBoomHashMap2::get_mut

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.NoKeyBoomHashMap2.html

Provides mutable access to the values associated with a given key. Similar to `get`, only keys present during creation should be used. Querying with an unknown key might yield unexpected results.

```APIDOC
## NoKeyBoomHashMap2::get_mut

### Description
Provides mutable access to the values associated with a given key. Similar to `get`, only keys present during creation should be used. Querying with an unknown key might yield unexpected results. Querying with a valid key will always return `Some`.

### Signature
```rust
pub fn get_mut<Q>(&mut self, kmer: &Q) -> Option<(&mut D1, &mut D2)>
```

### Parameters
* `kmer`: A reference to the key to query.

### Returns
An `Option` containing a tuple of mutable references to the primary value (`&mut D1`) and the auxiliary value (`&mut D2`) if the key is found, otherwise `None`.
```

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

### Try Hash Item (May Not Be Present)

Source: https://docs.rs/boomphf/latest/src/boomphf/lib.rs.html

Attempts to compute the hash value for an item. Returns `Some(hash)` if the item was in the construction set, otherwise returns `None`.

```rust
pub fn try_hash<Q>(&self, item: &Q) -> Option<u64>
    where
        T: Borrow<Q>,
        Q: ?Sized + Hash,
    {
        for i in 0..self.bitvecs.len() {
            let (bv, _) = &(self.bitvecs)[i];
            let hash = hashmod(i as u64, item, bv.capacity() as u64);

            if bv.contains(hash) {
                return Some(self.get_rank(hash, i));
            }
        }

        None
    }
```

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

### BoomHashMap::new

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Creates a new `BoomHashMap` from a vector of keys and a vector of associated data. It automatically builds an MPHF for efficient lookups.

```APIDOC
## BoomHashMap::new

### Description
Creates a new hash map from the parallel array `keys` and `values`.

### Method
`pub fn new(keys: Vec<K>, data: Vec<D>) -> BoomHashMap<K, D>`

### Parameters
- **keys** (Vec<K>) - A vector of keys to be stored in the hash map.
- **data** (Vec<D>) - A vector of data associated with the keys. The order must correspond to the `keys` vector.

### Returns
A new `BoomHashMap` instance.

### Example
```rust
let keys = vec!["apple", "banana", "cherry"];
let values = vec![1, 2, 3];
let hash_map = BoomHashMap::new(keys, values);
```
```

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

### Get Mutable Values from BoomHashMap2

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomHashMap2.html

Retrieves mutable references to the two associated values (D1 and D2) for a given key. The key must implement `Borrow<Q>` where `Q` is the type of the lookup key.

```rust
pub fn get_mut<Q>(&mut self, kmer: &Q) -> Option<(&mut D1, &mut D2))>
```

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

### Create BoomHashMap2 with Mphf

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Constructs a `BoomHashMap2` using a pre-computed `Mphf`. This is the primary way to create the hash map when the `Mphf` is generated separately.

```rust
pub fn new(keys: Vec<K>, values: Vec<D1>, aux_values: Vec<D2>) -> BoomHashMap2<K, D1, D2> {
        let mphf = Mphf::new(1.7, &keys);
        Self::create_map(keys, values, aux_values, mphf)
    }
```

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

### Get value from BoomHashMap2

Source: https://docs.rs/boomphf/latest/src/boomphf/hashmap.rs.html

Retrieves a reference to a key-value pair from `BoomHashMap2` using a queryable key. It first attempts to hash the key to find a potential position and then verifies if the key at that position matches the queried key.

```rust
pub fn get<Q: ?Sized>(&self, kmer: &Q) -> Option<(&D1, &D2)>
    where
        K: Borrow<Q>,
        Q: Hash + Eq,
    {
        let maybe_pos = self.mphf.try_hash(kmer);
        match maybe_pos {
            Some(pos) => {
                let hashed_kmer = &self.keys[pos as usize];
                if kmer == hashed_kmer.borrow() {
                    Some((&self.values[pos as usize], &self.aux_values[pos as usize]))
                } else {
                    None
                }
            }
            None => None,
        }
    }
```

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

### Generate Minimal Perfect Hash Function (MPHF)

Source: https://docs.rs/boomphf/latest/boomphf/index.html

Generates an MPHF for a given set of objects and retrieves hash values for each object. Asserts that the generated hashes match the expected sequence from 0 to n-1. Minimal perfect hash functions are only valid for the set of objects used during creation.

```rust
use boomphf::*
// Generate MPHF
let possible_objects = vec![1, 10, 1000, 23, 457, 856, 845, 124, 912];
let n = possible_objects.len();
let phf = Mphf::new(1.7, &possible_objects);
// Get hash value of all objects
let mut hashes = Vec::new();
for v in possible_objects {
    hashes.push(phf.hash(&v));
}
hashes.sort();

// Expected hash output is set of all integers from 0..n
let expected_hashes: Vec<u64> = (0 .. n as u64).collect();
assert!(hashes == expected_hashes)
```

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

### Get Value from NoKeyBoomHashMap

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.NoKeyBoomHashMap.html

Retrieves a reference to the value associated with a given key. It is crucial to use a key that was present during the map's creation. Querying with an unknown key may return `Some` with a random value or `None`.

```rust
pub fn get<Q>(&self, kmer: &Q) -> Option<&D1>
where K: Borrow<Q>, Q: Hash + Eq + ?Sized,
```

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

### Create NoKeyBoomHashMap2 with Existing Mphf

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.NoKeyBoomHashMap2.html

Constructs a new NoKeyBoomHashMap2 instance using a pre-existing Mphf, along with primary and auxiliary values. This is useful if the Mphf has already been generated.

```rust
pub fn new_with_mphf( mphf: Mphf<K>, values: Vec<D1>, aux_values: Vec<D2>, ) -> NoKeyBoomHashMap2<K, D1, D2>
```

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

### BoomHashMap::new

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomHashMap.html

Creates a new BoomHashMap from parallel vectors of keys and values.

```APIDOC
## BoomHashMap::new

### Description
Create a new hash map from the parallel array `keys` and `values`.

### Signature
```rust
pub fn new(keys: Vec<K>, data: Vec<D>) -> BoomHashMap<K, D>
```
```

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

### by_ref

Source: https://docs.rs/boomphf/latest/boomphf/hashmap/struct.BoomIterator.html

Creates a reference adapter for the iterator, allowing mutable access to the iterator itself.

```APIDOC
## fn by_ref(&mut self) -> &mut Self

### Description
Creates a “by reference” adapter for this instance of `Iterator`.
```

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

### Clone Implementation

Source: https://docs.rs/boomphf/latest/boomphf/struct.Mphf.html

Provides the ability to create a duplicate of an existing Mphf instance.

```rust
fn clone(&self) -> Mphf<T>
```
Tokens:
Raw