### Example: Using entry_async

Source: https://docs.rs/scc/3.4.14/scc/hash_map/struct.Reserve_search=std%3A%3Avec

Provides a basic example of how to use the `entry_async` method to get an entry for a specific key in a `HashMap`.

```rust
use scc::HashMap;

let hashmap: HashMap<char, u32> = HashMap::default();

let future_entry = hashmap.entry_async('b');

```

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

### HashCache Capacity and Eviction Example (Rust)

Source: https://docs.rs/scc/3.4.14/index

Shows how to create and use `HashCache`, a concurrent cache. This example demonstrates setting capacity, checking capacity ranges, putting and getting entries, and the LRU eviction policy when a bucket is full.

```Rust
use scc::HashCache;

let hashcache: HashCache<u64, u32> = HashCache::with_capacity(100, 2000);

/// The capacity cannot exceed the maximum capacity.
assert_eq!(hashcache.capacity_range(), 128..=2048);

/// If the bucket corresponding to `1` or `2` is full, the LRU entry will be evicted.
assert!(hashcache.put_sync(1, 0).is_ok());
assert!(hashcache.put_sync(2, 0).is_ok());

/// `1` becomes the most recently accessed entry in the bucket.
assert!(hashcache.get_sync(&1).is_some());

/// An entry can be normally removed.
assert_eq!(hashcache.remove_sync(&2).unwrap(), (2, 0));
```

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

### Example: Using try_entry

Source: https://docs.rs/scc/3.4.14/scc/hash_map/struct.Reserve_search=std%3A%3Avec

Shows an example of using `try_entry` to check if an entry exists and is accessible for manipulation in a `HashMap`. It first inserts a value and then attempts to get its entry.

```rust
use scc::HashMap;

let hashmap: HashMap<usize, usize> = HashMap::default();

assert!(hashmap.insert_sync(0, 1).is_ok());
assert!(hashmap.try_entry(0).is_some());

```

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

### Example: Using begin_async

Source: https://docs.rs/scc/3.4.14/scc/hash_map/struct.Reserve_search=std%3A%3Avec

Provides a basic example of initiating an asynchronous iteration over a `HashMap` using `begin_async`.

```rust
use scc::HashMap;

let hashmap: HashMap<char, u32> = HashMap::default();

let future_entry = hashmap.begin_async();

```

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

### Rust: Common Search Examples

Source: https://docs.rs/scc/3.4.14/src/scc/hash_cache.rs_search=

Provides common search query examples for Rust code, illustrating type signatures and generic type manipulation. These examples are useful for navigating and understanding Rust codebases.

```rust
std::vec
```

```rust
u32 -> bool
```

```rust
Option<T>, (T -> U) -> Option<U>
```

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

### Iteration Start (Async and Sync)

Source: https://docs.rs/scc/3.4.14/scc/hash_map/struct.HashMap_search=u32+-%3E+bool

Methods to begin iterating over map entries, starting with the first occupied entry.

```APIDOC
## Begin Async Iteration

### Description
Begins iterating over entries by getting the first occupied entry asynchronously. The returned `OccupiedEntry` can be used with `OccupiedEntry::next_async` to act as a mutable iterator.

### Method
`begin_async`

### Endpoint
N/A (Method on HashMap instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use scc::HashMap;

let hashmap: HashMap<char, u32> = HashMap::default();

let future_entry = hashmap.begin_async();
```

### Response
#### Success Response (200)
Returns `Some(OccupiedEntry)` representing the first occupied entry, or `None` if the map is empty.

#### Response Example
N/A

---

## Begin Sync Iteration

### Description
Begins iterating over entries by getting the first occupied entry synchronously. The returned `OccupiedEntry` can be used with `OccupiedEntry::next_sync` to act as a mutable iterator.

### Method
`begin_sync`

### Endpoint
N/A (Method on HashMap instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert_sync(1, 0).is_ok());

let mut first_entry = hashmap.begin_sync().unwrap();
*first_entry.get_mut() = 2;

assert!(first_entry.next_sync().is_none());
assert_eq!(hashmap.read_sync(&1, |_, v| *v), Some(2));
```

### Response
#### Success Response (200)
Returns `Some(OccupiedEntry)` representing the first occupied entry, or `None` if the map is empty.

#### Response Example
N/A
```

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

### HashIndex Example Usage (Rust)

Source: https://docs.rs/scc/3.4.14/src/scc/hash_index.rs

Demonstrates basic operations on a `HashIndex`, including insertion, retrieval, and checking for existence. This example showcases `insert_sync`, `get_sync`, and `contains` methods.

```Rust
use scc::HashIndex;

let hashindex: HashIndex<u64, u32> = HashIndex::default();

assert!(hashindex.get_sync(&1).is_none());
assert!(hashindex.insert_sync(1, 10).is_ok());
assert_eq!(*hashindex.get_sync(&1).unwrap().get(), 10);
assert_eq!(*hashindex.get_sync(&1).unwrap(), 10);

assert!(!hashindex.contains(&1));
assert!(hashindex.insert_sync(1, 0).is_ok());
assert!(hashindex.contains(&1));

use sdd::Guard;

let guard = Guard::new();
let value_ref = hashindex.peek(&1, &guard).unwrap();
assert_eq!(*value_ref, 10);

assert!(hashindex.peek_with(&1, |_, v| *v).is_none());
assert!(hashindex.insert_sync(1, 10).is_ok());
assert_eq!(hashindex.peek_with(&1, |_, v| *v).unwrap(), 10);
```

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

### Example Usage of HashMap Replace with Custom Key Type

Source: https://docs.rs/scc/3.4.14/src/scc/hash_map.rs

