### IdHashMap setup

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

Initial setup for an IdHashMap example involving a complex key structure.

```rust
#[cfg(feature = "default-hasher")] {
use iddqd::{IdHashItem, id_hash_map, id_upcast};

#[derive(Debug)]
struct Artifact {

```

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

### Example: Creating a BiHashMap with bi_hash_map!

Source: https://docs.rs/iddqd/latest/iddqd/macro.bi_hash_map.html

Demonstrates creating a `BiHashMap` from a list of `User` items, including a custom hasher variant. The example defines a `User` struct implementing `BiHashItem` and uses `bi_upcast!`.

```rust
use iddqd::{BiHashItem, bi_hash_map, bi_upcast};

#[derive(Debug)]
struct User {
    id: u32,
    name: String,
}

impl BiHashItem for User {
    type K1<'a> = u32;
    type K2<'a> = &'a str;
    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        &self.name
    }
    bi_upcast!();
}

let map = bi_hash_map! {
    User { id: 1, name: "Alice".to_string() },
    User { id: 2, name: "Bob".to_string() },
};
assert_eq!(map.get1(&1).unwrap().name, "Alice");
assert_eq!(map.get2("Bob").unwrap().id, 2);

// With a custom hasher:
let map = bi_hash_map! {
    foldhash::quality::RandomState;
    User { id: 3, name: "Charlie".to_string() },
    User { id: 4, name: "Eve".to_string() },
};
assert_eq!(map.get1(&3).unwrap().name, "Charlie");
assert_eq!(map.get2("Eve").unwrap().id, 4);
```

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

### reserve() usage example

Source: https://docs.rs/iddqd/latest/src/iddqd/id_hash_map/imp.rs.html

Shows how to use the reserve() method to pre-allocate capacity for at least 100 additional elements. The example asserts that the capacity is at least 100 after calling reserve.

```Rust
# #[cfg(feature = "default-hasher")] {
use iddqd::{IdHashItem, IdHashMap, id_upcast};

#[derive(Debug, PartialEq, Eq, Hash)]
struct Item {
    id: String,
    value: u32,
}

impl IdHashItem for Item {
    type Key<'a> = &'a str;
    fn key(&self) -> Self::Key<'_> {
        &self.id
    }
    id_upcast!();
}

let mut map: IdHashMap<Item> = IdHashMap::new();
map.reserve(100);
assert!(map.capacity() >= 100);
# }
```

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

### Creating a TriHashMap with tri_hash_map

Source: https://docs.rs/iddqd/latest/iddqd/macro.tri_hash_map.html

Example demonstrating how to implement TriHashItem for a struct and initialize a TriHashMap using the macro, including an example with a custom hasher.

```rust
use iddqd::{TriHashItem, tri_hash_map, tri_upcast};

#[derive(Debug)]
struct Person {
    id: u32,
    name: String,
    email: String,
}

impl TriHashItem for Person {
    type K1<'a> = u32;
    type K2<'a> = &'a str;
    type K3<'a> = &'a str;
    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        &self.name
    }
    fn key3(&self) -> Self::K3<'_> {
        &self.email
    }
    tri_upcast!();
}

let map = tri_hash_map! {
    Person { id: 1, name: "Alice".to_string(), email: "alice@example.com".to_string() },
    Person { id: 2, name: "Bob".to_string(), email: "bob@example.com".to_string() },
};
assert_eq!(map.get1(&1).unwrap().name, "Alice");
assert_eq!(map.get2("Bob").unwrap().id, 2);
assert_eq!(map.get3("alice@example.com").unwrap().name, "Alice");

// With a custom hasher:
let map = tri_hash_map! {
    foldhash::quality::RandomState;
    Person { id: 3, name: "Charlie".to_string(), email: "charlie@example.com".to_string() },
    Person { id: 4, name: "Eve".to_string(), email: "eve@example.com".to_string() },
};
assert_eq!(map.get1(&3).unwrap().name, "Charlie");
assert_eq!(map.get2("Eve").unwrap().id, 4);
```

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

### try_reserve() usage example

Source: https://docs.rs/iddqd/latest/src/iddqd/id_hash_map/imp.rs.html

Demonstrates the try_reserve() method which attempts to reserve capacity for additional elements. The example is incomplete in the source, showing only the setup with the Item type and map creation.

```Rust
# #[cfg(feature = "default-hasher")] {
use iddqd::{IdHashItem, IdHashMap, id_upcast};

#[derive(Debug, PartialEq, Eq, Hash)]
struct Item {
    id: String,
    value: u32,
}

impl IdHashItem for Item {
    type Key<'a> = &'a str;
    fn key(&self) -> Self::Key<'_> {
        &self.id
    }
    id_upcast!();
}
```

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

### prop_strategy_with_hasher_and_allocator - custom allocator example

Source: https://docs.rs/iddqd/latest/src/iddqd/bi_hash_map/proptest_impls.rs.html

Shows how to create a `BiHashMap` strategy with a custom hasher and allocator using `prop_strategy_with_hasher_and_allocator`. Requires the `allocator-api2` feature. The example uses `Global` from `allocator_api2` as the allocator.

