hibitset

https://docs.rs/hibitset/0.6.4
Admin
hibitset provides hierarchical bit sets, which allow very fast iteration on sparse data structures.
Tokens:211,329
Snippets:1,972
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### BitSet::BITS_PER_USIZE Example

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html

Demonstrates how to assert that BitSet::BITS_PER_USIZE is equal to the number of bits in a usize.

```rust
use hibitset::BitSet;
assert_eq!(BitSet::BITS_PER_USIZE, std::mem::size_of::<usize>()*8);
```

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

### Example usage of BITS_PER_USIZE constant

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=

Demonstrates how to use the `BITS_PER_USIZE` constant to verify the number of bits in a `usize`.

```rust
    use hibitset::BitSet;
    assert_eq!(BitSet::BITS_PER_USIZE, std::mem::size_of::<usize>()*8);
```

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

### Example usage of LAYER1_GRANULARITY

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=

Demonstrates that the `LAYER1_GRANULARITY` constant is equivalent to `BITS_PER_USIZE`.

```rust
    use hibitset::BitSet;
    assert_eq!(BitSet::LAYER1_GRANULARITY, BitSet::BITS_PER_USIZE);
```

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

### BitSet Usage Example

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html

Demonstrates adding an index to a BitSet and accessing its layer2 representation. This is useful for understanding how BitSet internally manages large sets of indices efficiently.

```rust
use hibitset::BitSet;

let index: u32 = 12345;

let mut bitset = BitSet::new();
bitset.add(index);

// layer 2 summarizes multiple indexes per bit, so divide appropriately
let slice = bitset.layer2_as_slice();
let bit_index = index as usize / BitSet::LAYER2_GRANULARITY;

// map that bit index to a usize in the slice and a bit within that usize
let slice_index = bit_index / BitSet::BITS_PER_USIZE;
let bit_at_index = bit_index % BitSet::BITS_PER_USIZE;

assert_eq!(slice[slice_index], 1 << bit_at_index);
```

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

### BitSet::LAYER2_GRANULARITY Example

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html

Asserts that BitSet::LAYER2_GRANULARITY is equal to the product of BitSet::LAYER1_GRANULARITY and BitSet::BITS_PER_USIZE.

```rust
use hibitset::BitSet;
assert_eq!(BitSet::LAYER2_GRANULARITY, BitSet::LAYER1_GRANULARITY * BitSet::BITS_PER_USIZE);
```

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

### BitSet::LAYER1_GRANULARITY Example

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html

Asserts that BitSet::LAYER1_GRANULARITY is equal to BitSet::BITS_PER_USIZE.

```rust
use hibitset::BitSet;
assert_eq!(BitSet::LAYER1_GRANULARITY, BitSet::BITS_PER_USIZE);
```

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

### BitSet Structure Example

Source: https://docs.rs/hibitset/0.6.4/hibitset/index.html?search=u32+-%3E+bool

Illustrates the layered structure of a BitSet with an imaginary 4-bit usize. Higher layers summarize bits from lower layers.

```text
Layer 3: 1------------------------------------------------ ...
Layer 2: 1------------------ 1------------------ 0-------- ...
Layer 1: 1--- 0--- 0--- 0--- 1--- 0--- 1--- 0--- 0--- 0--- ...
Layer 0: 0010 0000 0000 0000 0011 0000 1111 0000 0000 0000 ...

```

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

### BitSet Layer Structure Example

Source: https://docs.rs/hibitset/0.6.4/hibitset/index.html?search=

Illustrates the hierarchical structure of BitSet layers, where each layer summarizes the layer below it. This structure enables efficient set operations.

```text
Layer 3: 1------------------------------------------------ ...
Layer 2: 1------------------ 1------------------ 0-------- ...
Layer 1: 1--- 0--- 0--- 0--- 1--- 0--- 1--- 0--- 0--- 0--- ...
Layer 0: 0010 0000 0000 0000 0011 0000 1111 0000 0000 0000 ...
```

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

### BitSet Parallel Iterator Example

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitParIter.html

Demonstrates how to create and use a parallel iterator over a BitSet. The layers_split method can be used to configure the number of layers for parallel processing.

```rust
let mut bitset = BitSet::new();
bitset.par_iter()
    .layers_split(2)
    .count();
```

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

### Example usage of layer0_as_slice

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=

Shows how to add an index to a BitSet and then access its layer0 slice to verify the bit is set. It details the mapping from an index to a slice index and a bit within that index.

```rust
    use hibitset::BitSet;

    let index: u32 = 12345;

    let mut bitset = BitSet::new();
    bitset.add(index);

    // layer 0 is 1:1 with Indexes, so we expect that bit in the slice to be set
    let slice = bitset.layer0_as_slice();
    let bit_index = index as usize;

    // map that bit index to a usize in the slice and a bit within that usize
    let slice_index = bit_index / BitSet::BITS_PER_USIZE;
    let bit_at_index = bit_index % BitSet::BITS_PER_USIZE;

    assert_eq!(slice[slice_index], 1 << bit_at_index);
```

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

### BitSet::get_from_layer

Source: https://docs.rs/hibitset/0.6.4/struct.BitSet.html

Gets the usize corresponding to a specific layer and index.