Demonstrates the usage of `replace_async` and `replace_sync` with a custom `MaybeEqual` struct in Rust. This example highlights how `PartialEq` and `Hash` implementations affect key comparison and hashing, particularly when only a subset of fields are considered.

```rust
use std::cmp::{Eq, PartialEq};
use std::hash::{Hash, Hasher};

use scc::HashMap;
use scc::hash_map::ReplaceResult;

#[derive(Debug)]
struct MaybeEqual(u64, u64);

impl Eq for MaybeEqual {}

impl Hash for MaybeEqual {
    fn hash<H: Hasher>(&self, state: &mut H) {
        // Do not read `self.1`.
        self.0.hash(state);
    }
}

impl PartialEq for MaybeEqual {
    fn eq(&self, other: &Self) -> bool {
        // Do not compare `self.1`.
        self.0 == other.0
    }
}

let hashmap: HashMap<MaybeEqual, usize> = HashMap::default();

let ReplaceResult::NotReplaced(v) = hashmap.replace_sync(MaybeEqual(11, 7)) else {
    unreachable!();
};
drop(v.insert_entry(17));
let ReplaceResult::Replaced(_, k) = hashmap.replace_sync(MaybeEqual(11, 11)) else {
    unreachable!();
};
assert_eq!(k.1, 7);

```

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

### TreeIndex Range Scanning Example (Rust)

Source: https://docs.rs/scc/3.4.14/index

Demonstrates scanning a specific range of keys within a `TreeIndex`. This example shows how to efficiently retrieve entries within a given key range using the `range` method and a `Guard` for lock-free access.

```Rust
use scc::TreeIndex;

use sdd::Guard;

let treeindex: TreeIndex<u64, u32> = TreeIndex::new();

for i in 0..10 {
    assert!(treeindex.insert_sync(i, 10).is_ok());
}

let guard = Guard::new();

assert_eq!(treeindex.range(1..1, &guard).count(), 0);
assert_eq!(treeindex.range(4..8, &guard).count(), 4);
assert_eq!(treeindex.range(4..=8, &guard).count(), 5);
```

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

### Get Size of Rust SCC TreeIndex

Source: https://docs.rs/scc/3.4.14/scc/tree_index/struct.TreeIndex_search=std%3A%3Avec

Demonstrates how to get the number of elements in a TreeIndex. The example initializes an empty TreeIndex and asserts that its length is 0.

```rust
use scc::TreeIndex;

let treeindex: TreeIndex<u64, u32> = TreeIndex::new();
assert_eq!(treeindex.len(), 0);
```

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

### HashMap - Entry API Usage (Rust)

Source: https://docs.rs/scc/3.4.14/index

This example illustrates the use of the `Entry` API in `HashMap`. It demonstrates how to use `entry_sync`, `or_insert`, and `and_modify` methods to manipulate entries based on their presence in the map.

```Rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

hashmap.entry_sync(3).or_insert(7);
assert_eq!(hashmap.read_sync(&3, |_, v| *v), Some(7));

hashmap.entry_sync(4).and_modify(|v| { *v += 1 }).or_insert(5);
assert_eq!(hashmap.read_sync(&4, |_, v| *v), Some(5));
```

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

### Asynchronous Get Entry (Rust)

Source: https://docs.rs/scc/3.4.14/scc/hash_index/struct.HashIndex_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to asynchronously retrieve an `OccupiedEntry` for a given key in a HashIndex, allowing for in-place modification. This example shows inserting a value and then asynchronously getting its entry.

```Rust
use scc::HashIndex;

let hashindex: HashIndex<u64, u32> = HashIndex::default();
let future_insert = hashindex.insert_async(11, 17);
let future_get = hashindex.get_async(&11);
```

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

### Example: Using HashMap Reserve for Capacity Management

Source: https://docs.rs/scc/3.4.14/scc/hash_map/struct.Reserve_search=std%3A%3Avec

Demonstrates the usage of the `reserve` method on a `HashMap`. It shows how to increase capacity, check the new capacity, and how the capacity reverts after the `Reserve` guard is dropped. It also illustrates the error case where an excessively large capacity is requested.

```rust
use scc::HashMap;

let hashmap: HashMap<usize, usize> = HashMap::with_capacity(1000);
assert_eq!(hashmap.capacity(), 1024);

let reserved = hashmap.reserve(10000);
assert!(reserved.is_some());
assert_eq!(hashmap.capacity(), 16384);

assert!(hashmap.reserve(usize::MAX).is_none());
assert_eq!(hashmap.capacity(), 16384);

for i in 0..16 {
    assert!(hashmap.insert_sync(i, i).is_ok());
}
drop(reserved);

assert_eq!(hashmap.capacity(), 1024);

```

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

### HashSet - Basic Operations (Rust)

Source: https://docs.rs/scc/3.4.14/index

This example demonstrates basic operations on a `HashSet`, including insertion, retrieval, and removal, both synchronously and asynchronously. It highlights the similarities and differences compared to `HashMap`.

```Rust
use scc::HashSet;

let hashset: HashSet<u64> = HashSet::default();

assert!(hashset.read_sync(&1, |_| true).is_none());
assert!(hashset.insert_sync(1).is_ok());
assert!(hashset.read_sync(&1, |_| true).unwrap());

let future_insert = hashset.insert_async(2);
let future_remove = hashset.remove_async(&1);
```

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

### Synchronous Get Entry (Rust)

Source: https://docs.rs/scc/3.4.14/scc/hash_index/struct.HashIndex_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to synchronously get an `OccupiedEntry` for a key in a HashIndex, enabling in-place modification. The example checks for a non-existent key, inserts a value, and then retrieves and verifies the entry.