```rust
/// Creates a strategy to generate [`BiHashMap`]s with a custom hasher and
/// allocator.
///
/// # Examples
///
/// ```
/// # #[cfg(feature = "allocator-api2")] {
/// use allocator_api2::alloc::Global;
/// use iddqd::{BiHashItem, BiHashMap, bi_hash_map, bi_upcast};
/// use proptest::{
///     arbitrary::any, strategy::Strategy, test_runner::TestRunner,
/// };
/// use std::collections::hash_map::RandomState;
///
/// #[derive(Debug, Clone, PartialEq, Eq)]
/// struct Person {
///     id: u32,
///     email: String,
/// }
///
/// impl BiHashItem for Person {
///     type K1<'a> = u32;
///     type K2<'a> = &'a str;
///
///     fn key1(&self) -> Self::K1<'_> {
///         self.id
///     }
///     fn key2(&self) -> Self::K2<'_> {
///         &self.email
///     }
///     bi_upcast!();
/// }
///
/// // Create a strategy with a custom hasher and allocator.
/// let hasher = RandomState::new();
/// let strategy = bi_hash_map::prop_strategy_with_hasher_and_allocator(
///     (any::<u32>(), any::<String>())
///         .prop_map(|(id, email)| Person { id, email }),
///     0..=3,
///     hasher,
///     Global,
/// );
///
/// // The strategy can be used in proptest contexts.
/// let mut runner = TestRunner::default();
/// let _tree = strategy.new_tree(&mut runner).unwrap();
/// # }
/// ```
pub fn prop_strategy_with_hasher_and_allocator<T: Strategy, S, A>(
    element: T,
    size: impl Into<SizeRange>,
    hasher: S,
    allocator: A,
) -> BiHashMapStrategy<T, S, A>
where
    A: Allocator,
{
    let size = size.into();
    BiHashMapStrategy {
        inner: proptest::collection::vec(element, size),
        hasher,
        allocator,
    }
}
```

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

### IdHashMap::get example

Source: https://docs.rs/iddqd/latest/src/iddqd/id_hash_map/imp.rs.html

Example for the `get` method of `IdHashMap`. It asserts that the value for key "foo" is 42 and that "bar" is not present.

```rust
/// assert_eq!(map.get("foo").unwrap().value, 42);
/// assert!(map.get("bar").is_none());
/// # }
/// ```
```

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

### prop_strategy_with_hasher - custom hasher example

Source: https://docs.rs/iddqd/latest/src/iddqd/bi_hash_map/proptest_impls.rs.html

Shows how to create a `BiHashMap` strategy with a custom hasher using `prop_strategy_with_hasher`. The example uses `RandomState` as the hasher and a size range of 0..=3.

```rust
/// Creates a strategy to generate [`BiHashMap`]s with a custom hasher.
///
/// # Examples
///
/// ```
/// use iddqd::{BiHashItem, BiHashMap, bi_hash_map, bi_upcast};
/// use proptest::{
///     arbitrary::any, strategy::Strategy, test_runner::TestRunner,
/// };
/// use std::collections::hash_map::RandomState;
///
/// #[derive(Debug, Clone, PartialEq, Eq)]
/// struct Person {
///     id: u32,
///     email: String,
/// }
///
/// impl BiHashItem for Person {
///     type K1<'a> = u32;
///     type K2<'a> = &'a str;
///
///     fn key1(&self) -> Self::K1<'_> {
///         self.id
///     }
///     fn key2(&self) -> Self::K2<'_> {
///         &self.email
///     }
///     bi_upcast!();
/// }
///
/// // Create a strategy with a custom hasher.
/// let hasher = RandomState::new();
/// let strategy = bi_hash_map::prop_strategy_with_hasher(
///     (any::<u32>(), any::<String>())
///         .prop_map(|(id, email)| Person { id, email }),
///     0..=3,
///     hasher,
/// );
///
/// // The strategy can be used in proptest contexts.
/// let mut runner = TestRunner::default();
/// let _tree = strategy.new_tree(&mut runner).unwrap();
/// ```
pub fn prop_strategy_with_hasher<T: Strategy, S>(
    element: T,
    size: impl Into<SizeRange>,
    hasher: S,
) -> BiHashMapStrategy<T, S, Global> {
    let size = size.into();
    BiHashMapStrategy {
        inner: proptest::collection::vec(element, size),
        hasher,
        allocator: crate::support::alloc::global_alloc(),
    }
}
```

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

### IdOrdMap::capacity example

Source: https://docs.rs/iddqd/latest/src/iddqd/id_ord_map/imp.rs.html

Example showing how to check the allocated capacity of an IdOrdMap created with with_capacity.

```rust
use iddqd::{IdOrdItem, IdOrdMap, id_upcast};

#[derive(Debug, PartialEq, Eq, PartialOrd, Ord)]
struct Item {
    id: String,
    value: u32,
}

impl IdOrdItem for Item {
    type Key<'a> = &'a str;

    fn key(&self) -> Self::Key<'_> {
        &self.id
    }

    id_upcast!();
}

let map: IdOrdMap<Item> = IdOrdMap::with_capacity(10);
```

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

### BiHashMap usage example

Source: https://docs.rs/iddqd/latest/iddqd/bi_hash_map/struct.BiHashMap.html

Example showing how to define a struct with two keys, implement BiHashItem, insert items with insert_unique, and look them up using get1 and get2.

```rust
use iddqd::{BiHashItem, BiHashMap, bi_upcast};

// Define a struct with two keys and a value.
#[derive(Debug, PartialEq, Eq)]
struct MyItem {
    id: u32,
    name: &'static str,
    value: i32,
}

