### get example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Returns a reference to the value corresponding to the key. The key may be any borrowed form of the map's key type, but Hash and Eq on the borrowed form must match those for the key type.

```rust
use papaya::HashMap;

let map = HashMap::new();
map.pin().insert(1, "a");
assert_eq!(map.pin().get(&1), Some(&"a"));
assert_eq!(map.pin().get(&2), None);
```

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

### Constructing a HashMap with HashMapBuilder

Source: https://docs.rs/papaya/latest/papaya/struct.HashMapBuilder.html

Example demonstrating how to configure a HashMap using the builder pattern, including setting capacity, hasher, resize mode, and collector.

```rust
use papaya::{HashMap, ResizeMode};
use seize::Collector;
use std::collections::hash_map::RandomState;

let map: HashMap<i32, i32> = HashMap::builder()
    // Set the initial capacity.
    .capacity(2048)
    // Set the hasher.
    .hasher(RandomState::new())
    // Set the resize mode.
    .resize_mode(ResizeMode::Blocking)
    // Set a custom garbage collector.
    .collector(Collector::new().batch_size(128))
    // Construct the hash map.
    .build();
```

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

### Example: building a HashSet with builder options

Source: https://docs.rs/papaya/latest/papaya/struct.HashSetBuilder.html

Shows how to use HashSet::builder() to configure a HashSet with capacity, hasher, resize mode, and a custom collector, then build it.

```rust
use papaya::{HashSet, ResizeMode};
use seize::Collector;
use std::collections::hash_map::RandomState;

let set: HashSet<i32> = HashSet::builder()
    // Set the initial capacity.
    .capacity(2048)
    // Set the hasher.
    .hasher(RandomState::new())
    // Set the resize mode.
    .resize_mode(ResizeMode::Blocking)
    // Set a custom garbage collector.
    .collector(Collector::new().batch_size(128))
    // Construct the hash set.
    .build();
```

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

### keys example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

An iterator visiting all keys in arbitrary order. The iterator element type is &K. Note that this method will block until any in-progress resizes are completed before proceeding.

```rust
use papaya::HashMap;

let map = HashMap::from([
    ("a", 1),
    ("b", 2),
    ("c", 3),
]);

for key in map.pin().keys() {
    println!("{key}");
}
```

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

### get_or_insert example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Returns a reference to the value corresponding to the key, or inserts a default value. If the key is present, the corresponding value is returned; otherwise, the provided value is inserted and a reference to it is returned.

```rust
use papaya::HashMap;

let map = HashMap::new();
assert_eq!(map.pin().get_or_insert("a", 3), &3);
assert_eq!(map.pin().get_or_insert("a", 6), &3);
```

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

### insert example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Inserts a key-value pair into the map. If the key was not present, None is returned. If the key was present, the value is updated and the old value is returned; the key is not updated.

```rust
use papaya::HashMap;

let map = HashMap::new();
assert_eq!(map.pin().insert(37, "a"), None);
assert_eq!(map.pin().is_empty(), false);

map.pin().insert(37, "b");
assert_eq!(map.pin().insert(37, "c"), Some(&"b"));
assert_eq!(map.pin().get(&37), Some(&"c"));
```

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

### try_insert_with example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Tries to insert a key and value computed from a closure into the map. If the key is already present, nothing is updated and the existing value is returned.

```rust
use papaya::HashMap;

let map = HashMap::new();
let map = map.pin();

assert_eq!(map.try_insert_with(37, || "a").unwrap(), &"a");

let current = map.try_insert_with(37, || "b").unwrap_err();
assert_eq!(current, &"a");
```

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

### reserve example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Tries to reserve capacity for additional elements to be inserted in the HashMap. After calling this method, the table should be able to hold at least capacity elements before resizing. Panics if the new allocation size overflows usize.

```rust
use papaya::HashMap;

let map: HashMap<&str, i32> = HashMap::new();
map.pin().reserve(10);
```

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

### is_empty example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Checks if the map is empty. Returns true if empty, false otherwise.

```rust
use papaya::HashMap;

let map = HashMap::new();
assert!(map.is_empty());
map.pin().insert("a", 1);
assert!(!map.is_empty());
```

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

### Get number of entries with HashSet::len

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Returns the number of entries in the set. The example creates a set, inserts two values, and asserts the length is 2.