```APIDOC
## BitSet::get_from_layer

### Description
Retrieves the `usize` value from a specified layer at a given index.

### Method
Instance method

### Endpoint
N/A (instance method)

### Parameters
- **layer** (usize) - The layer from which to retrieve the value.
- **idx** (usize) - The index within the specified layer.

### Request Example
```rust
let value = bitset.get_from_layer(1, 5);
```

### Response
#### Success Response
- **usize**: The `usize` value found at the specified layer and index.

### Response Example
```rust
// Returns the usize value at the given layer and index
bitset.get_from_layer(layer, idx)
```
```

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

### Get Value from Layer (BitSetLike)

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.AtomicBitSet.html?search=u32+-%3E+bool

Gets the usize corresponding to a specific layer and index. This is part of the BitSetLike trait implementation.

```rust
fn get_from_layer(&self, layer: usize, idx: usize) -> usize
```

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

### init

Source: https://docs.rs/hibitset/0.6.4/struct.BitSet.html

Initializes a BitSet with a given initializer.

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

### Description
Initializes a with the given initializer.

### Method
`init`

### Parameters
* `init` (<T as Pointable>::Init) - The initializer for the BitSet.

### Request Example
None

### Response
#### Success Response
* `usize` - The pointer to the initialized BitSet.

#### Response Example
None
```

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

### type_id

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html

Gets the `TypeId` of the BitSet.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`type_id`

### Returns
The `TypeId` of the BitSet.
```

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

### type_id

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitIter.html?search=std%3A%3Avec

Gets the TypeId of the borrowed object.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Returns
The `TypeId` of the object.
```

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

### from

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitIter.html

Creates a new instance from a given value, returning the argument unchanged.

```APIDOC
## fn from(t: T) -> T

### Description
Returns the argument unchanged.

### Method
`from`

### Parameters
- `t`: The value to be converted.

### Returns
- `T`: The original value `t`.
```

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

### init

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html

Initializes a BitSet with a given initializer. This is an unsafe operation.

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

### Description
Initializes a with the given initializer.

### Method
`init`

### Parameters
#### Path Parameters
- **init** (<T as Pointable>::Init) - Required - The initializer for the BitSet.

### Returns
The size in bytes of the initialized BitSet.
```

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

### Any Trait Implementation

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitProducer.html?search=u32+-%3E+bool

Provides the `type_id` method for getting the `TypeId` of an object.

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

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

### BitSet::new

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html

Creates a new, empty BitSet.

```APIDOC
## BitSet::new()

### Description
Creates an empty `BitSet`.

### Method
`pub fn new() -> BitSet`
```

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

### type_id(&self) -> TypeId

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitIter.html?search=u32+-%3E+bool

Gets the TypeId of the `Any` trait object. This is part of the Any trait implementation.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Parameters
* `self`: A reference to the object implementing the `Any` trait.
```

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

### Get Pointer Alignment

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitParIter.html?search=

Constant defining the alignment of a pointer. Used in low-level memory operations.

```rust
const ALIGN: usize
```

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

### impl<T> CloneToUninit for T

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSetAll.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides nightly-only experimental API for cloning to uninitialized memory.

```APIDOC
## unsafe fn clone_to_uninit(&self, dest: *mut u8)

### Description
Performs copy-assignment from `self` to `dest`.

### Method
N/A (unsafe associated function)

### Endpoint
N/A

### Parameters
- **dest** (*mut u8): A mutable pointer to the destination memory.

### Request Example
N/A

### Response
None (operation is unsafe and modifies memory directly).
```

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

### BitIter::clear

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/iter/mod.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Clears the rest of the bitset starting from the next inner layer. This is a specialized method for mutable BitSet iterators.

```APIDOC
## BitIter::clear

### Description
Clears the rest of the bitset starting from the next inner layer.

### Method
`clear(&mut self)`

### Note
This method is available when iterating over a mutable `BitSet` (`&'a mut BitSet`). It modifies the underlying bitset by clearing subsequent bits.
```

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

### BitSet Constants

Source: https://docs.rs/hibitset/0.6.4/struct.BitSet.html

Demonstrates the usage of BitSet constants for understanding bit and index granularities.

```rust
use hibitset::BitSet;
assert_eq!(BitSet::BITS_PER_USIZE, std::mem::size_of::<usize>()*8);
```

```rust
use hibitset::BitSet;
assert_eq!(BitSet::LAYER1_GRANULARITY, BitSet::BITS_PER_USIZE);
```

```rust
use hibitset::BitSet;
assert_eq!(BitSet::LAYER2_GRANULARITY, BitSet::LAYER1_GRANULARITY * BitSet::BITS_PER_USIZE);
```

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

### BitSet Addition and Set Equality

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/ops.rs.html?search=std%3A%3Avec

Demonstrates adding elements to a BitSet and verifying its equality with a HashSet.

```rust
let mut hs = HashSet::new();
let mut set1 = HashSet::new();
let mut bitset = BitSet::new();
let mut rng = thread_rng();
let limit = 1000;

for _ in 0..limit {
    let index = rng.gen_range(0, limit);
    set1.insert(index);
    bitset.insert(index);
}