// Implement BiHashItem for the struct.
impl BiHashItem for MyItem {
    type K1<'a> = u32;
    type K2<'a> = &'a str;

    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        self.name
    }

    bi_upcast!();
}

// Create a new BiHashMap and insert items.
let mut map = BiHashMap::new();
map.insert_unique(MyItem { id: 1, name: "foo", value: 42 }).unwrap();
map.insert_unique(MyItem { id: 2, name: "bar", value: 99 }).unwrap();

// Look up by the first key.
assert_eq!(map.get1(&1).unwrap().value, 42);
assert_eq!(map.get1(&2).unwrap().value, 99);
assert!(map.get1(&3).is_none());

// Look up by the second key.
assert_eq!(map.get2(&"foo").unwrap().value, 42);
assert_eq!(map.get2(&"bar").unwrap().value, 99);
assert!(map.get2(&"baz").is_none());
```

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

### Example: Using prop_strategy with proptest

Source: https://docs.rs/iddqd/latest/iddqd/bi_hash_map/fn.prop_strategy.html

A complete example showing how to define a custom `BiHashItem` type and create a strategy using `prop_strategy` with a tuple mapped to the type. The strategy is then used to generate a tree in a proptest runner.

```rust
use iddqd::{BiHashItem, BiHashMap, bi_hash_map, bi_upcast};
use proptest::{
    arbitrary::any, strategy::Strategy, test_runner::TestRunner,
};

#[derive(Debug, Clone, PartialEq, Eq)]
struct Person {
    id: u32,
    email: String,
}

impl BiHashItem for Person {
    type K1<'a> = u32;
    type K2<'a> = &'a str;

    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        &self.email
    }
    bi_upcast!();
}

// Create a strategy using a tuple and mapping it to Person.
let strategy = bi_hash_map::prop_strategy(
    (any::<u32>(), any::<String>())
        .prop_map(|(id, email)| Person { id, email }),
    0..=5,
);

// The strategy can be used in proptest contexts.
let mut runner = TestRunner::default();
let _tree = strategy.new_tree(&mut runner).unwrap();
```

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

### Implementing BiHashItem for a struct

Source: https://docs.rs/iddqd/latest/iddqd/bi_hash_map/trait.BiHashItem.html

Example showing how to define a struct with two keys, implement BiHashItem, and use a BiHashMap with insert_unique. The example uses the bi_upcast! macro to implement the upcast methods.

```rust
use iddqd::{BiHashItem, BiHashMap, bi_upcast};

// Define a struct with two keys.
#[derive(Debug, PartialEq, Eq, Hash)]
struct MyPair {
    id: u32,
    name: String,
}

// Implement BiHashItem for the struct.
impl BiHashItem for MyPair {
    type K1<'a> = u32;
    type K2<'a> = &'a str;

    fn key1(&self) -> Self::K1<'_> {
        self.id
    }

    fn key2(&self) -> Self::K2<'_> {
        &self.name
    }

    bi_upcast!();
}

// Create a BiHashMap and insert items.
let mut map = BiHashMap::new();
map.insert_unique(MyPair { id: 1, name: "Alice".to_string() }).unwrap();
map.insert_unique(MyPair { id: 2, name: "Bob".to_string() }).unwrap();
```

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

### Example: generating TriHashMap with prop_strategy

Source: https://docs.rs/iddqd/latest/iddqd/tri_hash_map/fn.prop_strategy.html

Example usage of prop_strategy. It defines a Person type implementing TriHashItem, creates a strategy from a tuple of arbitrary values mapped to Person, and generates a tree with a default TestRunner. The size range is 0..=5.

```rust
use iddqd::{TriHashItem, TriHashMap, tri_hash_map, tri_upcast};
use proptest::{
    arbitrary::any, strategy::Strategy, test_runner::TestRunner,
};

#[derive(Debug, Clone, PartialEq, Eq)]
struct Person {
    id: u32,
    email: String,
    name: String,
}

impl TriHashItem for Person {
    type K1<'a> = u32;
    type K2<'a> = &'a str;
    type K3<'a> = &'a str;

    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        &self.email
    }
    fn key3(&self) -> Self::K3<'_> {
        &self.name
    }
    tri_upcast!();
}

// Create a strategy using a tuple and mapping it to Person.
let strategy = tri_hash_map::prop_strategy(
    (any::<u32>(), any::<String>(), any::<String>())
        .prop_map(|(id, email, name)| Person { id, email, name }),
    0..=5,
);

// The strategy can be used in proptest contexts.
let mut runner = TestRunner::default();
let _tree = strategy.new_tree(&mut runner).unwrap();
```

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

### Check for key2 existence

Source: https://docs.rs/iddqd/latest/src/iddqd/bi_hash_map/imp.rs.html

Demonstrates the setup for checking existence by key2.

```rust
# #[cfg(feature = "default-hasher")] {
    use iddqd::{BiHashItem, BiHashMap, bi_upcast};

    #[derive(Debug, PartialEq, Eq)]
    struct Item {
        id: u32,
        name: String,
        value: i32,
    }

    impl BiHashItem for Item {
        type K1<'a> = u32;
        type K2<'a> = &'a str;

        fn key1(&self) -> Self::K1<'_> {
            self.id
        }
        fn key2(&self) -> Self::K2<'_> {
            &self.name
        }