```rust
use papaya::HashSet;

let set = HashSet::new();

set.pin().insert(1);
set.pin().insert(2);
assert!(set.len() == 2);
```

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

### try_insert example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Tries to insert a key-value pair into the map. If the key is already present, nothing is updated and an error containing the existing value is returned.

```rust
use papaya::HashMap;

let map = HashMap::new();
let map = map.pin();

assert_eq!(map.try_insert(37, "a").unwrap(), &"a");

let err = map.try_insert(37, "b").unwrap_err();
assert_eq!(err.current, &"a");
assert_eq!(err.not_inserted, "b");
```

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

### Create an empty HashMap with HashMap::new

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Creates an empty `HashMap` with a capacity of 0, so it will not allocate until the first insertion. The example shows a map with `&str` keys and `i32` values.

```rust
use papaya::HashMap;
let map: HashMap<&str, i32> = HashMap::new();
```

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

### Basic HashMap usage with pinning

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

Shows how to create a papaya HashMap, pin it, and perform basic operations like insert, get, and len. Pinning is required to access the map and is similar to a lock guard but cheaper and deadlock-free.

```rust
use papaya::HashMap;

// Create a map.
let map = HashMap::new();

// Pin the map.
let map = map.pin();

// Use the map as normal.
map.insert('A', 1);
assert_eq!(map.get(&'A'), Some(&1));
assert_eq!(map.len(), 1);
```

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

### Create a HashMap with capacity and custom hasher using HashMap::with_capacity_and_hasher

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Creates an empty `HashMap` with at least the specified capacity and a custom hash builder. Warning: setting a manual hasher can expose a DoS attack vector. The example uses `RandomState` and inserts a key-value pair via `pin().insert`.

```rust
use papaya::HashMap;
use std::hash::RandomState;

let s = RandomState::new();
let map = HashMap::with_capacity_and_hasher(10, s);
map.pin().insert(1, 2);
```

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

### Get the number of entries with HashMap::len

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Returns the number of entries in the map. The example inserts two entries and asserts the length is 2.

```rust
use papaya::HashMap;

let map = HashMap::new();

map.pin().insert(1, "a");
map.pin().insert(2, "b");
assert!(map.len() == 2);
```

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

### get

Source: https://docs.rs/papaya/latest/papaya/struct.HashSetRef.html

Returns a reference to the value corresponding to the key.

```APIDOC
## get

### Description
Returns a reference to the value corresponding to the key. See `HashSet::get` for details.

### Method
`pub fn get<Q>(&self, key: &Q) -> Option<&K> where Q: Equivalent<K> + Hash + ?Sized`

### Parameters
- `&self` - The reference to the `HashSetRef`.
- `key: &Q` - The key to look up.

### Returns
- `Option<&K>` - A reference to the value if found, `None` otherwise.
```

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

### Get reference to value with HashSet::get

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Returns a reference to the value corresponding to the key. The key may be any borrowed form of the set's key type, but Hash and Eq on the borrowed form must match those for the key type. The example inserts 1 and asserts get(&1) returns Some(&1) and get(&2) returns None.

```rust
use papaya::HashSet;

let set = HashSet::new();
set.pin().insert(1);
assert_eq!(set.pin().get(&1), Some(&1));
assert_eq!(set.pin().get(&2), None);
```

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

### clear example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Clears the map, removing all key-value pairs. Note that this method will block until any in-progress resizes are completed before proceeding.

```rust
use papaya::HashMap;

let map = HashMap::new();

map.pin().insert(1, "a");
map.pin().clear();
assert!(map.pin().is_empty());
```

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

### get_or_insert_with example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Returns a reference to the value corresponding to the key, or inserts a default value computed from a closure. If the key is present, the corresponding value is returned; otherwise, the value from the closure is inserted and a reference to it is returned.

```rust
use papaya::HashMap;

let map = HashMap::new();
assert_eq!(map.pin().get_or_insert_with("a", || 3), &3);
assert_eq!(map.pin().get_or_insert_with("a", || 6), &3);
```

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

### iter example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

An iterator visiting all key-value pairs in arbitrary order. The iterator element type is (&K, &V). Note that this method will block until any in-progress resizes are completed before proceeding.

```rust
use papaya::HashMap;

let map = HashMap::from([
    ("a", 1),
    ("b", 2),
    ("c", 3),
]);

for (key, val) in map.pin().iter() {
    println!("key: {key} val: {val}");
}
```

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