```Rust
use scc::HashIndex;

let hashindex: HashIndex<u64, u32> = HashIndex::default();

assert!(hashindex.get_sync(&1).is_none());
assert!(hashindex.insert_sync(1, 10).is_ok());
assert_eq!(*hashindex.get_sync(&1).unwrap().get(), 10);
assert_eq!(*hashindex.get_sync(&1).unwrap(), 10);
```

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

### Example: Using any_async

Source: https://docs.rs/scc/3.4.14/scc/hash_map/struct.Reserve_search=std%3A%3Avec

Illustrates the use of `any_async` to find an entry in a `HashMap` based on a condition applied to its key. It shows how to initiate the search for an entry where the key equals 2.

```rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

let future_entry = hashmap.any_async(|k, _| *k == 2);

```

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

### Stack Length Calculation Example (Rust)

Source: https://docs.rs/scc/3.4.14/scc/stack/struct.Stack

Shows how to get the number of elements currently in the stack using the `len()` method. This method has a time complexity of O(N) as it iterates through all entries.

```rust
use sdd::Stack;

let stack: Stack<usize> = Stack::default();
assert_eq!(stack.len(), 0);

stack.push(7);
stack.push(11);
assert_eq!(stack.len(), 2);

stack.pop();
stack.pop();
assert_eq!(stack.len(), 0);
```

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

### Get Entry for In-Place Manipulation (Sync)

Source: https://docs.rs/scc/3.4.14/scc/hash_index/struct.Reserve_search=

Illustrates synchronous retrieval of an `Entry` for a key, enabling in-place modification of the value within a `HashIndex`. The example demonstrates modifying counters for characters in a string.

```rust
use scc::HashIndex;

let hashindex: HashIndex<char, u32> = HashIndex::default();

for ch in "a short treatise on fungi".chars() {
    unsafe {
        hashindex.entry_sync(ch).and_modify(|counter| *counter += 1).or_insert(1);
    }
}

assert_eq!(hashindex.peek_with(&'s', |_, v| *v), Some(2));
assert_eq!(hashindex.peek_with(&'t', |_, v| *v), Some(3));
assert!(hashindex.peek_with(&'y', |_, v| *v).is_none());

```

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

### Get Async in HashCache (Rust)

Source: https://docs.rs/scc/3.4.14/scc/hash_cache/struct.HashCache

Demonstrates retrieving an `OccupiedEntry` for a key in a HashCache asynchronously. This allows for in-place modification of the value. The example shows initiating a `put_async` and then attempting to `get_async` the entry.

```rust
use scc::HashCache;

let hashcache: HashCache<u64, u32> = HashCache::default();
let future_put = hashcache.put_async(11, 17);
let future_get = hashcache.get_async(&11);
```

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

### Stack Push, Pop, and Peek Example (Rust)

Source: https://docs.rs/scc/3.4.14/scc/stack/struct.Stack

Demonstrates how to push elements onto a stack, pop them off, and peek at the top element without removing it. It uses the `sdd::Stack` and asserts the expected behavior.

```rust
use sdd::Stack;

let stack: Stack<usize> = Stack::default();

assert!(stack.peek_with(|v| v.is_none()));

stack.push(37);
stack.push(3);

assert_eq!(stack.peek_with(|v| **v.unwrap()), 3);
```

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

### Initialize and Test DataBlock and Bucket Operations in Rust

Source: https://docs.rs/scc/3.4.14/src/scc/hash_table/bucket.rs

Demonstrates the initialization of DataBlock and Bucket, along with insertion, LRU tail updates, and assertions for removed bitmap and LRU list values. It also includes logic for handling evicted keys when the bucket is full.

```rust
let data_block: DataBlock<usize, usize, BUCKET_LEN> = DataBlock::new();
let data_block_ptr =
    unsafe { NonNull::new_unchecked(from_ref(&data_block).cast_mut()) };
let bucket: Bucket<usize, usize, DoublyLinkedList, CACHE> = Bucket::new();
let writer = Writer::lock_sync(&bucket).unwrap();
for _ in 0..3 {
    for v in 0..xs {
        let entry_ptr = writer.insert(data_block_ptr, 0, (v, v));
        writer.update_lru_tail(&entry_ptr);
        if v < BUCKET_LEN {
            assert_eq!(
                writer.metadata.removed_bitmap.load(Relaxed) as usize,
                v + 1
            );
        }
        assert_eq!(
            writer.lru_list.read
                (writer.metadata.removed_bitmap.load(Relaxed) - 1)
                .0,
            0
        );
    }

    let mut evicted_key = None;
    if xs >= BUCKET_LEN {
        let evicted = writer.evict_lru_head(data_block_ptr);
        assert!(evicted.is_some());
        evicted_key = evicted.map(|(k, _)| k);
    }
    assert_ne!(writer.metadata.removed_bitmap.load(Relaxed), 0);

    for v in 0..xs {
        let mut entry_ptr = writer.get_entry_ptr(data_block_ptr, &v, 0);
        if entry_ptr.is_valid() {
            let _erased = writer.remove(data_block_ptr, &mut entry_ptr);
        } else {
            assert_eq!(v, evicted_key.unwrap());
        }
    }
    assert_eq!(writer.metadata.removed_bitmap.load(Relaxed), 0);
}
```

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

### Get Sync in HashCache (Rust)

Source: https://docs.rs/scc/3.4.14/scc/hash_cache/struct.HashCache

Demonstrates retrieving an `OccupiedEntry` for a key in a HashCache synchronously. This allows for in-place modification. The example shows checking for a non-existent key, putting a value, retrieving it, and modifying it.