```

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

### IdOrdMap::new example

Source: https://docs.rs/iddqd/latest/iddqd/id_ord_map/struct.IdOrdMap.html

Creates a new, empty IdOrdMap.

```rust
use iddqd::{IdOrdItem, IdOrdMap, id_upcast};

#[derive(Debug, PartialEq, Eq, PartialOrd, Ord)]
struct Item {
    id: String,
    value: u32,
}

impl IdOrdItem for Item {
    type Key<'a> = &'a str;

    fn key(&self) -> Self::Key<'_> {
        &self.id
    }

    id_upcast!();
}

let map: IdOrdMap<Item> = IdOrdMap::new();
assert!(map.is_empty());
assert_eq!(map.len(), 0);
```

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

### BiHashMap::with_capacity_and_hasher() example

Source: https://docs.rs/iddqd/latest/iddqd/bi_hash_map/struct.BiHashMap.html

Creates a new BiHashMap with a given capacity and custom hasher. The example uses RandomState and defines a custom Item type. It asserts the map's capacity is at least 10 and it is empty.

```rust
use iddqd::{BiHashItem, BiHashMap, bi_upcast};
use std::collections::hash_map::RandomState;

#[derive(Debug, PartialEq, Eq)]
struct Item {
    id: u32,
    name: String,
    value: i32,
}

impl BiHashItem for Item {
    type K1<'a> = u32;
    type K2<'a> = &'a str;

    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        &self.name
    }
    bi_upcast!();
}

let hasher = RandomState::new();
let map: BiHashMap<Item, _> =
    BiHashMap::with_capacity_and_hasher(10, hasher);
assert!(map.capacity() >= 10);
assert!(map.is_empty());
```

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

### BiHashMap::with_capacity() example

Source: https://docs.rs/iddqd/latest/iddqd/bi_hash_map/struct.BiHashMap.html

Creates a new BiHashMap with the given capacity using the default hasher. Requires the 'default-hasher' crate feature. The example defines a custom Item type and asserts the map's capacity is at least 10 and it is empty.

```rust
use iddqd::{BiHashItem, BiHashMap, bi_upcast};

#[derive(Debug, PartialEq, Eq)]
struct Item {
    id: u32,
    name: String,
    value: i32,
}

impl BiHashItem for Item {
    type K1<'a> = u32;
    type K2<'a> = &'a str;

    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        &self.name
    }
    bi_upcast!();
}

let map: BiHashMap<Item> = BiHashMap::with_capacity(10);
assert!(map.capacity() >= 10);
assert!(map.is_empty());
```

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

### Usage example with custom hasher and allocator

Source: https://docs.rs/iddqd/latest/iddqd/tri_hash_map/fn.prop_strategy_with_hasher_in.html

Shows how to import required modules, define a TriHashItem implementation, and create the strategy with allocator and proptest integration.

```rust
use allocator_api2::alloc::Global;
use iddqd::{TriHashItem, TriHashMap, tri_hash_map, tri_upcast};
use proptest::{
    arbitrary::any, strategy::Strategy, test_runner::TestRunner,
};
use std::collections::hash_map::RandomState;

#[derive(Debug, Clone, PartialEq, Eq)]
struct Person {
    id: u32,
    email: String,
    name: String,
}

impl TriHashItem for Person {
    type K1<'a> = u32;
    type K2<'a> = &'a str;
    type K3<'a> = &'a str;

    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        &self.email
    }
    fn key3(&self) -> Self::K3<'_> {
        &self.name
    }
    tri_upcast!();
}

// Create a strategy with custom hasher and allocator.
let hasher = RandomState::new();
let allocator = Global;
let strategy = tri_hash_map::prop_strategy_with_hasher_in(
    (any::<u32>(), any::<String>(), any::<String>())
        .prop_map(|(id, email, name)| Person { id, email, name }),
    1..=4,
    hasher,
    allocator,
);

// The strategy can be used in proptest contexts.
let mut runner = TestRunner::default();
let _tree = strategy.new_tree(&mut runner).unwrap();
```

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

### len() usage example

Source: https://docs.rs/iddqd/latest/src/iddqd/id_hash_map/imp.rs.html

Shows how to use the len() method to get the number of items in an IdHashMap. The example creates a map, inserts two items, and asserts the length is 2.

```Rust
# #[cfg(feature = "default-hasher")] {
use iddqd::{IdHashItem, IdHashMap, id_upcast};

#[derive(Debug, PartialEq, Eq, Hash)]
struct Item {
    id: String,
    value: u32,
}

impl IdHashItem for Item {
    type Key<'a> = &'a str;
    fn key(&self) -> Self::Key<'_> {
        &self.id
    }
    id_upcast!();
}

let mut map = IdHashMap::new();
assert_eq!(map.len(), 0);

map.insert_unique(Item { id: "foo".to_string(), value: 42 }).unwrap();
assert_eq!(map.len(), 1);

map.insert_unique(Item { id: "bar".to_string(), value: 20 }).unwrap();
assert_eq!(map.len(), 2);
# }
```

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

### Example: Creating a strategy with custom hasher and allocator

Source: https://docs.rs/iddqd/latest/iddqd/bi_hash_map/fn.prop_strategy_with_hasher_in.html

Shows how to use `prop_strategy_with_hasher_in` with a custom `BiHashItem` type, a `RandomState` hasher, and the `Global` allocator. The strategy is then used with a `TestRunner` to generate a tree.

```rust
use allocator_api2::alloc::Global;
use iddqd::{BiHashItem, BiHashMap, bi_hash_map, bi_upcast};
use proptest::{
    arbitrary::any, strategy::Strategy, test_runner::TestRunner,
};
use std::collections::hash_map::RandomState;