### Create a HashMap with a custom hasher using HashMap::with_hasher

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Creates an empty `HashMap` using a given hash builder. Warning: setting a manual hasher can expose a DoS attack vector. The example uses `RandomState` and inserts a key-value pair via `pin().insert`.

```rust
use papaya::HashMap;
use std::hash::RandomState;

let s = RandomState::new();
let map = HashMap::with_hasher(s);
map.pin().insert(1, 2);
```

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

### Update or insert with update_or_insert()

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Updates an existing entry or inserts a provided default value. Returns a reference to the resulting value. Example shows first insert returning 0, then update returning 1.

```rust
use papaya::HashMap;

let map = HashMap::new();
assert_eq!(*map.pin().update_or_insert("a", |i| i + 1, 0), 0);
assert_eq!(*map.pin().update_or_insert("a", |i| i + 1, 0), 1);
```

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

### Reserve capacity with HashSet::reserve

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Tries to reserve capacity for additional elements. Panics if the new allocation size overflows usize. The example reserves capacity for 10 more elements.

```rust
use papaya::HashSet;

let set: HashSet<&str> = HashSet::new();
set.pin().reserve(10);
```

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

### Iterate over values with HashMap::values

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Example of using the values method on a papaya::HashMap to iterate over all values in arbitrary order. The iterator yields references to the values, and the method blocks until any in-progress resizes are completed.

```rust
use papaya::HashMap;

let map = HashMap::from([
    ("a", 1),
    ("b", 2),
    ("c", 3),
]);

for value in map.pin().values() {
    println!("{value}");
}
```

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

### Iterate over values with HashSet::iter

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

An iterator visiting all values in arbitrary order. Blocks until any in-progress resizes are completed before proceeding. The example creates a set from an array and prints each value.

```rust
use papaya::HashSet;

let set = HashSet::from([
    "a",
    "b",
    "c"
]);

for val in set.pin().iter() {
    println!("val: {val}");
}
```

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

### get_key_value example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Returns the key-value pair corresponding to the supplied key. The supplied key may be any borrowed form of the map's key type, but Hash and Eq on the borrowed form must match those for the key type.

```rust
use papaya::HashMap;

let map = HashMap::new();
map.pin().insert(1, "a");
assert_eq!(map.pin().get_key_value(&1), Some((&1, &"a")));
assert_eq!(map.pin().get_key_value(&2), None);
```

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

### retain example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Retains only the elements specified by the predicate. The elements are visited in unsorted order. Note the function may be called more than once for a given key if its value is concurrently modified during removal. This method will block until any in-progress resizes are completed before proceeding.

```rust
use papaya::HashMap;

let mut map: HashMap<i32, i32> = (0..8).map(|x| (x, x * 10)).collect();
map.pin().retain(|&k, _| k % 2 == 0);
assert_eq!(map.len(), 4);
```

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

### remove_entry example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Removes a key from the map, returning the stored key and value if the key was previously in the map. The key may be any borrowed form of the map's key type, but Hash and Eq on the borrowed form must match those for the key type.

```rust
use papaya::HashMap;

let map = HashMap::new();
map.pin().insert(1, "a");
assert_eq!(map.pin().get(&1), Some(&"a"));
assert_eq!(map.pin().remove_entry(&1), Some((&1, &"a")));
assert_eq!(map.pin().remove(&1), None);
```

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

### Create a HashSet with capacity and hasher using with_capacity_and_hasher()

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Creates an empty HashSet with at least the specified capacity and a custom hash builder. The hasher must implement BuildHasher. Warning: manually setting the hasher can expose a DoS attack vector.

```rust
use papaya::HashSet;
use std::hash::RandomState;

let s = RandomState::new();
let set = HashSet::with_capacity_and_hasher(10, s);
set.pin().insert(1);
```

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

### Insert value with HashSet::insert

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Inserts a value into the set. Returns true if the key was not present, false if it was present (and the old value is not updated). The example inserts 37 twice, asserting the first insert returns true and the second returns false, and that get(&37) returns Some(&37).

```rust
use papaya::HashSet;

let set = HashSet::new();
assert_eq!(set.pin().insert(37), true);
assert_eq!(set.pin().is_empty(), false);

set.pin().insert(37);
assert_eq!(set.pin().insert(37), false);
assert_eq!(set.pin().get(&37), Some(&37));
```

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