```rust
use scc::HashCache;

let hashcache: HashCache<u64, u32> = HashCache::default();

assert!(hashcache.get_sync(&1).is_none());
assert!(hashcache.put_sync(1, 10).is_ok());
assert_eq!(*hashcache.get_sync(&1).unwrap().get(), 10);

*hashcache.get_sync(&1).unwrap() = 11;
assert_eq!(*hashcache.get_sync(&1).unwrap(), 11);
```

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

### Get Sync Entry for In-Place Manipulation (SCC HashMap)

Source: https://docs.rs/scc/3.4.14/scc/hash_map/struct.HashMap

Demonstrates retrieving a synchronous entry for a key in an SCC `HashMap` for in-place manipulation. It includes an example of counting character occurrences in a string.

```rust
use scc::HashMap;

let hashmap: HashMap<char, u32> = HashMap::default();

for ch in "a short treatise on fungi".chars() {
    hashmap.entry_sync(ch).and_modify(|counter| *counter += 1).or_insert(1);
}

assert_eq!(hashmap.read_sync(&'s', |_, v| *v), Some(2));
assert_eq!(hashmap.read_sync(&'t', |_, v| *v), Some(3));
assert!(hashmap.read_sync(&'y', |_, v| *v).is_none());
```

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

### HashIndex Entry API Update Example (Rust)

Source: https://docs.rs/scc/3.4.14/index

Illustrates how to use the `Entry` API of `HashIndex` to update existing entries. It shows both creating a new version of an entry and modifying an entry in place using `get_sync` and `update` or `get_mut`.

```Rust
use scc::HashIndex;

let hashindex: HashIndex<u64, u32> = HashIndex::default();
assert!(hashindex.insert_sync(1, 1).is_ok());

if let Some(mut o) = hashindex.get_sync(&1) {
    // Create a new version of the entry.
    o.update(2);
};

if let Some(mut o) = hashindex.get_sync(&1) {
    // Update the entry in place.
    unsafe { *o.get_mut() = 3; }
};
```

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

### Stack Initialization

Source: https://docs.rs/scc/3.4.14/scc/stack/struct.Stack_search=

Demonstrates how to create a new, empty Stack.

```APIDOC
## POST /stack/new

### Description
Creates an empty `Stack`.

### Method
POST

### Endpoint
/stack/new

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **stack** (Stack<T>) - The newly created empty stack.

#### Response Example
```json
{
  "example": "Stack<T>"
}
```
```

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

### Begin Synchronous Iteration Over HashIndex Entries

Source: https://docs.rs/scc/3.4.14/scc/hash_index/struct.Reserve_search=

Illustrates starting synchronous iteration over occupied entries in a `HashIndex` with `begin_sync`. The `OccupiedEntry` returned can be used with `next_sync` for mutable iteration. The example shows modifying an entry's value.

```rust
use scc::HashIndex;

let hashindex: HashIndex<u64, u32> = HashIndex::default();

assert!(hashindex.insert_sync(1, 0).is_ok());

let mut first_entry = hashindex.begin_sync().unwrap();
unsafe {
    *first_entry.get_mut() = 2;
}

assert!(first_entry.next_sync().is_none());
assert_eq!(hashindex.peek_with(&1, |_, v| *v), Some(2));

```

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

### Get Capacity Range of SCC HashMap

Source: https://docs.rs/scc/3.4.14/src/scc/hash_map.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The `capacity_range` method returns the current capacity range of the HashMap. This is particularly relevant for HashMaps that might have dynamic resizing capabilities or different internal structures. The default capacity range is provided as an example.

```rust
pub fn capacity_range() -> RangeInclusive<usize> {
    0..=(1_usize << (usize::BITS - 2))
}
```

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

### Example: Using any_sync to Find and Modify Entry

Source: https://docs.rs/scc/3.4.14/scc/hash_map/struct.Reserve_search=std%3A%3Avec

Demonstrates finding an entry in a `HashMap` using `any_sync` based on a predicate and then modifying its value. It inserts two key-value pairs, finds the entry with key 2, asserts its value, and then modifies it.

```rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert_sync(1, 0).is_ok());
assert!(hashmap.insert_sync(2, 3).is_ok());

let mut entry = hashmap.any_sync(|k, _| *k == 2).unwrap();
assert_eq!(*entry.get(), 3);

```

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

### Get HashSet Size

Source: https://docs.rs/scc/3.4.14/src/scc/hash_set.rs_search=

Returns the number of entries in the HashSet. This operation has a time complexity of O(N) as it reads the entire metadata area. It may overcount if old bucket arrays haven't been dropped. Example shows inserting an element and checking the length.

```rust
/// Returns the number of entries in the [`HashSet`].
///
/// It reads the entire metadata area of the bucket array to calculate the number of valid
/// entries, making its time complexity `O(N)`. Furthermore, it may overcount entries if an old
/// bucket array has yet to be dropped.
///
/// # Examples
///
/// ```
/// use scc::HashSet;
///
/// let hashset: HashSet<u64> = HashSet::default();
///
/// assert!(hashset.insert_sync(1).is_ok());
/// assert_eq!(hashset.len(), 1);
/// ```
#[inline]
pub fn len(&self) -> usize {
    self.map.len()
}
```

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

### Example: Using begin_sync for Mutable Iteration

Source: https://docs.rs/scc/3.4.14/scc/hash_map/struct.Reserve_search=std%3A%3Avec

Demonstrates synchronous iteration and modification of `HashMap` entries using `begin_sync` and `OccupiedEntry::get_mut`. It inserts a value, retrieves the first entry, modifies it, and verifies the change.

```rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert_sync(1, 0).is_ok());