#[derive(Debug, Clone, PartialEq, Eq)]
struct Person {
    id: u32,
    email: String,
}

impl BiHashItem for Person {
    type K1<'a> = u32;
    type K2<'a> = &'a str;

    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        &self.email
    }
    bi_upcast!();
}

// Create a strategy with custom hasher and allocator.
let hasher = RandomState::new();
let allocator = Global;
let strategy = bi_hash_map::prop_strategy_with_hasher_in(
    (any::<u32>(), any::<String>())
        .prop_map(|(id, email)| Person { id, email }),
    1..=4,
    hasher,
    allocator,
);

// The strategy can be used in proptest contexts.
let mut runner = TestRunner::default();
let _tree = strategy.new_tree(&mut runner).unwrap();
```

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

### Example: Creating and using a prop_strategy for IdHashMap

Source: https://docs.rs/iddqd/latest/iddqd/id_hash_map/fn.prop_strategy.html

Shows how to define a custom `IdHashItem` type and create a strategy using a tuple and `prop_map`, then use it with a `TestRunner` to generate a tree.

```rust
use iddqd::{IdHashItem, IdHashMap, id_hash_map, id_upcast};
use proptest::{
    arbitrary::any, strategy::Strategy, test_runner::TestRunner,
};

#[derive(Debug, Clone, PartialEq, Eq)]
struct Person {
    id: u32,
    name: String,
}

impl IdHashItem for Person {
    type Key<'a> = u32;

    fn key(&self) -> Self::Key<'_> {
        self.id
    }
    id_upcast!();
}

// Create a strategy using a tuple and mapping it to Person.
let strategy = id_hash_map::prop_strategy(
    (any::<u32>(), any::<String>())
        .prop_map(|(id, name)| Person { id, name }),
    0..=5,
);

// The strategy can be used in proptest contexts.
let mut runner = TestRunner::default();
let _tree = strategy.new_tree(&mut runner).unwrap();
```

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

### Using len() to get item count

Source: https://docs.rs/iddqd/latest/iddqd/id_ord_map/struct.IdOrdMap.html

Shows how to use len() to get the number of items in an IdOrdMap. The example creates a map, inserts two items, and asserts the length is 2.

```rust
use iddqd::{IdOrdItem, IdOrdMap, id_upcast};

#[derive(Debug, PartialEq, Eq, PartialOrd, Ord)]
struct Item {
    id: String,
    value: u32,
}

impl IdOrdItem for Item {
    type Key<'a> = &'a str;

    fn key(&self) -> Self::Key<'_> {
        &self.id
    }

    id_upcast!();
}

let mut map = IdOrdMap::new();
assert_eq!(map.len(), 0);

map.insert_unique(Item { id: "foo".to_string(), value: 42 }).unwrap();
map.insert_unique(Item { id: "bar".to_string(), value: 99 }).unwrap();
assert_eq!(map.len(), 2);
```

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

### get2 example: get value by key2 in BiHashMap

Source: https://docs.rs/iddqd/latest/src/iddqd/bi_hash_map/imp.rs.html

Defines an Item struct with u32 key1 and &str key2, inserts two items, and retrieves values using get2 with 'foo' and 'bar'. Requires the default-hasher feature.

```rust
# #[cfg(feature = "default-hasher")] {
use iddqd::{BiHashItem, BiHashMap, bi_upcast};

#[derive(Debug, PartialEq, Eq)]
struct Item {
    id: u32,
    name: String,
    value: i32,
}

impl BiHashItem for Item {
    type K1<'a> = u32;
    type K2<'a> = &'a str;

    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        &self.name
    }
    bi_upcast!();
}

let mut map = BiHashMap::new();
map.insert_unique(Item { id: 1, name: "foo".to_string(), value: 42 })
    .unwrap();
map.insert_unique(Item { id: 2, name: "bar".to_string(), value: 99 })
    .unwrap();

assert_eq!(map.get2(&"foo").unwrap().value, 42);
assert_eq!(map.get2(&"bar").unwrap().value, 99);
assert!(map.get2(&"baz").is_none());
# }
```

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

### Initialize BiHashMap with bi_hash_map!

Source: https://docs.rs/iddqd/latest/src/iddqd/macros.rs.html

Demonstrates implementing BiHashItem and using the bi_hash_map! macro to create a map with default or custom hashers.

```rust
/// impl BiHashItem for User {
///     type K1<'a> = u32;
///     type K2<'a> = &'a str;
///     fn key1(&self) -> Self::K1<'_> {
///         self.id
///     }
///     fn key2(&self) -> Self::K2<'_> {
///         &self.name
///     }
///     bi_upcast!();
/// }
///
/// let map = bi_hash_map! {
///     User { id: 1, name: "Alice".to_string() },
///     User { id: 2, name: "Bob".to_string() },
/// };
/// assert_eq!(map.get1(&1).unwrap().name, "Alice");
/// assert_eq!(map.get2("Bob").unwrap().id, 2);
///
/// // With a custom hasher:
/// let map = bi_hash_map! {
///     foldhash::quality::RandomState;
///     User { id: 3, name: "Charlie".to_string() },
///     User { id: 4, name: "Eve".to_string() },
/// };
/// assert_eq!(map.get1(&3).unwrap().name, "Charlie");
/// assert_eq!(map.get2("Eve").unwrap().id, 4);
/// # }
```

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

### get

Source: https://docs.rs/iddqd/latest/iddqd/id_ord_map/struct.IdOrdMap.html

Gets a reference to the value associated with the given key.

```APIDOC
## get