### Create a HashSet with capacity using with_capacity()

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Creates an empty HashSet with the specified capacity. The set can hold at least that many elements before resizing, though poor hash distribution may cause premature resizing. If capacity is 0, no allocation occurs.

```rust
use papaya::HashSet;
let set: HashSet<&str> = HashSet::with_capacity(10);
```

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

### Create a HashSet with a custom hasher using with_hasher()

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Creates an empty HashSet using a custom hash builder. Warning: manually setting the hasher can expose a DoS attack vector because the default random hasher provides collision resistance. The hasher must implement BuildHasher.

```rust
use papaya::HashSet;
use std::hash::RandomState;

let s = RandomState::new();
let set = HashSet::with_hasher(s);
set.pin().insert(1);
```

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

### HashSetBuilder::build

Source: https://docs.rs/papaya/latest/papaya/struct.HashSetBuilder.html

Constructs a HashSet from the builder using the configured options.

```APIDOC
## HashSetBuilder::build

### Description
Constructs a `HashSet` from the builder, using the configured options.

### Method
pub fn build(self) -> HashSet<K, S>

### Parameters
None.

### Returns
- **HashSet<K, S>** - The constructed hash set.

```

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

### HashSet::with_capacity_and_hasher

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Creates an empty HashSet with a specified capacity and custom hash builder, with a warning about potential DoS attack vectors.

```APIDOC
## HashSet::with_capacity_and_hasher

### Description
Creates an empty `HashSet` with at least the specified capacity, using `hash_builder` to hash the keys. The set should be able to hold at least `capacity` elements before resizing. However, the capacity is an estimate, and the set may prematurely resize due to poor hash distribution. If `capacity` is 0, the hash set will not allocate. Warning: `hash_builder` is normally randomly generated, and is designed to allow HashSets to be resistant to attacks that cause many collisions and very poor performance. Setting it manually using this function can expose a DoS attack vector. The `hasher` passed should implement the `BuildHasher` trait for the HashSet to be useful, see its documentation for details.

### Method
`pub fn with_capacity_and_hasher(capacity: usize, hash_builder: S) -> HashSet<K, S>`

### Parameters
- **capacity** (usize) - Required - The desired capacity of the set.
- **hash_builder** (S) - Required - The hash builder to use for hashing keys.

### Returns
- **HashSet<K, S>** - A new empty `HashSet` with the specified capacity and hash builder.

### Example
```rust
use papaya::HashSet;
use std::hash::RandomState;

let s = RandomState::new();
let set = HashSet::with_capacity_and_hasher(10, s);
set.pin().insert(1);
```
```

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

### take

Source: https://docs.rs/papaya/latest/papaya/struct.Keys.html

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

```APIDOC
## take

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

### Signature
fn take(self, n: usize) -> Take<Self> ⓘ
where Self: Sized,

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

### Stability
1.0.0 (const: unstable)
```

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

### Clear set with HashSet::clear

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Clears the set, removing all values. Blocks until any in-progress resizes are completed before proceeding. The example inserts 1, clears, and asserts the set is empty.

```rust
use papaya::HashSet;

let set = HashSet::new();

set.pin().insert(1);
set.pin().clear();
assert!(set.pin().is_empty());
```

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

### HashMapBuilder::build

Source: https://docs.rs/papaya/latest/papaya/struct.HashMapBuilder.html

Constructs a `HashMap` from the builder, using the configured options.

```APIDOC
## build

### Description
Constructs a `HashMap` from the builder, using the configured options.

### Method
`pub fn build(self) -> HashMap<K, V, S>`

### Parameters
None.

### Returns
- `HashMap<K, V, S>` - The constructed hash map.

### Example
```rust
use papaya::{HashMap, ResizeMode};
use std::collections::hash_map::RandomState;

let map: HashMap<i32, i32> = HashMap::builder()
    .capacity(2048)
    .hasher(RandomState::new())
    .resize_mode(ResizeMode::Blocking)
    .build();
```
```

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

### Check if set is empty with HashSet::is_empty

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Returns true if the set is empty, otherwise false. The example asserts the set is initially empty, inserts a value, then asserts it is not empty.

```rust
use papaya::HashSet;

let set = HashSet::new();
assert!(set.is_empty());
set.pin().insert("a");
assert!(!set.is_empty());
```

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