let mut first_entry = hashmap.begin_sync().unwrap();
*first_entry.get_mut() = 2;

assert!(first_entry.next_sync().is_none());
assert_eq!(hashmap.read_sync(&1, |_, v| *v), Some(2));

```

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

### Get HashSet Capacity

Source: https://docs.rs/scc/3.4.14/src/scc/hash_set.rs_search=

Returns the current capacity of the HashSet. The capacity indicates the allocated space. For a default HashSet, capacity is 0, but after inserting an element, it becomes 64. A HashSet created with `with_capacity` will have a capacity that is a power of two greater than or equal to the requested value. Example shows different capacity scenarios.

```rust
/// Returns the capacity of the [`HashSet`].
///
/// # Examples
///
/// ```
/// use scc::HashSet;
///
/// let hashset_default: HashSet<u64> = HashSet::default();
/// assert_eq!(hashset_default.capacity(), 0);
///
/// assert!(hashset_default.insert_sync(1).is_ok());
/// assert_eq!(hashset_default.capacity(), 64);
///
/// let hashset: HashSet<u64> = HashSet::with_capacity(1000);
/// assert_eq!(hashset.capacity(), 1024);
/// ```
#[inline]
pub fn capacity(&self) -> usize {
    self.map.capacity()
}
```

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

### HashSet Creation and Capacity

Source: https://docs.rs/scc/3.4.14/scc/hash_set/struct.HashSet

Demonstrates how to create a new HashSet and check its initial capacity.

```APIDOC
## fn default() -> Self

### Description
Creates an empty default `HashSet`.
The default capacity is `0`.

### Method
`default`

### Endpoint
N/A (Constructor)

### Parameters
None

### Request Example
```rust
use scc::HashSet;

let hashset: HashSet<u64> = HashSet::default();
```

### Response
#### Success Response (200)
- **hashset** (HashSet<u64>) - An empty HashSet.

#### Response Example
```rust
let result = hashset.capacity();
assert_eq!(result, 0);
```
```

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

### Get Sync Entry for In-Place Manipulation (Rust)

Source: https://docs.rs/scc/3.4.14/src/scc/hash_cache.rs_search=

Retrieves an Entry for a given key synchronously, enabling in-place modification. This method locks the relevant bucket, searches for the key using its hash, and returns either an OccupiedEntry or a VacantEntry based on whether the key exists. Example demonstrates modifying counts for characters in a string.

```rust
pub fn entry_sync(&self, key: K) -> Entry<'_, K, V, H> {
        let hash = self.hash(&key);
        let locked_bucket = self.writer_sync(hash);
        let entry_ptr = locked_bucket.search(&key, hash);
        if entry_ptr.is_valid() {
            Entry::Occupied(OccupiedEntry {
                hashcache: self,
                locked_bucket,
                entry_ptr,
            })
        } else {
            let vacant_entry = VacantEntry {
                hashcache: self,
                key,
                hash,
                locked_bucket,
            };
            Entry::Vacant(vacant_entry)
        }
    }
```

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

### Get Bucket Index for Key

Source: https://docs.rs/scc/3.4.14/src/scc/hash_set.rs_search=

Returns the index of the bucket that may contain the given key. The number of buckets is determined by dividing the capacity by 32. This method is useful for understanding key distribution within the HashSet's internal structure. Example shows calculating the bucket index for a key and verifying it's within bounds.

```rust
/// Returns the index of the bucket that may contain the key.
///
/// The method returns the index of the bucket associated with the key. The number of buckets
/// can be calculated by dividing the capacity by `32`.
///
/// # Examples
///
/// ```
/// use scc::HashSet;
///
/// let hashset: HashSet<u64> = HashSet::with_capacity(1024);
///
/// let bucket_index = hashset.bucket_index(&11);
/// assert!(bucket_index < hashset.capacity() / 32);
/// ```
#[inline]
pub fn bucket_index<Q>(&self, key: &Q) -> usize
where
    Q: Equivalent<K> + Hash + ?Sized,
{
    self.map.bucket_index(key)
}
```

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

### HashMap Initialization

Source: https://docs.rs/scc/3.4.14/scc/hash_map/struct.HashMap_search=std%3A%3Avec

Demonstrates how to create a new HashMap using default settings or with a specified initial capacity.

```APIDOC
## HashMap Initialization

### Description
Provides methods to create a new `HashMap` instance. You can create an empty `HashMap` with default settings or initialize it with a specific capacity.

### Methods

#### `new()`
Creates an empty default `HashMap`.

##### Example
```rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::new();
assert_eq!(hashmap.capacity(), 0);
```

#### `with_capacity(capacity: usize)`
Creates an empty `HashMap` with the specified capacity. The actual capacity will be equal to or greater than the provided value, unless it exceeds system limits.

##### Example
```rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::with_capacity(1000);
assert_eq!(hashmap.capacity(), 1024);
```

#### `default()`
Creates an empty default `HashMap`. This is equivalent to calling `HashMap::new()`.