### Description
Gets a reference to the value associated with the given key.

### Method
get

### Signature
pub fn get<'a, Q>(&'a self, key: &Q) -> Option<&'a T>
where Q: ?Sized + Comparable<T::Key<'a>>,

### Parameters
- key: &Q - The key to look up.

### Returns
- Option<&'a T> - A reference to the value if found, None otherwise.

### Example
```rust
use iddqd::{IdOrdItem, IdOrdMap, id_upcast};

#[derive(Debug, PartialEq, Eq, PartialOrd, Ord)]
struct Item {
    id: String,
    value: u32,
}

impl IdOrdItem for Item {
    type Key<'a> = &'a str;

    fn key(&self) -> Self::Key<'_> {
        &self.id
    }

    id_upcast!();
}

let mut map = IdOrdMap::new();
map.insert_unique(Item { id: "foo".to_string(), value: 42 }).unwrap();
assert_eq!(map.get("foo").unwrap().value, 42);
assert!(map.get("bar").is_none());
```
```

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

### IdHashMap::entry example

Source: https://docs.rs/iddqd/latest/src/iddqd/id_hash_map/imp.rs.html

Example for the `entry` method of `IdHashMap`. It uses the entry API to conditionally insert items and asserts the map length is 2.

```rust
/// # #[cfg(feature = "default-hasher")] {
/// use iddqd::{IdHashItem, IdHashMap, id_upcast};
///
/// #[derive(Debug, PartialEq, Eq, Hash)]
/// struct Item {
///     id: String,
///     value: u32,
/// }
///
/// impl IdHashItem for Item {
///     type Key<'a> = &'a str;
///     fn key(&self) -> Self::Key<'_> {
///         &self.id
///     }
///     id_upcast!();
/// }
///
/// let mut map = IdHashMap::new();
///
/// // Use entry API for conditional insertion
/// map.entry("foo").or_insert(Item { id: "foo".to_string(), value: 42 });
/// map.entry("bar").or_insert(Item { id: "bar".to_string(), value: 20 });
///
/// assert_eq!(map.len(), 2);
/// # }
/// ```
```

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

### BiHashMap::with_hasher() example

Source: https://docs.rs/iddqd/latest/iddqd/bi_hash_map/struct.BiHashMap.html

Creates a new BiHashMap with a custom hasher. The example uses RandomState and defines a custom Item type. It asserts the map is empty.

```rust
use iddqd::{BiHashItem, BiHashMap, bi_upcast};
use std::collections::hash_map::RandomState;

#[derive(Debug, PartialEq, Eq)]
struct Item {
    id: u32,
    name: String,
    value: i32,
}

impl BiHashItem for Item {
    type K1<'a> = u32;
    type K2<'a> = &'a str;

    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        &self.name
    }
    bi_upcast!();
}

let hasher = RandomState::new();
let map: BiHashMap<Item, RandomState> = BiHashMap::with_hasher(hasher);
assert!(map.is_empty());
```

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

### Example: Using prop_strategy with a custom type

Source: https://docs.rs/iddqd/latest/iddqd/id_ord_map/fn.prop_strategy.html

Shows how to create a strategy for `IdOrdMap` using a tuple mapped to a `Person` type, then use it with a `TestRunner`. Requires the `proptest` and `std` features.

```rust
use iddqd::{IdOrdItem, IdOrdMap, id_ord_map, id_upcast};
use proptest::{
    arbitrary::any, strategy::Strategy, test_runner::TestRunner,
};

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
struct Person {
    id: u32,
    name: String,
}

impl IdOrdItem for Person {
    type Key<'a> = u32;

    fn key(&self) -> Self::Key<'_> {
        self.id
    }
    id_upcast!();
}

// Create a strategy using a tuple and mapping it to Person.
let strategy = id_ord_map::prop_strategy(
    (any::<u32>(), any::<String>())
        .prop_map(|(id, name)| Person { id, name }),
    0..=5,
);

// The strategy can be used in proptest contexts.
let mut runner = TestRunner::default();
let _tree = strategy.new_tree(&mut runner).unwrap();
```

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

### clear() usage example

Source: https://docs.rs/iddqd/latest/src/iddqd/id_hash_map/imp.rs.html

Demonstrates the clear() method which removes all items from the map. The example inserts two items, clears the map, and asserts it is empty with length 0.

```Rust
# #[cfg(feature = "default-hasher")] {
use iddqd::{IdHashItem, IdHashMap, id_upcast};

#[derive(Debug, PartialEq, Eq, Hash)]
struct Item {
    id: String,
    value: u32,
}

impl IdHashItem for Item {
    type Key<'a> = &'a str;
    fn key(&self) -> Self::Key<'_> {
        &self.id
    }
    id_upcast!();
}

let mut map = IdHashMap::new();
map.insert_unique(Item { id: "foo".to_string(), value: 42 }).unwrap();
map.insert_unique(Item { id: "bar".to_string(), value: 20 }).unwrap();
assert_eq!(map.len(), 2);