### Create a HashMap with capacity using HashMap::with_capacity

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Creates an empty `HashMap` with the specified capacity. The table should hold at least `capacity` elements before resizing, but may prematurely resize due to poor hash distribution. If `capacity` is 0, the map will not allocate.

```rust
use papaya::HashMap;
let map: HashMap<&str, i32> = HashMap::with_capacity(10);
```

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

### Standard HashMap entry API with and_modify and or_insert

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

Shows the standard library approach for updating or inserting an entry, using Entry::and_modify and Entry::or_insert. This is not thread-safe and is provided for comparison with the concurrent version.

```rust
use std::collections::HashMap;

let mut map = HashMap::new();
// Insert `poneyland` with the value `42` if it doesn't exist,
// otherwise increment it's value.
map.entry("poneyland")
   .and_modify(|e| { *e += 1 })
   .or_insert(42);
```

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

### HashMap::with_capacity_and_hasher

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Creates an empty HashMap with a specified capacity and custom hash builder, with a warning about potential DoS attacks.

```APIDOC
## HashMap::with_capacity_and_hasher

### Description
Creates an empty `HashMap` with at least the specified capacity, using `hash_builder` to hash the keys.

The table should be able to hold at least `capacity` elements before resizing. However, the capacity is an estimate, and the table may prematurely resize due to poor hash distribution. If `capacity` is 0, the hash map will not allocate.

Warning: `hash_builder` is normally randomly generated, and is designed to allow HashMaps to be resistant to attacks that cause many collisions and very poor performance. Setting it manually using this function can expose a DoS attack vector.

### Method
`pub fn with_capacity_and_hasher(capacity: usize, hash_builder: S) -> HashMap<K, V, S>`

### Parameters
#### Parameters
- **capacity** (usize) - Required - The minimum number of elements the map should hold before resizing.
- **hash_builder** (S) - Required - The hash builder to use for hashing keys. Should implement the `BuildHasher` trait.

### Request Example
```rust
use papaya::HashMap;
use std::hash::RandomState;

let s = RandomState::new();
let map = HashMap::with_capacity_and_hasher(10, s);
map.pin().insert(1, 2);
```

### Response
#### Success Response
Returns an empty `HashMap<K, V, S>` with the specified capacity and hash builder.

#### Response Example
```rust
let s = RandomState::new();
let map = HashMap::with_capacity_and_hasher(10, s);
```
```

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

### Async iteration with owned guard

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

Use pin_owned to iterate over the map asynchronously, holding references across await points. This is a more fitting example than the previous one when you need to perform async operations for each entry.

```rust
use papaya::HashMap;

async fn run(map: Arc<HashMap<i32, String>>) {
    tokio::spawn(async move {
        for (key, value) in map.pin_owned().iter() {
            tokio::fs::write("db.txt", format!("{key}: {value}\n")).await;
        }
    });
}
```

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

### HashSet::new

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Creates an empty HashSet with a capacity of 0, which will not allocate until the first insertion.

```APIDOC
## HashSet::new

### Description
Creates an empty `HashSet`. The hash set is initially created with a capacity of 0, so it will not allocate until it is first inserted into.

### Method
`pub fn new() -> HashSet<K>`

### Parameters
None

### Returns
- **HashSet<K>** - A new empty `HashSet`.

### Example
```rust
use papaya::HashSet;
let map: HashSet<&str> = HashSet::new();
```
```

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

### Create an empty HashSet with new()

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Creates an empty HashSet with a capacity of 0, so it does not allocate until the first insertion. The type parameter K is the key type.

```rust
use papaya::HashSet;
let map: HashSet<&str> = HashSet::new();
```

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

### contains_key example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Checks if the map contains a value for the specified key. The key may be any borrowed form of the map's key type, but Hash and Eq on the borrowed form must match those for the key type.

```rust
use papaya::HashMap;

let map = HashMap::new();
map.pin().insert(1, "a");
assert_eq!(map.pin().contains_key(&1), true);
assert_eq!(map.pin().contains_key(&2), false);
```

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

### partition

Source: https://docs.rs/papaya/latest/papaya/struct.Keys.html

Consumes an iterator, creating two collections from it.

```APIDOC
## partition

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

### Signature
fn partition<B, F>(self, f: F) -> (B, B)
where Self: Sized, B: Default + Extend<Self::Item>, F: FnMut(&Self::Item) -> bool,

### Parameters
- **f** (F) - Required - A closure that determines which collection each item goes into.

### Stability
1.0.0 (const: unstable)
```

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