##### Example
```rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();
assert_eq!(hashmap.capacity(), 0);
```
```

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

### Get HashSet Capacity Range

Source: https://docs.rs/scc/3.4.14/src/scc/hash_set.rs_search=

Returns the current capacity range of the HashSet. This range indicates the minimum and maximum number of elements the set can hold without rehashing. For a default set, the range is typically large, related to `usize::BITS`. Reserving capacity adjusts this range. Example shows the default range and the range after reserving.

```rust
/// Returns the current capacity range of the [`HashSet`].
///
/// # Examples
///
/// ```
/// use scc::HashSet;
///
/// let hashset: HashSet<u64> = HashSet::default();
///
/// assert_eq!(hashset.capacity_range(), 0..=(1_usize << (usize::BITS - 2)));
///
/// let reserved = hashset.reserve(1000);
/// assert_eq!(hashset.capacity_range(), 1000..=(1_usize << (usize::BITS - 2)));
/// ```
#[inline]
pub fn capacity_range(&self) -> RangeInclusive<usize> {
    self.map.capacity_range()
}
```

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

### Rust: Basic Queue Operations (Push, Pop, Length)

Source: https://docs.rs/scc/3.4.14/scc/queue/struct.Queue

Demonstrates the fundamental operations of a `Queue` in Rust, including initializing a queue, adding elements using `push`, removing elements using `pop`, and checking the current number of elements with `len`. This example assumes the `sdd::Queue` type is available.

```rust
use sdd::Queue;

let queue: Queue<usize> = Queue::default();
assert_eq!(queue.len(), 0);

queue.push(7);
queue.push(11);
assert_eq!(queue.len(), 2);

queue.pop();
queue.pop();
assert_eq!(queue.len(), 0);
```

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

### Get Sync

Source: https://docs.rs/scc/3.4.14/scc/hash_cache/struct.HashCache_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Gets an `OccupiedEntry` corresponding to the key for in-place modification. This is the synchronous version of the get operation.

```APIDOC
## GET /hashcache/get_sync

### Description
Gets an `OccupiedEntry` corresponding to the key for in-place modification. `OccupiedEntry` exclusively owns the entry, preventing others from gaining access to it: use `read_sync` if read-only access is sufficient. Returns `None` if the key does not exist.

### Method
GET

### Endpoint
`/hashcache/get_sync`

### Parameters
#### Query Parameters
- **key** (Q) - Required - The key to retrieve from the HashCache.

### Response
#### Success Response (200)
- **Option<OccupiedEntry<'_, K, V, H>>** - An Option containing an `OccupiedEntry` if the key exists, allowing for in-place modification. Returns `None` if the key does not exist.

#### Response Example
```json
{
  "key": "some_key",
  "value": "some_value"
}
```

```json
null
```
```

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

### Get Async

Source: https://docs.rs/scc/3.4.14/scc/hash_cache/struct.HashCache_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Asynchronously gets an `OccupiedEntry` corresponding to the key for in-place modification. This is the asynchronous version of the get operation.

```APIDOC
## GET /hashcache/get_async

### Description
Asynchronously gets an `OccupiedEntry` corresponding to the key for in-place modification. `OccupiedEntry` exclusively owns the entry, preventing others from gaining access to it: use `read_async` if read-only access is sufficient. Returns `None` if the key does not exist.

### Method
GET

### Endpoint
`/hashcache/get_async`

### Parameters
#### Query Parameters
- **key** (Q) - Required - The key to retrieve from the HashCache.

### Response
#### Success Response (200)
- **Option<OccupiedEntry<'_, K, V, H>>** - An Option containing an `OccupiedEntry` if the key exists, allowing for in-place modification. Returns `None` if the key does not exist.

#### Response Example
```json
{
  "key": "some_key",
  "value": "some_value"
}
```