assert_eq!(bitset, set1.iter().collect());
```

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

### Get bits per usize constant (64-bit)

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=

Defines the number of bits in a `usize` for 64-bit systems. This constant is provided for clarity.

```rust
    #[cfg(target_pointer_width = "64")]
    pub const BITS_PER_USIZE: usize = 64;
```

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

### Get bits per usize constant (32-bit)

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=

Defines the number of bits in a `usize` for 32-bit systems. This constant is provided for clarity.

```rust
    #[cfg(target_pointer_width = "32")]
    pub const BITS_PER_USIZE: usize = 32;
```

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

### init

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitIter.html?search=std%3A%3Avec

Initializes a memory location with a given initializer. This is an unsafe operation requiring careful handling of memory.

```APIDOC
## init

### Description
Initializes a memory location with the given initializer. This is an unsafe operation.

### Method
`init`

### Parameters
- `init` (<T as Pointable>::Init): The initializer value for the memory location.

### Safety
This function is unsafe and requires the caller to ensure that the memory pointed to by `ALIGN` is valid and properly managed.
```

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

### BitSet Creation

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Methods for creating new BitSet instances.

```APIDOC
## Creation

### `new()`

- **Description**: Creates an empty `BitSet`.
- **Returns**: A new, empty `BitSet`.

### `with_capacity(max: u32)`

- **Description**: Creates an empty `BitSet`, preallocated for up to `max` indices.
- **Parameters**:
  - `max` (u32) - The maximum number of indices the `BitSet` should be able to hold.
- **Returns**: A new `BitSet` with the specified capacity.
```

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

### BitIter Clear Method

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/iter/mod.rs.html?search=std%3A%3Avec

Clears the rest of the bitset starting from the next inner layer. This method is specific to mutable references of BitSet.

```rust
pub(crate) fn clear(&mut self) {
        use self::State::Continue;
        while let Some(level) = (1..LAYERS).find(|&level| self.handle_level(level) == Continue) {
            let lower = level - 1;
            let idx = (self.prefix[lower] >> BITS) as usize;
            *self.set.layer_mut(lower, idx) = 0;
            if level == LAYERS - 1 {
                self.set.layer3 &= !((2 << idx) - 1);
            }
        }
    }
```

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

### BitSetLike::get_from_layer

Source: https://docs.rs/hibitset/0.6.4/hibitset/trait.BitSetLike.html?search=u32+-%3E+bool

Gets the usize corresponding to a given layer and index. The layer should be in the range [0, 3]. This is a provided method in the BitSetLike trait.

```APIDOC
## fn get_from_layer(&self, layer: usize, idx: usize) -> usize

### Description
Gets the `usize` corresponding to layer and index.

### Method
`get_from_layer`

### Parameters
#### Path Parameters
- **layer** (usize) - Required - The layer to retrieve data from (0-3).
- **idx** (usize) - Required - The index within the specified layer.

### Returns
- **usize** - The usize value corresponding to the layer and index.
```

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

### Get Optional Length of Parallel Iterator

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitParIter.html?search=

Internal method to determine the optional length of a parallel iterator. Typically not called directly by users.

```rust
fn opt_len(&self) -> Option<usize>
```

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

### Creating a BitSet with Capacity

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates an empty `BitSet` and preallocates internal storage to accommodate indices up to a specified maximum. Ensures the provided `max` index is within the valid range.

```Rust
/// Creates an empty `BitSet`, preallocated for up to `max` indices.
pub fn with_capacity(max: Index) -> BitSet {
    Self::valid_range(max);
    let mut value = BitSet::new();
    value.extend(max);
    value
}
```

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

### Get Layer 0 from AtomicBitSet

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.AtomicBitSet.html?search=u32+-%3E+bool

Returns a usize that maps directly to the 1:1 association with each index of the set. This is part of the BitSetLike trait implementation.

```rust
fn layer0(&self, i: usize) -> usize
```

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

### clone_to_uninit (Nightly Experimental)

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitIter.html?search=std%3A%3Avec

Performs a copy-assignment from the source to an uninitialized destination. This is an experimental, nightly-only feature.

```APIDOC
## clone_to_uninit

### Description
Performs copy-assignment from `self` to `dest`. This is a nightly-only experimental API.

### Method
`clone_to_uninit`

### Parameters
- `dest` (*mut u8): A mutable pointer to the destination memory location.