### HashMap::new

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Creates an empty HashMap with a capacity of 0, which will not allocate until the first insertion.

```APIDOC
## HashMap::new

### Description
Creates an empty `HashMap`.

The hash map is initially created with a capacity of 0, so it will not allocate until it is first inserted into.

### Method
`pub fn new() -> HashMap<K, V>`

### Parameters
None.

### Request Example
```rust
use papaya::HashMap;
let map: HashMap<&str, i32> = HashMap::new();
```

### Response
#### Success Response
Returns an empty `HashMap<K, V>`.

#### Response Example
```rust
let map: HashMap<&str, i32> = HashMap::new();
```
```

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

### Remove entry with remove()

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Removes a key from the map and returns the value if present, otherwise None. The key may be any borrowed form that matches Hash and Eq. Example shows removing an existing key and then a missing key.

```rust
use papaya::HashMap;

let map = HashMap::new();
map.pin().insert(1, "a");
assert_eq!(map.pin().remove(&1), Some(&"a"));
assert_eq!(map.pin().remove(&1), None);
```

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

### Update existing entry with update()

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Atomically updates the value for a key if present, returning the new value or None. The update closure may be called multiple times and should be pure. Example shows inserting then updating a value.

```rust
use papaya::HashMap;

let map = HashMap::new();
map.pin().insert("a", 1);
assert_eq!(map.pin().get(&"a"), Some(&1));

map.pin().update("a", |v| v + 1);
assert_eq!(map.pin().get(&"a"), Some(&2));
```

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

### set

Source: https://docs.rs/papaya/latest/papaya/struct.HashSetRef.html

Returns a reference to the inner `HashSet`.

```APIDOC
## set

### Description
Returns a reference to the inner `HashSet`.

### Method
`pub fn set(&self) -> &'set HashSet<K, S>`

### Parameters
- `&self` - The reference to the `HashSetRef`.

### Returns
- `&'set HashSet<K, S>` - A reference to the inner `HashSet`.
```

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

### Error returning reference to temporary value

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

This example shows a compile error (E0515) when trying to return a reference to a map contained within an outer type. The error occurs because the guard is a temporary value and the reference cannot outlive it.

```rust
pub struct Metrics {
    map: papaya::HashMap<String, Vec<u64>>
}

impl Metrics {
    pub fn get(&self, name: &str) -> Option<&[u64]> {
        // error[E0515]: cannot return value referencing temporary value
        Some(self.map.pin().get(name)?.as_slice())
    }
}
```

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

### HashSet::with_hasher

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Creates an empty HashSet using a custom hash builder, with a warning about potential DoS attack vectors.

```APIDOC
## HashSet::with_hasher

### Description
Creates an empty `HashSet` which will use the given hash builder to hash keys. Warning: `hash_builder` is normally randomly generated, and is designed to allow HashSets to be resistant to attacks that cause many collisions and very poor performance. Setting it manually using this function can expose a DoS attack vector. The `hash_builder` passed should implement the `BuildHasher` trait for the HashSet to be useful, see its documentation for details.

### Method
`pub fn with_hasher(hash_builder: S) -> HashSet<K, S>`

### Parameters
- **hash_builder** (S) - Required - The hash builder to use for hashing keys.

### Returns
- **HashSet<K, S>** - A new empty `HashSet` using the provided hash builder.

### Example
```rust
use papaya::HashSet;
use std::hash::RandomState;

let s = RandomState::new();
let set = HashSet::with_hasher(s);
set.pin().insert(1);
```
```

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

### Update or insert with closure using update_or_insert_with()

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Updates an existing entry or inserts a value computed by a closure. The closure is only called when the key is absent. Example shows first call inserting 0, second call updating to 1.

```rust
use papaya::HashMap;

let map = HashMap::new();
assert_eq!(*map.pin().update_or_insert_with("a", |i| i + 1, || 0), 0);
assert_eq!(*map.pin().update_or_insert_with("a", |i| i + 1, || 0), 1);
```

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

### Compute complex operations with compute()

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Performs compare-and-swap style operations using a compute closure that returns an Operation. The closure may be retried and should be pure. Example shows removing even values, incrementing odd values, and aborting on missing keys.

```rust
use papaya::{HashMap, Operation, Compute};

let map = HashMap::new();
let map = map.pin();