```json
null
```
```

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

### Rust Range Iterator Start Method

Source: https://docs.rs/scc/3.4.14/src/scc/tree_index.rs_search=

Implements the `start` method for the `Range` iterator to find the first element within the specified bounds. It loads the root node, determines the starting leaf iterator based on the range's start bound, and handles cases where the start bound is unbounded or requires approximate searching.

```rust
impl<'g, K, V, Q, R> Range<'_, 'g, K, V, Q, R>
where
    K: 'static + Clone + Ord,
    V: 'static,
    Q: Comparable<K> + ?Sized,
    R: RangeBounds<Q>,
{
    fn start(&mut self) -> Option<(&'g K, &'g V)> {
        // Start iteration.
        let root_ptr = self.root.load(Acquire, self.guard);
        if let Some(root) = root_ptr.as_ref() {
            let mut leaf_iter = match self.bounds.start_bound() {
                Excluded(k) | Included(k) => root.approximate::<_, true>(k, self.guard),
                Unbounded => None,
            };
            if leaf_iter.is_none() {
                if let Some(mut iter) = root.min(self.guard) {
                    iter.next();
                    leaf_iter.replace(iter);
                }
            }

```

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

### HashMap - Basic Operations (Rust)

Source: https://docs.rs/scc/3.4.14/index

This snippet demonstrates basic operations on a `HashMap`, including insertion, retrieval, update, and removal, both synchronously and asynchronously. It showcases the use of `insert_sync`, `upsert_sync`, `update_sync`, `read_sync`, `remove_sync`, `insert_async`, and `remove_async` methods.

```Rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert_sync(1, 0).is_ok());
assert!(hashmap.insert_sync(1, 1).is_err());
assert_eq!(hashmap.upsert_sync(1, 1).unwrap(), 0);
assert_eq!(hashmap.update_sync(&1, |_, v| { *v = 3; *v }).unwrap(), 3);
assert_eq!(hashmap.read_sync(&1, |_, v| *v).unwrap(), 3);
assert_eq!(hashmap.remove_sync(&1).unwrap(), (1, 3));

hashmap.entry_sync(7).or_insert(17);
assert_eq!(hashmap.read_sync(&7, |_, v| *v).unwrap(), 17);

let future_insert = hashmap.insert_async(2, 1);
let future_remove = hashmap.remove_async(&1);
```

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

### Queue Initialization

Source: https://docs.rs/scc/3.4.14/scc/queue/struct.Queue

Methods for creating and initializing a new Queue instance.

```APIDOC
## POST /queue

### Description
Creates a new, empty Queue.

### Method
POST

### Endpoint
/queue

### Parameters
#### Query Parameters
- **T** (type) - Required - The type of elements the queue will hold.

### Request Body
None

### Response
#### Success Response (200)
- **Queue<T>** (object) - A new, empty Queue instance.

#### Response Example
```json
{
  "queue": "new_empty_queue_instance"
}
```

## GET /queue/new

### Description
Creates a new, empty Queue instance using the `new` constructor.

### Method
GET

### Endpoint
/queue/new

### Parameters
None

### Request Body
None

### Response
#### Success Response (200)
- **Queue<T>** (object) - A new, empty Queue instance.

#### Response Example
```json
{
  "queue": "new_empty_queue_instance"
}
```
```

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

### Start Method for Range in Rust

Source: https://docs.rs/scc/3.4.14/src/scc/tree_index.rs

Implements the `start` method for the `Range` struct in Rust. This method is responsible for finding the starting point of the iteration within the specified range, handling different bound types and initializing the leaf iterator.

```rust
impl<'g, K, V, Q, R>
    Range<'_, 'g, K, V, Q, R>
where
    K: 'static + Clone + Ord,
    V: 'static,
    Q: Comparable<K> + ?Sized,
    R: RangeBounds<Q>,
{
    fn start(&mut self) -> Option<(&'g K, &'g V)> {
        // Start iteration.
        let root_ptr = self.root.load(Acquire, self.guard);
        if let Some(root) = root_ptr.as_ref() {
            let mut leaf_iter = match self.bounds.start_bound() {
                Excluded(k) | Included(k) => root.approximate::<_, true>(k, self.guard),
                Unbounded => None,
            };
            if leaf_iter.is_none() {
                if let Some(mut iter) = root.min(self.guard) {
                    iter.next();

```

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

### Example: Push and Peek on SCC Queue

Source: https://docs.rs/scc/3.4.14/scc/struct.Queue_search=std%3A%3Avec

Demonstrates pushing an integer value into a `Queue` and then peeking at it using a `Guard`. It asserts that the peeked value matches the pushed value.

```rust
use sdd::Queue;
use sdd::Guard;

let queue: Queue<usize> = Queue::default();

queue.push(37);
queue.push(3);

assert_eq!(**queue.peek(&Guard::new()).unwrap(), 37);
```

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

### Rust LinkedList delete_self Example

Source: https://docs.rs/scc/3.4.14/scc/trait.LinkedList_search=

Provides an example of using the `delete_self` method to mark a `LinkedList` node as deleted. It returns `false` if the node is already marked as deleted. The example also shows how this affects the `next_ptr`.

```rust
use std::sync::atomic::Ordering::Relaxed;

use sdd::{AtomicShared, Guard, LinkedList, Shared};

#[derive(Default)]
struct L(AtomicShared<L>, usize);
impl LinkedList for L {
    fn link_ref(&self) -> &AtomicShared<L> {
        &self.0
    }
}

let guard = Guard::new();

let head: L = L::default();
let tail: Shared<L> = Shared::new(L::default());
assert!(head.push_back(tail.clone(), false, Relaxed, &guard).is_ok());

tail.delete_self(Relaxed);
assert!(head.next_ptr(Relaxed, &guard).as_ref().is_none());
```

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

### Rust Range Query Start Method

Source: https://docs.rs/scc/3.4.14/src/scc/tree_index.rs_search=std%3A%3Avec

Determines the starting point for a range query. It loads the root node and, based on the start bound, finds an approximate leaf iterator or the minimum element. Dependencies include `Acquire`, `Comparable`, and `RangeBounds`.

```rust
impl<'g, K, V, Q, R>
where
    K: 'static + Clone + Ord,
    V: 'static,
    Q: Comparable<K> + ?Sized,
    R: RangeBounds<Q>,
{
    fn start(&mut self) -> Option<(&'g K, &'g V)> {
        // Start iteration.
        let root_ptr = self.root.load(Acquire, self.guard);
        if let Some(root) = root_ptr.as_ref() {
            let mut leaf_iter = match self.bounds.start_bound() {
                Excluded(k) | Included(k) => root.approximate::<_, true>(k, self.guard),
                Unbounded => None,
            };
            if leaf_iter.is_none() {
                if let Some(mut iter) = root.min(self.guard) {
                    iter.next();
                    leaf_iter.replace(iter);
                }
            }
            // ... rest of the logic to return the first element within the range
        }
        None
    }
}
```

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

### Stack Initialization

Source: https://docs.rs/scc/3.4.14/scc/stack/struct.Stack_search=std%3A%3Avec

Provides methods to create new Stack instances.

```APIDOC
## Stack Initialization

### Description
Methods for creating and initializing a new `Stack`.

### Methods

- `new()`: Creates an empty `Stack`.
- `default()`: Creates an empty `Stack` using the default implementation.

### Request Example

```rust
use sdd::Stack;

// Using new()
let stack_new: Stack<usize> = Stack::new();

// Using default()
let stack_default: Stack<usize> = Stack::default();
```

### Response

#### Success Response (200)

- **Stack<T>** (Stack) - A new, empty stack instance.

#### Response Example

```json
{
  "stack_instance": "<Stack<T>>"
}
```
```

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

### GET /hashcache/sync/get

Source: https://docs.rs/scc/3.4.14/src/scc/hash_cache.rs_search=

Synchronously gets an OccupiedEntry corresponding to the key for in-place modification. Returns None if the key does not exist.

```APIDOC
## GET /hashcache/sync/get

### Description
Synchronously retrieves an `OccupiedEntry` for in-place modification. This provides exclusive ownership of the entry. Returns `None` if the key is not found.

### Method
GET

### Endpoint
`/hashcache/sync/get`

### Query Parameters
- **key** (Q) - Required - The key to search for.

### Response
#### Success Response (200)
- **OccupiedEntry** (OccupiedEntry<'_, K, V, H>) - An entry that allows in-place modification.

#### Response Example
```json
{
  "entry": "OccupiedEntry object"
}
```

#### Error Response (404)
- **None** - Returned when the key does not exist.
```

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

### HashMap Constructors

Source: https://docs.rs/scc/3.4.14/scc/hash_map/struct.HashMap_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides documentation for creating new HashMap instances, including default and capacity-initialized HashMaps.

```APIDOC
## HashMap Constructors

### `new()`

Creates an empty default `HashMap`.

#### Method

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

#### Example

```rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::new();
assert_eq!(hashmap.capacity(), 0);
```

### `with_capacity(capacity: usize)`

Creates an empty `HashMap` with the specified capacity.

The actual capacity is equal to or greater than `capacity` unless it is greater than `1 << (usize::BITS - 1)`.

#### Method

```rust
pub fn with_capacity(capacity: usize) -> Self
```

#### Parameters

*   **capacity** (usize) - The desired initial capacity for the HashMap.

#### Example

```rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::with_capacity(1000);
assert_eq!(hashmap.capacity(), 1024);
```

### `default()`

Creates an empty default `HashMap`.

#### Method

```rust
pub fn default() -> Self
```

#### Example

```rust
use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();
assert_eq!(hashmap.capacity(), 0);
```
```

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

### GET /hashcache/async/get

Source: https://docs.rs/scc/3.4.14/src/scc/hash_cache.rs_search=

Asynchronously gets an OccupiedEntry corresponding to the key for in-place modification. Returns None if the key does not exist.

```APIDOC
## GET /hashcache/async/get

### Description
Asynchronously retrieves an `OccupiedEntry` for in-place modification. This provides exclusive ownership of the entry. Returns `None` if the key is not found.

### Method
GET

### Endpoint
`/hashcache/async/get`

### Query Parameters
- **key** (Q) - Required - The key to search for.

### Response
#### Success Response (200)
- **OccupiedEntry** (OccupiedEntry<'_, K, V, H>) - An entry that allows in-place modification.

#### Response Example
```json
{
  "entry": "OccupiedEntry object"
}
```

#### Error Response (404)
- **None** - Returned when the key does not exist.
```

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

### HashSet Default Implementation

Source: https://docs.rs/scc/3.4.14/scc/hash_set/struct.HashSet_search=std%3A%3Avec

Demonstrates how to create a new HashSet using its default implementation and check its initial capacity.

```APIDOC
## Default for HashSet<K, H>

### Description
Creates an empty default `HashSet`.
The default capacity is `0`.

### Method
`default()`

### Parameters
None

### Request Example
```rust
use scc::HashSet;

let hashset: HashSet<u64> = HashSet::default();

let result = hashset.capacity();
assert_eq!(result, 0);
```

### Response
#### Success Response (200)
- **HashSet<K, H>** (HashSet) - An empty HashSet instance.

#### Response Example
```rust
// No direct response body, but an instance of HashSet is created.
```
```

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

### Get Occupied Entry (Sync)

Source: https://docs.rs/scc/3.4.14/scc/hash_map/struct.Reserve_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Synchronously gets an OccupiedEntry for in-place modification. Returns None if the key does not exist.

```APIDOC
## POST /get_sync

### Description
Synchronously gets an `OccupiedEntry` corresponding to the key for in-place modification. `OccupiedEntry` exclusively owns the entry, preventing others from gaining access to it: use `read_sync` if read-only access is sufficient. Returns `None` if the key does not exist.

### Method
POST

### Endpoint
`/get_sync`

### Parameters
#### Query Parameters
- **key** (Q) - Required - The key to get the entry for.

### Request Body
This method does not have a request body.

### Response
#### Success Response (200)
- **Option<OccupiedEntry<'_, K, V, H>>** - An `OccupiedEntry` if the key exists, otherwise None.

#### Response Example
```json
{
  "occupied_entry": "..."
}
```
```json
{
  "occupied_entry": null
}
```
```

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

### Rust: Basic Queue Operations (Push and Pop)

Source: https://docs.rs/scc/3.4.14/scc/struct.Queue_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates the fundamental operations of adding elements to a queue using `push` and removing them using `pop`. It shows how the queue's length changes with these operations and verifies its emptiness after all elements are removed. This example uses the `sdd::Queue` type.

```rust
use sdd::Queue;

let mut queue: Queue<usize> = Queue::default();
assert_eq!(queue.len(), 0);

queue.push(7);
queue.push(11);
assert_eq!(queue.len(), 2);

queue.pop();
queue.pop();
assert_eq!(queue.len(), 0);
```

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

### Sync Get Occupied Entry

Source: https://docs.rs/scc/3.4.14/src/scc/hash_cache.rs_search=std%3A%3Avec

Gets an OccupiedEntry corresponding to the key for in-place modification. Returns None if the key does not exist.

```APIDOC
## GET /hashcache/sync/{key}

### Description
Retrieves a synchronous `OccupiedEntry` for in-place modification of a key-value pair. This provides exclusive ownership of the entry.

### Method
GET

### Endpoint
`/hashcache/sync/{key}`

### Parameters
#### Path Parameters
- **key** (Q) - Required - The key to look up in the cache.

### Response
#### Success Response (200)
- **OccupiedEntry** - A synchronous entry that allows in-place modification of the value.

#### Error Response (404)
- **None** - Returned if the key does not exist in the cache.
```