### Safety
This function is unsafe and requires the caller to ensure that `dest` is a valid, properly aligned, and sufficiently large memory location to hold a `T`.
```

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

### Constructor: DrainBitIter::new

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.DrainBitIter.html

Creates a new DrainBitIter. Typically, users should use the .drain() method on a bit set instead of calling this directly.

```rust
pub fn new(set: &'a mut T, masks: [usize; 4], prefix: [u32; 3]) -> Self
```

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

### Get Layer 1 from AtomicBitSet

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.AtomicBitSet.html?search=u32+-%3E+bool

Returns a usize from the array indicating if any bit has been set in layer 0. This is part of the BitSetLike trait implementation.

```rust
fn layer1(&self, i: usize) -> usize
```

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

### Get Layer 2 from AtomicBitSet

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.AtomicBitSet.html?search=u32+-%3E+bool

Returns a usize from the array indicating if any bit has been set in layer 1. This is part of the BitSetLike trait implementation.

```rust
fn layer2(&self, i: usize) -> usize
```

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

### BitSetXor Operations

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSetXor.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates the bitwise XOR operation on BitSetXor instances.

```APIDOC
## BitSetXor<A, B>

### Description
`BitSetXor` takes two `BitSetLike` items and returns a new virtual set representing the XOR of the two original sets.

### Tuple Fields
- `0: A`: The first `BitSetLike` item.
- `1: B`: The second `BitSetLike` item.

### Trait Implementations

#### BitXor<T> for BitSetXor<A, B>
Performs the `^` (XOR) operation.

- **Output Type**: `BitSetXor<BitSetXor<A, B>, T>`

#### BitXor<T> for &'a BitSetXor<A, B>
Performs the `^` (XOR) operation on a reference.

- **Output Type**: `BitSetXor<&'a BitSetXor<A, B>, T>`

#### BitSetLike for BitSetXor<A, B>
Implements the `BitSetLike` trait for `BitSetXor`, allowing it to be used in operations that expect a `BitSetLike`.

- **Methods**: `layer3`, `layer2`, `layer1`, `layer0`, `contains`, `get_from_layer`, `is_empty`, `iter`, `par_iter`

#### Clone for BitSetXor<A, B>
Allows cloning `BitSetXor` instances.

#### Debug for BitSetXor<A, B>
Allows debugging `BitSetXor` instances.

#### IntoIterator for BitSetXor<A, B>
Allows iterating over the elements of a `BitSetXor`.

#### IntoIterator for &'a BitSetXor<A, B>
Allows iterating over the elements of a referenced `BitSetXor`.
```

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

### BitSet Operator Implementations

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/ops.rs.html

Shows the macro-generated implementations for bitwise AND, OR, and XOR operators for `BitSet` and its references.

```rust
impl<$( $lifetime, )* $( $arg, )* T> BitOr<T> for $bitset
            where T: BitSetLike,
                  $( $arg: BitSetLike ),*
        {
            type Output = BitSetOr<Self, T>;
            fn bitor(self, rhs: T) -> Self::Output {
                BitSetOr(self, rhs)
            }
        }

        impl<$( $lifetime, )* $( $arg, )* T> BitXor<T> for $bitset
            where T: BitSetLike,
                  $( $arg: BitSetLike ),*
        {
            type Output = BitSetXor<Self, T>;
            fn bitxor(self, rhs: T) -> Self::Output {
                BitSetXor(self, rhs)
            }
        }
```

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

### Get Layer 3 from AtomicBitSet

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.AtomicBitSet.html?search=u32+-%3E+bool

Returns a usize where each bit indicates if any word in layer 2 has been set. This is part of the BitSetLike trait implementation.

```rust
fn layer3(&self) -> usize
```

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

### BitSet XOR (^) Operator

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/ops.rs.html

Demonstrates the XOR operation between two BitSets. Use this to get a new BitSet containing elements that are in either of the original BitSets, but not both.

```rust
{
            let exclusive = &bitset ^ &other;
            let collected = exclusive.iter().collect::<Vec<Index>>();
            assert_eq!(collected, vec![5, 15, 200, 50000]);

            let exclusive_sanity = bitset.clone() ^ other.clone();
            assert_eq!(collected, exclusive_sanity.iter().collect::<Vec<Index>>());
        }
```

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

### BitSet Methods

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html?search=

Details the methods available for creating, manipulating, and querying a BitSet.

```APIDOC
## Methods

### `new()` -> `BitSet`
Creates an empty `BitSet`.

### `with_capacity(max: u32) -> BitSet`
Creates an empty `BitSet`, preallocated for up to `max` indices.

### `add(&mut self, id: u32) -> bool`
Adds `id` to the `BitSet`. Returns `true` if the value was already in the set.

### `remove(&mut self, id: u32) -> bool`
Removes `id` from the set, returns `true` if the value was removed, and `false` if the value was not set to begin with.

### `contains(&self, id: u32) -> bool`
Returns `true` if `id` is in the set.

### `contains_set(&self, other: &BitSet) -> bool`
Returns `true` if all ids in `other` are contained in this set.

### `clear(&mut self)`
Completely wipes out the bit set.

### `layer0_as_slice(&self) -> &[usize]`
Returns the bottom layer of the bitset as a slice. Each bit in this slice refers to a single `Index`. The slice’s length will be at least the length needed to reflect all the `1`s in the bitset, but is not otherwise guaranteed. Consider it to be an implementation detail.

### `layer1_as_slice(&self) -> &[usize]`
Returns the second layer of the bitset as a slice. Each bit in this slice summarizes a corresponding `usize` from `layer0`. `BitSet::LAYER1_GRANULARITY` reflects how many indexes are summarized per layer 1 bit. The slice’s length is not guaranteed, except that it will be at least the length needed to reflect all the `1`s in the bitset.

### `layer2_as_slice(&self) -> &[usize]`
Returns the third layer of the bitset as a slice. Each bit in this slice summarizes a corresponding `usize` from `layer1`. The slice’s length is not guaranteed, except that it will be at least the length needed to reflect all the `1`s in the bitset.
```

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

### BitSet Intersection (&) Operator

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/ops.rs.html

Demonstrates the intersection operation between two BitSets. Use this to get a new BitSet containing only elements present in both original BitSets.

```rust
{
            let same = &bitset & &other;
            let collected = same.iter().collect::<Vec<Index>>();
            assert_eq!(collected, vec![1, 3, 50001]);

            let same_sanity = bitset.clone() & other.clone();
            assert_eq!(collected, same_sanity.iter().collect::<Vec<Index>>());
        }
```

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

### into

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html

Converts the BitSet into another type that can be created from it.

```APIDOC
## fn into(self) -> U

### Description
Calls `U::from(self)`.

### Method
`into`

### Returns
The converted value.
```

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

### BitSet Union (|) Operator

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/ops.rs.html

Demonstrates the union operation between two BitSets. Use this to get a new BitSet containing all elements from either of the original BitSets.

```rust
{
            let either = &bitset | &other;
            let collected = either.iter().collect::<Vec<Index>>();
            assert_eq!(collected, vec![1, 3, 5, 15, 200, 50000, 50001]);

            let either_sanity = bitset.clone() | other.clone();
            assert_eq!(collected, either_sanity.iter().collect::<Vec<Index>>());
        }
```

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

### get_from_layer Method - BitSetLike Trait

Source: https://docs.rs/hibitset/0.6.4/hibitset/trait.BitSetLike.html

Gets the usize corresponding to a given layer and index. The layer must be in the range [0, 3]. This is a provided method.

```rust
fn get_from_layer(&self, layer: usize, idx: usize) -> usize { ... }
```

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

### Test BitSet Sequential Iteration

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=

Demonstrates iterating through a BitSet after adding a large number of elements, verifying that each element is visited in order.

```rust
    #[test]
    fn iter() {
        let mut c = BitSet::new();
        for i in 0..100_000 {
            c.add(i);
        }

        let mut count = 0;
        for (idx, i) in c.iter().enumerate() {
            count += 1;
            assert_eq!(idx, i as usize);
        }
        assert_eq!(count, 100_000);
    }
```

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

### Dereference Pointer to Get Reference

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitParIter.html?search=

Unsafe method to dereference a raw pointer to obtain a reference to the data. Requires careful lifetime and validity management.

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

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

### AtomicBitSet Default Initialization

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/atomic.rs.html?search=

Provides the default initialization for an AtomicBitSet, setting up its internal atomic layers.

```rust
impl Default for AtomicBitSet {
    fn default() -> Self {
        AtomicBitSet {
            layer3: Default::default(),
            layer2: repeat(0)
                .map(|_| AtomicUsize::new(0))
                .take(1 << BITS)
                .collect(),
            layer1: repeat(0)
                .map(|_| AtomicBlock::new())
                .take(1 << (2 * BITS))
                .collect(),
        }
    }
}
```

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

### DrainBitIter::new

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/iter/drain.rs.html?search=

Creates a new DrainBitIter. This is typically not called directly; users should use the `.drain()` method on a bit set instead.

```APIDOC
## DrainBitIter::new

### Description
Creates a new `DrainBitIter`. This function is intended for internal use; users should generally call the `.drain()` method on a `DrainableBitSet` to obtain an iterator that removes elements as it yields them.

### Signature
```rust
pub fn new(set: &'a mut T, masks: [usize; LAYERS], prefix: [u32; LAYERS - 1]) -> Self
```

### Parameters
* `set` (*&'a mut T*): A mutable reference to the `DrainableBitSet` to iterate over and drain.
* `masks` (*[usize; LAYERS]*): Internal masks used for iteration.
* `prefix` (*[u32; LAYERS - 1]*): Internal prefix used for iteration.

### Returns
* `Self` (DrainBitIter<'a, T>): A new `DrainBitIter` instance.
```

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

### take

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitIter.html?search=u32+-%3E+bool

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.

### Method
`take`

### Parameters
#### Query Parameters
- **n** (usize) - Required - The maximum number of elements to yield.
```

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

### from

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html

Creates a BitSet from a value of the same type.

```APIDOC
## fn from(t: T) -> T

### Description
Returns the argument unchanged.

### Method
`from`

### Parameters
#### Path Parameters
- **t** (T) - Required - The value to convert.
```

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

### BitIter Clear Method

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/iter/mod.rs.html

Clears the remaining bits in the BitSet starting from the next inner layer. This method is specific to `BitIter` instances borrowed mutably from a `BitSet`.

```rust
pub(crate) fn clear(&mut self) {
    use self::State::Continue;
    while let Some(level) = (1..LAYERS).find(|&level| self.handle_level(level) == Continue) {
        let lower = level - 1;
        let idx = (self.prefix[lower] >> BITS) as usize;
        *self.set.layer_mut(lower, idx) = 0;
        if level == LAYERS - 1 {
            self.set.layer3 &= !((2 << idx) - 1);
        }
    }
}
```

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

### Get the bottom layer (layer0) as a slice

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=

Returns the bottom layer of the bitset as a slice. Each bit in this slice corresponds to a single `Index`. The slice's length is implementation-dependent.

```rust
    pub fn layer0_as_slice(&self) -> &[usize] {
        self.layer0.as_slice()
    }
```

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

### BitIter::new

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitIter.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new BitIter. This function is typically not called directly; users should use the `.iter()` method on a bit set instead.

```APIDOC
## BitIter::new

### Description
Creates a new `BitIter`.

### Method
`pub fn new(set: T, masks: [usize; 4], prefix: [u32; 3]) -> Self`

### Parameters
* `set` (T) - The bit set-like structure to iterate over.
* `masks` ([usize; 4]) - Internal masks used for iteration.
* `prefix` ([u32; 3]) - Internal prefix used for iteration.

### Note
This function is usually not called directly but through the `.iter()` method on a bit set.
```

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

### Basic Vec Operations and Clearing

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/atomic.rs.html?search=std%3A%3Avec

Demonstrates adding elements to a vector, checking its size, and clearing it. This pattern is repeated with different ranges and multipliers to show scalability.

```rust
            set.add(i * 1_000);
        }

        assert_eq!((&set).iter().count(), 1_000);
        set.clear();
        assert_eq!((&set).iter().count(), 0);

        for i in 0..100 {
            set.add(i * 10_000);
        }

        assert_eq!((&set).iter().count(), 100);
        set.clear();
        assert_eq!((&set).iter().count(), 0);

        for i in 0..10 {
            set.add(i * 10_000);
        }

        assert_eq!((&set).iter().count(), 10);
        set.clear();
        assert_eq!((&set).iter().count(), 0);
    }
}
```

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

### Parallel Iteration with Layer Splitting

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/iter/parallel.rs.html?search=

Demonstrates how to configure the number of layers to split when performing parallel iteration. The `layers_split` method allows tuning the work distribution for parallel processing.

```Rust
use rayon::iter::ParallelIterator;
use hibitset::{BitSet, BitSetLike};

fn main() {
    let mut bitset = BitSet::new();
    bitset.par_iter()
        .layers_split(2)
        .count();
}
```

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

### Get the granularity of layer 1 bits

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=

Provides the number of `Index`es described by a single layer 1 bit. This is intended for use with `BitSet::layer1_as_slice()` and is equal to `BITS_PER_USIZE`.

```rust
    pub const LAYER1_GRANULARITY: usize = BitSet::BITS_PER_USIZE;
```

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

### Accessing Layer 0 Slice

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html

Demonstrates how to add an index to a BitSet and then verify its presence in the layer0_as_slice. The index is mapped to its corresponding bit within the slice.

```rust
use hibitset::BitSet;

let index: u32 = 12345;

let mut bitset = BitSet::new();
bitset.add(index);

// layer 0 is 1:1 with Indexes, so we expect that bit in the slice to be set
let slice = bitset.layer0_as_slice();
let bit_index = index as usize;

// map that bit index to a usize in the slice and a bit within that usize
let slice_index = bit_index / BitSet::BITS_PER_USIZE;
let bit_at_index = bit_index % BitSet::BITS_PER_USIZE;

assert_eq!(slice[slice_index], 1 << bit_at_index);
```

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

### BitSetLike Trait: Get from Layer

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=std%3A%3Avec

Provides a generic method to retrieve a `usize` value from a specific layer (0-3) of a `BitSetLike` type. This is a core method for accessing the hierarchical data structure.

```rust
fn get_from_layer(&self, layer: usize, idx: usize) -> usize {
        match layer {
            0 => self.layer0(idx),
            1 => self.layer1(idx),
            2 => self.layer2(idx),
            3 => self.layer3(),
            _ => panic!("Invalid layer: {}", layer),
        }
    }
```

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

### BitSet Set Operations (Union, Intersection, XOR)

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/ops.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates the use of bitwise operators for union (|), intersection (&), and XOR (^) on BitSets. Includes sanity checks using clone and direct operator application.

```rust
        let mut bitset = BitSet::new();
        bitset.add(1);
        bitset.add(3);
        bitset.add(5);
        bitset.add(15);
        bitset.add(200);
        bitset.add(50001);

        let mut other = BitSet::new();
        other.add(1);
        other.add(3);
        other.add(50000);
        other.add(50001);

        {
            let not = &bitset & !&bitset;
            assert_eq!(not.iter().count(), 0);
        }

        {
            let either = &bitset | &other;
            let collected = either.iter().collect::<Vec<Index>>();
            assert_eq!(collected, vec![1, 3, 5, 15, 200, 50000, 50001]);

            let either_sanity = bitset.clone() | other.clone();
            assert_eq!(collected, either_sanity.iter().collect::<Vec<Index>>());
        }

        {
            let same = &bitset & &other;
            let collected = same.iter().collect::<Vec<Index>>();
            assert_eq!(collected, vec![1, 3, 50001]);

            let same_sanity = bitset.clone() & other.clone();
            assert_eq!(collected, same_sanity.iter().collect::<Vec<Index>>());
        }

        {
            let exclusive = &bitset ^ &other;
            let collected = exclusive.iter().collect::<Vec<Index>>();
            assert_eq!(collected, vec![5, 15, 200, 50000]);

            let exclusive_sanity = bitset.clone() ^ other.clone();
            assert_eq!(collected, exclusive_sanity.iter().collect::<Vec<Index>>());
        }
```

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

### BitSetLike: Get from Layer

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

A generic method to retrieve a `usize` value from a specific layer of a `BitSetLike` type. It supports layers 0 through 3, providing a unified way to access hierarchical bitset data.

```rust
fn get_from_layer(&self, layer: usize, idx: usize) -> usize {
    match layer {
        0 => self.layer0(idx),
        1 => self.layer1(idx),
        2 => self.layer2(idx),
        3 => self.layer3(),
        _ => panic!("Invalid layer: {}", layer),
    }
}
```

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

### extend_one (with references, experimental)

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.AtomicBitSet.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Extends the AtomicBitSet with exactly one element. This is a nightly-only experimental API.

```APIDOC
## fn extend_one(&mut self, item: A)

### Description
Extends a collection with exactly one element.

### Method
`extend_one`

### Parameters
#### Path Parameters
- **item** (A) - The element to add to the bit set.
```

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

### Cloning and Debugging

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSetOr.html?search=

BitSetOr supports cloning and debugging.

```APIDOC
## Trait Implementations for BitSetOr

### `impl<A: Clone + BitSetLike, B: Clone + BitSetLike> Clone for BitSetOr<A, B>`
- `clone(&self) -> BitSetOr<A, B>`: Returns a duplicate of the value.
- `clone_from(&mut self, source: &Self)`: Performs copy-assignment from `source`.

### `impl<A: Debug + BitSetLike, B: Debug + BitSetLike> Debug for BitSetOr<A, B>`
- `fmt(&self, f: &mut Formatter<'_>) -> Result`: Formats the value using the given formatter.
```

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

### Accessing Mutable Layer Data

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=

Provides a way to get a mutable reference to a specific `usize` within one of the `BitSet`'s layers based on the layer number and index. This is an internal helper function.

```rust
fn layer_mut(&mut self, level: usize, idx: usize) -> &mut usize {
    match level {
        0 => { // This is an incomplete snippet, likely intended to return a mutable reference to self.layer0[idx] or similar.
```

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

### from

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitIter.html?search=std%3A%3Avec

Creates a new instance of a type from another instance of the same type. This is typically used for identity conversions.

```APIDOC
## from

### Description
Returns the argument unchanged. This function is part of the `From<T>` trait implementation.

### Method
`from`

### Parameters
- `t` (T): The value to be converted.

### Response
- `T`: The argument `t` itself.
```

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

### Accessing Mutable Layer Elements

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides a way to get a mutable reference to a specific `usize` element within one of the `BitSet`'s layers based on the layer level and index. Currently only implements for layer 0.

```Rust
fn layer_mut(&mut self, level: usize, idx: usize) -> &mut usize {
    match level {
        0 => {

```

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

### Bitwise Operations

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSetOr.html

Demonstrates the bitwise AND, OR, and XOR operations supported by BitSetOr.

```APIDOC
### impl BitAnd<T> for BitSetOr<A, B>

Performs the `&` operation, returning a `BitSetAnd`.

### impl BitOr<T> for BitSetOr<A, B>

Performs the `|` operation, returning a `BitSetOr`.

### impl BitXor<T> for BitSetOr<A, B>

Performs the `^` operation, returning a `BitSetXor`.
```

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

### Consuming BitProducer with a Folder

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/iter/parallel.rs.html?search=

Demonstrates how to consume a `BitProducer` using a `Folder` trait implementation. This method is designed for efficient iteration and processing of the producer's items in parallel.

```rust
fn fold_with<F>(self, folder: F) -> F
    where
        F: Folder<Self::Item>,
    {
        folder.consume_iter(self.0)
    }
```

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

### clone_to_uninit

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitIter.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Performs copy-assignment from self to a destination pointer. This is an experimental, nightly-only API.

```APIDOC
## clone_to_uninit

### Description
Performs copy-assignment from `self` to `dest`.

### Method
`clone_to_uninit`

### Parameters
* `dest` (*mut u8) - A mutable pointer to the destination memory location.

### Returns
None
```

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

### CloneToUninit Trait (Nightly/Experimental)

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitIter.html?search=

Allows cloning data to an uninitialized memory location. This is an experimental API and requires a nightly Rust toolchain.

```APIDOC
## unsafe fn clone_to_uninit(&self, dest: *mut u8)

### Description
Performs copy-assignment from `self` to `dest`. This is a nightly-only experimental API.

### Method
`clone_to_uninit`

### Parameters
- `dest` (*mut u8): A mutable pointer to the destination memory location.
```

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

### BitIter::next Method

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/iter/mod.rs.html?search=u32+-%3E+bool

Implements the core iteration logic for BitIter, returning the next set bit as an Index or None if no more bits are set.

```rust
fn next(&mut self) -> Option<Self::Item> {
    use self::State::*;
    'find: loop {
        for level in 0..LAYERS {
            match self.handle_level(level) {
                Value(v) => return Some(v),
                Continue => continue 'find,
                Empty => {} // Continue to the next level
            }
        }
        // There are no set bits left
        return None;
    }
}
```

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

### Creating a New BitSet

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides a constructor for creating an empty `BitSet` using the `Default` trait implementation.

```Rust
/// Creates an empty `BitSet`.
pub fn new() -> BitSet {
    Default::default()
}
```

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

### BitIter Constructor

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/iter/mod.rs.html

Provides a constructor for `BitIter`. This is typically not called directly but rather through the `.iter()` method on a `BitSetLike` type.

```rust
pub fn new(set: T, masks: [usize; LAYERS], prefix: [u32; LAYERS - 1]) -> Self {
    BitIter {
        set: set,
        masks: masks,
        prefix: prefix,
    }
}
```

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

### BitSet Set Operations (AND, OR, XOR)

Source: https://docs.rs/hibitset/0.6.4/src/hibitset/ops.rs.html?search=std%3A%3Avec

Illustrates the use of bitwise AND (&), OR (|), and XOR (^) operators for BitSets. The NOT operation is also shown.

```rust
let mut bitset = BitSet::new();
bitset.add(1);
bitset.add(3);
bitset.add(5);
bitset.add(15);
bitset.add(200);
bitset.add(50001);

let mut other = BitSet::new();
other.add(1);
other.add(3);
other.add(50000);
other.add(50001);

{
    let not = &bitset & !&bitset;
    assert_eq!(not.iter().count(), 0);
}

{
    let either = &bitset | &other;
    let collected = either.iter().collect::<Vec<Index>>();
    assert_eq!(collected, vec![1, 3, 5, 15, 200, 50000, 50001]);

    let either_sanity = bitset.clone() | other.clone();
    assert_eq!(collected, either_sanity.iter().collect::<Vec<Index>>());
}

{
    let same = &bitset & &other;
    let collected = same.iter().collect::<Vec<Index>>();
    assert_eq!(collected, vec![1, 3, 50001]);

    let same_sanity = bitset.clone() & other.clone();
    assert_eq!(collected, same_sanity.iter().collect::<Vec<Index>>());
}

{
    let exclusive = &bitset ^ &other;
    let collected = exclusive.iter().collect::<Vec<Index>>();
    assert_eq!(collected, vec![5, 15, 200, 50000]);

    let exclusive_sanity = bitset.clone() ^ other.clone();
    assert_eq!(collected, exclusive_sanity.iter().collect::<Vec<Index>>());
}
```

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

### Initialize Pointer with Initializer

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitParIter.html?search=

Unsafe method to initialize memory at a given pointer with an initializer. Requires careful handling of memory.

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

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

### AtomicBitSet Methods

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.AtomicBitSet.html

This section details the public methods available for the AtomicBitSet struct, including creation, adding elements, checking for containment, and clearing the set.

```APIDOC
## new()

### Description
Creates an empty `AtomicBitSet`.

### Method
`new()`

### Returns
An empty `AtomicBitSet` instance.
```

```APIDOC
## add_atomic(id: u32) -> bool

### Description
Adds `id` to the `AtomicBitSet` atomically. Returns `true` if the value was already in the set.
This method will panic if the `id` is out of range, as extending the set requires unique ownership which is not guaranteed in atomic operations.

### Method
`add_atomic(&self, id: u32) -> bool`

### Parameters
#### Path Parameters
- **id** (u32) - Required - The identifier to add to the set.

### Returns
`true` if the value was already in the set, `false` otherwise.
```

```APIDOC
## add(id: u32) -> bool

### Description
Adds `id` to the `AtomicBitSet`. Returns `true` if the value was already in the set.
This method requires mutable access to the `AtomicBitSet`.

### Method
`add(&mut self, id: u32) -> bool`

### Parameters
#### Path Parameters
- **id** (u32) - Required - The identifier to add to the set.

### Returns
`true` if the value was already in the set, `false` otherwise.
```

```APIDOC
## remove(id: u32) -> bool

### Description
Removes `id` from the set. Returns `true` if the value was removed, and `false` if the value was not set to begin with.
This method requires mutable access to the `AtomicBitSet`.

### Method
`remove(&mut self, id: u32) -> bool`

### Parameters
#### Path Parameters
- **id** (u32) - Required - The identifier to remove from the set.

### Returns
`true` if the value was removed, `false` otherwise.
```

```APIDOC
## contains(id: u32) -> bool

### Description
Returns `true` if `id` is present in the set.

### Method
`contains(&self, id: u32) -> bool`

### Parameters
#### Path Parameters
- **id** (u32) - Required - The identifier to check for.

### Returns
`true` if `id` is in the set, `false` otherwise.
```

```APIDOC
## clear()

### Description
Clears all bits in the set, making it empty.
This method requires mutable access to the `AtomicBitSet`.

### Method
`clear(&mut self)`
```

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

### Clone Implementation

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html?search=

Provides methods for creating a duplicate of a BitSet or copying its contents to another BitSet.

```APIDOC
## Clone Implementation

### Description
Provides methods for creating a duplicate of a BitSet or copying its contents to another BitSet.

### Methods
- `clone(&self) -> BitSet`: Returns a duplicate of the value.
- `clone_from(&mut self, source: &Self)`: Performs copy-assignment from `source`.
```

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

### AtomicBitSet::new

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.AtomicBitSet.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new, empty AtomicBitSet. This is the constructor for the struct.

```APIDOC
## AtomicBitSet::new

### Description
Creates an empty `AtomicBitSet`.

### Method
`new()`

### Returns
- `AtomicBitSet`: An empty AtomicBitSet instance.
```

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

### borrow

Source: https://docs.rs/hibitset/0.6.4/hibitset/struct.BitSet.html

Immutably borrows the BitSet.

```APIDOC
## fn borrow(&self) -> &T

### Description
Immutably borrows from an owned value.

### Method
`borrow`

### Returns
A reference to the borrowed value.
```
Tokens:
Raw