let compute = |entry| match entry {
    // Remove the value if it is even.
    Some((_key, value)) if value % 2 == 0 => {
        Operation::Remove
    }

    // Increment the value if it is odd.
    Some((_key, value)) => {
        Operation::Insert(value + 1)
    }

    // Do nothing if the key does not exist
    None => Operation::Abort(()),
};

assert_eq!(map.compute('A', compute), Compute::Aborted(()));

map.insert('A', 1);
assert_eq!(map.compute('A', compute), Compute::Updated {
    old: (&'A', &1),
    new: (&'A', &2),
});
assert_eq!(map.compute('A', compute), Compute::Removed(&'A', &2));
```

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

### by_ref

Source: https://docs.rs/papaya/latest/papaya/struct.Keys.html

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

```APIDOC
## by_ref

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

### Signature
fn by_ref(&mut self) -> &mut Self
where Self: Sized,

### Stability
1.0.0 (const: unstable)
```

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

### product

Source: https://docs.rs/papaya/latest/papaya/struct.Keys.html

Iterates over the entire iterator, multiplying all the elements.

```APIDOC
## product

### Description
Iterates over the entire iterator, multiplying all the elements.

### Method
product

### Signature
fn product<P>(self) -> P
where Self: Sized, P: Product<Self::Item>

### Returns
- **P** - The product of all elements.
```

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

### remove_if example

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Conditionally removes a key from the map based on the provided closure. If the key is found and the closure returns true, the key and value are returned successfully. If the closure returns false, an error is returned containing the entry provided to the closure. If the key is not found, Ok(None) is returned.

```rust
use papaya::HashMap;

let map = HashMap::new();
map.pin().insert(1, "a");

assert_eq!(map.pin().remove_if(&1, |k, v| *v == "b"), Err((&1, &"a")));
assert_eq!(map.pin().get(&1), Some(&"a"));
assert_eq!(map.pin().remove_if(&1, |k, v| *v == "a"), Ok(Some((&1, &"a"))));
assert_eq!(map.pin().remove_if(&1, |_, _| true), Ok(None));
```

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

### Retain elements with HashSet::retain

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Retains only elements specified by the predicate. Elements are visited in unsorted order, and the function may be called more than once for a given key if concurrently modified. Blocks until in-progress resizes complete. The example retains even numbers from 0..8 and asserts the set has 4 elements, contains 2, and not 1.

```rust
use papaya::HashSet;

let set: HashSet<i32> = (0..8).collect();
set.pin().retain(|&v| v % 2 == 0);
assert_eq!(set.len(), 4);
assert_eq!(set.pin().contains(&1), false);
assert_eq!(set.pin().contains(&2), true);
```

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

### HashMap::with_hasher

Source: https://docs.rs/papaya/latest/papaya/struct.HashMap.html

Creates an empty HashMap using a custom hash builder, with a warning about potential DoS attacks if not randomly generated.

```APIDOC
## HashMap::with_hasher

### Description
Creates an empty `HashMap` which will use the given hash builder to hash keys.

Warning: `hash_builder` is normally randomly generated, and is designed to allow HashMaps to be resistant to attacks that cause many collisions and very poor performance. Setting it manually using this function can expose a DoS attack vector.

### Method
`pub fn with_hasher(hash_builder: S) -> HashMap<K, V, S>`

### Parameters
#### Parameters
- **hash_builder** (S) - Required - The hash builder to use for hashing keys. Should implement the `BuildHasher` trait.

### Request Example
```rust
use papaya::HashMap;
use std::hash::RandomState;

let s = RandomState::new();
let map = HashMap::with_hasher(s);
map.pin().insert(1, 2);
```

### Response
#### Success Response
Returns an empty `HashMap<K, V, S>` using the provided hash builder.

#### Response Example
```rust
let s = RandomState::new();
let map = HashMap::with_hasher(s);
```
```

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

### Remove value with HashSet::remove

Source: https://docs.rs/papaya/latest/papaya/struct.HashSet.html

Removes a key from the set, returning true if the key was previously in the set. The key may be any borrowed form of the set's key type, but Hash and Eq on the borrowed form must match those for the key type. The example inserts 1, removes it (returns true), then removes it again (returns false).

```rust
use papaya::HashSet;

let set = HashSet::new();
set.pin().insert(1);
assert_eq!(set.pin().remove(&1), true);
assert_eq!(set.pin().remove(&1), false);
```