map.clear();
assert!(map.is_empty());
assert_eq!(map.len(), 0);
# }
```

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

### Example usage of prop_strategy_with_hasher

Source: https://docs.rs/iddqd/latest/iddqd/id_hash_map/fn.prop_strategy_with_hasher.html

Demonstrates creating a strategy for a custom struct Person with a specific hasher and using it within a proptest TestRunner.

```rust
use iddqd::{IdHashItem, IdHashMap, id_hash_map, id_upcast};
use proptest::{
    arbitrary::any, strategy::Strategy, test_runner::TestRunner,
};
use std::collections::hash_map::RandomState;

#[derive(Debug, Clone, PartialEq, Eq)]
struct Person {
    id: u32,
    name: String,
}

impl IdHashItem for Person {
    type Key<'a> = u32;

    fn key(&self) -> Self::Key<'_> {
        self.id
    }
    id_upcast!();
}

// Create a strategy with a custom hasher.
let hasher = RandomState::new();
let strategy = id_hash_map::prop_strategy_with_hasher(
    (any::<u32>(), any::<String>())
        .prop_map(|(id, name)| Person { id, name }),
    0..=3,
    hasher,
);

// The strategy can be used in proptest contexts.
let mut runner = TestRunner::default();
let _tree = strategy.new_tree(&mut runner).unwrap();
```

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

### IdHashMap::get_mut example

Source: https://docs.rs/iddqd/latest/src/iddqd/id_hash_map/imp.rs.html

Example for the `get_mut` method of `IdHashMap`. It inserts an item, mutates its value via `get_mut`, and asserts the updated value and that a missing key returns `None`.

```rust
/// # #[cfg(feature = "default-hasher")] {
/// use iddqd::{IdHashItem, IdHashMap, id_upcast};
///
/// #[derive(Debug, PartialEq, Eq, Hash)]
/// struct Item {
///     id: String,
///     value: u32,
/// }
///
/// impl IdHashItem for Item {
///     type Key<'a> = &'a str;
///     fn key(&self) -> Self::Key<'_> {
///         &self.id
///     }
///     id_upcast!();
/// }
///
/// let mut map = IdHashMap::new();
/// map.insert_unique(Item { id: "foo".to_string(), value: 42 }).unwrap();
///
/// if let Some(mut item) = map.get_mut("foo") {
///     item.value = 100;
/// }
///
/// assert_eq!(map.get("foo").unwrap().value, 100);
/// assert!(map.get_mut("bar").is_none());
/// # }
/// ```
```

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

### Create a BiHashMap strategy with a custom hasher

Source: https://docs.rs/iddqd/latest/iddqd/bi_hash_map/fn.prop_strategy_with_hasher.html

Example demonstrating how to implement BiHashItem for a struct and use prop_strategy_with_hasher to generate it within a proptest context.

```rust
use iddqd::{BiHashItem, BiHashMap, bi_hash_map, bi_upcast};
use proptest::{
    arbitrary::any, strategy::Strategy, test_runner::TestRunner,
};
use std::collections::hash_map::RandomState;

#[derive(Debug, Clone, PartialEq, Eq)]
struct Person {
    id: u32,
    email: String,
}

impl BiHashItem for Person {
    type K1<'a> = u32;
    type K2<'a> = &'a str;

    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        &self.email
    }
    bi_upcast!();
}

// Create a strategy with a custom hasher.
let hasher = RandomState::new();
let strategy = bi_hash_map::prop_strategy_with_hasher(
    (any::<u32>(), any::<String>())
        .prop_map(|(id, email)| Person { id, email }),
    0..=3,
    hasher,
);

// The strategy can be used in proptest contexts.
let mut runner = TestRunner::default();
let _tree = strategy.new_tree(&mut runner).unwrap();
```

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

### IdHashMap::remove example

Source: https://docs.rs/iddqd/latest/src/iddqd/id_hash_map/imp.rs.html

Example for the `remove` method of `IdHashMap`. It removes an existing item, asserts the removed value and that the map is empty, and shows that removing a missing key returns `None`.

```rust
/// # #[cfg(feature = "default-hasher")] {
/// use iddqd::{IdHashItem, IdHashMap, id_upcast};
///
/// #[derive(Debug, PartialEq, Eq, Hash)]
/// struct Item {
///     id: String,
///     value: u32,
/// }
///
/// impl IdHashItem for Item {
///     type Key<'a> = &'a str;
///     fn key(&self) -> Self::Key<'_> {
///         &self.id
///     }
///     id_upcast!();
/// }
///
/// let mut map = IdHashMap::new();
/// map.insert_unique(Item { id: "foo".to_string(), value: 42 }).unwrap();
///
/// let removed = map.remove("foo");
/// assert_eq!(removed.unwrap().value, 42);
/// assert!(map.is_empty());
///
/// // Removing non-existent key returns None
/// assert!(map.remove("bar").is_none());
/// # }
/// ```
```

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

### Example: computing a diff between two IdOrdMaps

Source: https://docs.rs/iddqd/latest/iddqd/id_ord_map/struct.Diff.html

Shows how to create two IdOrdMaps, compute their diff, and assert on the added, removed, and modified entries. Requires the 'daft' and 'std' features.

```rust
use daft::Diffable;
use iddqd::{IdOrdItem, IdOrdMap, id_upcast};

#[derive(Eq, PartialEq, PartialOrd, Ord)]
struct Item {
    id: String,
    value: u32,
}

impl IdOrdItem for Item {
    type Key<'a> = &'a str;
    fn key(&self) -> Self::Key<'_> {
        &self.id
    }
    id_upcast!();
}

// Create two IdOrdMaps with overlapping items.
let mut map1 = IdOrdMap::new();
map1.insert_unique(Item { id: "a".to_string(), value: 1 });
map1.insert_unique(Item { id: "b".to_string(), value: 2 });

let mut map2 = IdOrdMap::new();
map2.insert_unique(Item { id: "b".to_string(), value: 3 });
map2.insert_unique(Item { id: "c".to_string(), value: 4 });

// Compute the diff between the two maps.
let diff = map1.diff(&map2);

// "a" is removed.
assert!(diff.removed.contains_key("a"));
// "b" is modified (value changed from 2 to 3).
assert!(diff.is_modified("b"));
// "c" is added.
assert!(diff.added.contains_key("c"));
```

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

### Using shrink_to_fit() to reduce capacity

Source: https://docs.rs/iddqd/latest/iddqd/id_ord_map/struct.IdOrdMap.html

Shows how to use shrink_to_fit() to shrink capacity as much as possible. The example creates a map with capacity 100, inserts two items, and after shrink_to_fit asserts capacity is at least 2.

```rust
use iddqd::{IdOrdItem, IdOrdMap, id_upcast};

#[derive(Debug, PartialEq, Eq, PartialOrd, Ord)]
struct Item {
    id: String,
    value: u32,
}

impl IdOrdItem for Item {
    type Key<'a> = &'a str;
    fn key(&self) -> Self::Key<'_> {
        &self.id
    }
    id_upcast!();
}

let mut map: IdOrdMap<Item> = IdOrdMap::with_capacity(100);
map.insert_unique(Item { id: "foo".to_string(), value: 1 }).unwrap();
map.insert_unique(Item { id: "bar".to_string(), value: 2 }).unwrap();
assert!(map.capacity() >= 100);
map.shrink_to_fit();
assert!(map.capacity() >= 2);
```

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

### BiHashMap::new_in() example with bumpalo allocator

Source: https://docs.rs/iddqd/latest/iddqd/bi_hash_map/struct.BiHashMap.html

Creates a new empty BiHashMap using a given allocator. Requires the 'default-hasher' and 'allocator-api2' features. The example uses the bumpalo allocator and asserts the map is empty.

```rust
use iddqd::{BiHashMap, BiHashItem, bi_upcast};

#[derive(Debug, PartialEq, Eq)]
struct Item {
    id: u32,
    name: String,
    value: i32,
}

impl BiHashItem for Item {
    type K1<'a> = u32;
    type K2<'a> = &'a str;

    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        &self.name
    }
    bi_upcast!();
}

// Define a new allocator.
let bump = bumpalo::Bump::new();
// Create a new BiHashMap using the allocator.
let map: BiHashMap<Item, _, &bumpalo::Bump> = BiHashMap::new_in(&bump);
assert!(map.is_empty());
```

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

### Retrieve an entry by keys using entry

Source: https://docs.rs/iddqd/latest/iddqd/bi_hash_map/struct.BiHashMap.html

Demonstrates how to use the entry method to access or insert items in a BiHashMap. It shows handling both occupied and vacant entry states.

```rust
use iddqd::{BiHashItem, BiHashMap, bi_hash_map, bi_upcast};

#[derive(Debug, PartialEq, Eq)]
struct Item {
    id: u32,
    name: String,
    value: i32,
}

impl BiHashItem for Item {
    type K1<'a> = u32;
    type K2<'a> = &'a str;

    fn key1(&self) -> Self::K1<'_> {
        self.id
    }
    fn key2(&self) -> Self::K2<'_> {
        &self.name
    }
    bi_upcast!();
}

let mut map = BiHashMap::new();
map.insert_unique(Item { id: 1, name: "foo".to_string(), value: 42 })
    .unwrap();

// Get an existing entry.
match map.entry(1, "foo") {
    bi_hash_map::Entry::Occupied(entry) => {
        assert_eq!(entry.get().as_unique().unwrap().value, 42);
    }
    bi_hash_map::Entry::Vacant(_) => panic!("Should be occupied"),
}

// Try to get a non-existing entry.
match map.entry(2, "bar") {
    bi_hash_map::Entry::Occupied(_) => panic!("Should be vacant"),
    bi_hash_map::Entry::Vacant(entry) => {
        entry.insert(Item { id: 2, name: "bar".to_string(), value: 99 });
    }
}

assert_eq!(map.len(), 2);
```

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

### Initialize IdHashMap with a custom hasher

Source: https://docs.rs/iddqd/latest/src/iddqd/id_hash_map/imp.rs.html

Demonstrates creating an IdHashMap using a specific RandomState hasher.

```rust
///     id: String,
///     value: u32,
/// }
///
/// impl IdHashItem for Item {
///     type Key<'a> = &'a str;
///     fn key(&self) -> Self::Key<'_> {
///         &self.id
///     }
///     id_upcast!();
/// }
///
/// let hasher = RandomState::new();
/// let map: IdHashMap<Item, _> = IdHashMap::with_hasher(hasher);
/// assert!(map.is_empty());
/// ```
```