### Vector::get, Vector::get_mut, and indexing

Source: https://context7.com/jneem/imbl/llms.txt

Provides element access via `get(index)` for immutable access, `get_mut(index)` for mutable access (triggering copy-on-write), and indexing `[]` for direct access. Panics on out-of-bounds.

```APIDOC
## `Vector::get` / `Vector::get_mut` / indexing — Element access

`get(index)` returns `Option<&A>`; `get_mut(index)` returns `Option<&mut A>` and triggers a copy-on-write if the node is shared. The `Index` / `IndexMut` operator traits panic on out-of-bounds access.

```rust
use imbl::vector;

let mut v = vector!["Alice", "Bob", "Carol"];

// Immutable access
assert_eq!(Some(&"Bob"), v.get(1));
assert_eq!(None, v.get(99));
assert_eq!("Carol", v[2]);

// Mutable in-place update (copy-on-write)
*v.get_mut(0).unwrap() = "Dave";
assert_eq!("Dave", v[0]);

// Functional update — returns new vector, original unchanged
let v2 = v.clone();
let v3 = v2.update(1, "Eve");
assert_eq!("Bob", v2[1]);  // original untouched
assert_eq!("Eve", v3[1]);  // new version has the change
```
```

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

### HashMap Mutation and Lookup

Source: https://context7.com/jneem/imbl/llms.txt

Perform O(log n) operations using `insert()` to add or update entries (returning the old value), `remove()` to delete entries (returning the removed value), and `get()` for lookups. `update()` provides a functional alternative.

```rust
use imbl::{hashmap, HashMap};

let mut map: HashMap<&str, i32> = hashmap! {
    "a" => 1,
    "b" => 2,
};

// Insert and update
let old = map.insert("a", 10);
assert_eq!(Some(1), old);
assert_eq!(Some(&10), map.get("a"));
```

```rust
// Remove
assert_eq!(Some(10), map.remove("a"));
assert_eq!(None, map.get("a"));
```

```rust
// Functional style — returns new map, original unchanged
let m2 = map.update("c", 3);
assert_eq!(None, map.get("c"));   // original untouched
assert_eq!(Some(&3), m2.get("c")); // new version has the value
```

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

### Access Vector elements using get, get_mut, and indexing

Source: https://context7.com/jneem/imbl/llms.txt

Access elements immutably with `get(index)` (returns `Option<&A>`) or by using the `Index` operator (`[]`), which panics on out-of-bounds. `get_mut(index)` provides mutable access, triggering copy-on-write if the node is shared.

```rust
use imbl::vector;

let mut v = vector!["Alice", "Bob", "Carol"];

// Immutable access
assert_eq!(Some(&"Bob"), v.get(1));
assert_eq!(None, v.get(99));
assert_eq!("Carol", v[2]);

// Mutable in-place update (copy-on-write)
*v.get_mut(0).unwrap() = "Dave";
assert_eq!("Dave", v[0]);

// Functional update — returns new vector, original unchanged
let v2 = v.clone();
let v3 = v2.update(1, "Eve");
assert_eq!("Bob", v2[1]);  // original untouched
assert_eq!("Eve", v3[1]);  // new version has the change
```

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

### Vector Filtering and Slicing

Source: https://context7.com/jneem/imbl/llms.txt

Use `retain()` to keep elements matching a predicate, `skip()` to remove leading elements, `take()` to get leading elements, and `truncate()` to shorten the vector in place.

```rust
use imbl::vector;

let mut v = vector![1, 2, 3, 4, 5, 6];
v.retain(|x| x % 2 == 0);
assert_eq!(vector![2, 4, 6], v);
```

```rust
let src = vector![10, 20, 30, 40, 50];
assert_eq!(vector![30, 40, 50], src.skip(2));
assert_eq!(vector![10, 20, 30], src.take(3));
```

```rust
let mut t = vector![1, 2, 3, 4, 5];
t.truncate(3);
assert_eq!(vector![1, 2, 3], t);
```

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

### Vector Initialization and Manipulation Test Case

Source: https://github.com/jneem/imbl/blob/main/proptest-regressions/tests/vector.txt

Demonstrates vector initialization from an array, appending another vector, splitting, popping, pushing, and further manipulations. This case is useful for testing the interaction between different vector operations.

```rust
cc bae4a6aa243531a345cb36883fda4aebc84848fffe12d051df4e24ff22af3689 # shrinks to actions = let mut vec = Vector::new(); let mut vec_new = Vector::from([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]); vec_new.append(vec); vec = vec_new; vec = vec.split_off(6); vec.pop_front(); vec.pop_front(); vec.push_front(0); vec.pop_front(); vec.push_front(0); vec.append(Vector::from([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])); vec.split_off(141); let mut vec_new = Vector::from([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]); vec_new.append(vec); vec = vec_new; vec.insert(41, 0); vec.pop_front(); vec.pop_front(); vec = vec.split_off(5); vec.pop_front(); vec.append(Vector::from([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])); vec.append(Vector::from([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1])); vec.push_front(0); vec.push_front(0); let mut vec_new = Vector::from([0]); vec_new.append(vec); vec = vec_new; 
```

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

### Add elements to a Vector using push_front and push_back

Source: https://context7.com/jneem/imbl/llms.txt

Efficiently add elements to the beginning or end of a vector. `push_back` appends to the tail, and `push_front` prepends to the head, both with amortized O(1) complexity. Symmetrical `pop_back` and `pop_front` operations are also available.

```rust
use imbl::vector;

let mut v = vector![2, 3, 4];
v.push_back(5);
v.push_front(1);
assert_eq!(vector![1, 2, 3, 4, 5], v);

// pop symmetrically
assert_eq!(Some(5), v.pop_back());
assert_eq!(Some(1), v.pop_front());
assert_eq!(vector![2, 3, 4], v);
```

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

### Construct HashMap with `hashmap!` Macro

Source: https://context7.com/jneem/imbl/llms.txt

Use the `hashmap!` macro for concise literal construction of `HashMap` instances. Supports empty map creation.

```rust
use imbl::{hashmap, HashMap};

let map: HashMap<i32, &str> = hashmap! {
    1 => "one",
    2 => "two",
    3 => "three",
};
assert_eq!(3, map.len());
assert_eq!(Some(&"two"), map.get(&2));
```

```rust
// Empty map
let empty: HashMap<String, i32> = hashmap! {};
assert!(empty.is_empty());
```

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

### Vector Split and Comparison

Source: https://github.com/jneem/imbl/blob/main/proptest-regressions/tests/vector.txt

Initializes a vector, performs a series of operations including splitting, and then compares the resulting vector with an expected vector. This is a core regression test.

```rust
let mut vec_new = Vector::from(vec![89, 252, 187, 201, 31, 229, 16, 211, 172, 223, 209, 123, 120, 100, 91, 241, 223, 42, 71, 212, 42, 113, 211, 128, 54, 142]); // size 26
vec_new.append(vec);
vec = vec_new; // len = 282
vec = vec.split_off(188); // len = 94
let expected = vec![233, 141, 182, 243, 42, 102, 166, 184, 248, 127, 120, 88, 246, 204, 127, 214, 30, 201, 205, 115, 28, 204, 26, 17, 67, 228, 44, 158, 15, 79, 141, 86, 101, 148, 76, 44, 216, 65, 127, 142, 241, 16, 254, 11, 153, 252, 3, 104, 61, 225, 73, 56, 149, 247, 142, 67, 4, 24, 96, 169, 234, 215, 227, 30, 84, 45, 209, 194, 101, 202, 247, 108, 248, 86, 224, 255, 187, 50, 123, 93, 110, 63, 83, 122, 101, 48, 38, 228, 25, 146, 89, 230, 224, 101];
assert_eq!(Vector::from(expected), vec);
```

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

### Vector Initialization and Appending

Source: https://github.com/jneem/imbl/blob/main/proptest-regressions/tests/vector.txt

Initializes a vector and appends another vector to it. This demonstrates basic vector construction and concatenation.

```rust
let mut vec = Vector::new();
let mut vec_new = Vector::from(vec![0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]); // size 70
vec_new.append(vec);
vec = vec_new; // len = 70
vec.append(Vector::from(vec![0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 53, 59, 108, 189, 95, 24, 92, 116, 211, 64, 195, 2, 58, 198, 130, 44, 163, 180, 50, 176, 78, 24, 2, 180, 91, 132, 176, 205, 155, 65, 228, 182, 175, 100, 204, 222])); // size 61 // len = 131
```

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

### HashMap Entry API for In-Place Manipulation

Source: https://context7.com/jneem/imbl/llms.txt

Use the `entry()` API for efficient conditional insertion or modification of HashMap entries in O(log n), mirroring `std::collections::HashMap`'s behavior.

```rust
use imbl::{hashmap, HashMap};

let mut scores: HashMap<&str, u32> = hashmap! {};

// Insert if absent
scores.entry("Alice").or_insert(0);
assert_eq!(Some(&0), scores.get("Alice"));
```

```rust
// Modify if present
*scores.entry("Alice").or_insert(0) += 10;
assert_eq!(Some(&10), scores.get("Alice"));
```

```rust
// Complex pattern: count word frequencies
let words = vec!["hello", "world", "hello", "rust"];
let mut freq: HashMap<&str, u32> = hashmap! {};
for w in words {
    *freq.entry(w).or_insert(0) += 1;
}
assert_eq!(Some(&2), freq.get("hello"));
assert_eq!(Some(&1), freq.get("rust"));
```

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

### Vector Push, Pop, and Push Front Operations

Source: https://github.com/jneem/imbl/blob/main/proptest-regressions/tests/vector.txt

Appends an element, removes the first element, and adds an element to the front. This tests the dynamic resizing and boundary modifications of the vector.

```rust
vec.push_back(31); // len = 13
vec.pop_front(); // len = 12
vec.push_front(96); // len = 13
vec.push_back(77); // len = 14
```

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

### Create a Vector using Vector::new or Vector::unit

Source: https://context7.com/jneem/imbl/llms.txt

Initialize an empty vector with `Vector::new()` or a single-element vector with `Vector::unit(value)`. Vectors are stored inline for small sizes and heap-allocate when exceeding the chunk size.

```rust
use imbl::{vector, Vector};

let empty: Vector<i32> = Vector::new();
assert!(empty.is_empty());

let single = Vector::unit(42_i32);
assert_eq!(1, single.len());
assert_eq!(Some(&42), single.get(0));

// Collect from an iterator
let from_iter: Vector<i32> = (0..10).collect();
assert_eq!(10, from_iter.len());
```

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

### Split a Vector using split_at, split_off, or slice

Source: https://context7.com/jneem/imbl/llms.txt

Divide a vector into parts using `split_at` (consumes and returns two halves), `split_off` (in-place, returns the right half), or `slice` (extracts a sub-range and rejoins the remainder). All operations run in O(log n) time.

```rust
use imbl::vector;

let v = vector![1, 2, 3, 4, 5, 6];
let (left, right) = v.split_at(3);
assert_eq!(vector![1, 2, 3], left);
assert_eq!(vector![4, 5, 6], right);

let mut v2 = vector![10, 20, 30, 40, 50];
let tail = v2.split_off(2);
assert_eq!(vector![10, 20], v2);
assert_eq!(vector![30, 40, 50], tail);

// slice removes a range and rejoins
let mut v3 = vector![1, 2, 3, 4, 5];
let middle = v3.slice(1..4);
assert_eq!(vector![1, 5], v3);     // remainder
assert_eq!(vector![2, 3, 4], middle); // extracted slice
```

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

### HashMap In-place Mutation

Source: https://context7.com/jneem/imbl/llms.txt

Provides methods for in-place mutation of HashMaps using a copy-on-write strategy, cloning only the necessary nodes. Includes `get_mut`, `retain`, and `iter_mut`.

```APIDOC
## `HashMap::get_mut` / `HashMap::retain` / `HashMap::iter_mut` — In-place mutation

Copy-on-write mutation: only the nodes that need to change are cloned.

### Example
```rust
use imbl::hashmap;

let mut map = hashmap! { "x" => 1_i32, "y" => 2, "z" => 3 };

// Mutate in place
if let Some(v) = map.get_mut("x") {
    *v += 100;
}
assert_eq!(Some(&101), map.get("x"));

// Retain only entries satisfying a predicate
map.retain(|_k, v| *v > 2);
assert_eq!(1, map.len());
assert!(map.contains_key("z"));

// Mutable iteration
let mut m2 = hashmap! { "a" => 1_i32, "b" => 2, "c" => 3 };
for (_k, v) in m2.iter_mut() {
    *v *= 2;
}
assert_eq!(Some(&6), m2.get("c"));
```
```

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

### HashMap Entry API

Source: https://context7.com/jneem/imbl/llms.txt

The entry API mirrors `std::collections::HashMap` and allows efficient conditional insertion or modification in O(log n).

```APIDOC
## `HashMap::entry` — Entry API for in-place manipulation

The entry API mirrors `std::collections::HashMap` and allows efficient conditional insertion or modification in O(log n).

```rust
use imbl::{hashmap, HashMap};

let mut scores: HashMap<&str, u32> = hashmap! {};

// Insert if absent
scores.entry("Alice").or_insert(0);
assert_eq!(Some(&0), scores.get("Alice"));

// Modify if present
*scores.entry("Alice").or_insert(0) += 10;
assert_eq!(Some(&10), scores.get("Alice"));

// Complex pattern: count word frequencies
let words = vec!["hello", "world", "hello", "rust"];
let mut freq: HashMap<&str, u32> = hashmap! {};
for w in words {
    *freq.entry(w).or_insert(0) += 1;
}
assert_eq!(Some(&2), freq.get("hello"));
assert_eq!(Some(&1), freq.get("rust"));
```
```

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

### Vector Efficient Random-Access Cursor

Source: https://context7.com/jneem/imbl/llms.txt

`Focus` and `FocusMut` provide amortised O(1) sequential access to arbitrary indices by caching the last-visited tree node. Useful for high-performance loops that touch many indices.

```APIDOC
## `Vector::focus` / `Vector::focus_mut` — Efficient random-access cursor

`Focus` and `FocusMut` provide amortised O(1) sequential access to arbitrary indices by caching the last-visited tree node. Useful for high-performance loops that touch many indices.

```rust
use imbl::vector;

let v = vector![0i64, 1, 2, 3, 4, 5];
let mut focus = v.focus();
let sum: i64 = (0..v.len()).map(|i| *focus.index(i)).sum();
assert_eq!(15, sum);

// Mutable focus with split for parallel-style processing
let mut v2 = vector![1i32, 2, 3, 4, 5, 6];
{
    let mut fm = v2.focus_mut();
    let (mut left, mut right) = fm.split_at(3);
    for x in &mut left  { *x *= 10; }
    for x in &mut right { *x *= 100; }
}
assert_eq!(vector![10, 20, 30, 400, 500, 600], v2);
```
```

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

### Efficient Random-Access with Vector Focus

Source: https://context7.com/jneem/imbl/llms.txt

Utilize `focus()` and `focus_mut()` for amortized O(1) sequential access to vector elements by caching tree nodes. `focus_mut()` supports splitting for parallel-style processing.

```rust
use imbl::vector;

let v = vector![0i64, 1, 2, 3, 4, 5];
let mut focus = v.focus();
let sum: i64 = (0..v.len()).map(|i| *focus.index(i)).sum();
assert_eq!(15, sum);
```

```rust
// Mutable focus with split for parallel-style processing
let mut v2 = vector![1i32, 2, 3, 4, 5, 6];
{
    let mut fm = v2.focus_mut();
    let (mut left, mut right) = fm.split_at(3);
    for x in &mut left  { *x *= 10; }
    for x in &mut right { *x *= 100; }
}
assert_eq!(vector![10, 20, 30, 400, 500, 600], v2);
```

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

### HashMap Macro

Source: https://context7.com/jneem/imbl/llms.txt

Construct a `HashMap` literal using the `hashmap!` macro.

```APIDOC
## `hashmap!` macro — Construct a `HashMap` literal

```rust
use imbl::{hashmap, HashMap};

let map: HashMap<i32, &str> = hashmap! {
    1 => "one",
    2 => "two",
    3 => "three",
};
assert_eq!(3, map.len());
assert_eq!(Some(&"two"), map.get(&2));

// Empty map
let empty: HashMap<String, i32> = hashmap! {};
assert!(empty.is_empty());
```
```

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

### Serde Serialization and Deserialization

Source: https://context7.com/jneem/imbl/llms.txt

Enable the `serde` feature in `Cargo.toml` to use `Serialize` and `Deserialize` for all `imbl` collection types. This allows transparent conversion to and from formats like JSON.

```toml
# Cargo.toml
[dependencies]
imbl = { version = "7", features = ["serde"] }
serde_json = "1"
```

```rust
use imbl::{hashmap, ordmap, vector, HashMap, OrdMap, Vector};
use serde_json;

let map: HashMap<String, i32> = hashmap! {
    "x".to_string() => 1,
    "y".to_string() => 2,
};
let json = serde_json::to_string(&map).unwrap();
let back: HashMap<String, i32> = serde_json::from_str(&json).unwrap();
assert_eq!(map, back);

let v: Vector<i32> = vector![10, 20, 30];
let json_v = serde_json::to_string(&v).unwrap();
assert_eq!("[10,20,30]", json_v);

let om: OrdMap<i32, &str> = ordmap! { 1 => "a", 2 => "b" };
let json_om = serde_json::to_string(&om).unwrap();
let back_om: OrdMap<i32, String> = serde_json::from_str(&json_om).unwrap();
assert_eq!(2, back_om.len());
```

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

### Vector::push_front and Vector::push_back

Source: https://context7.com/jneem/imbl/llms.txt

Adds elements to the front or back of a Vector. Both operations are amortized O(1). Includes symmetric pop operations.

```APIDOC
## `Vector::push_front` / `Vector::push_back` — Add elements

Both operations are amortised O(1). `push_back` appends to the tail; `push_front` prepends to the head.

```rust
use imbl::vector;

let mut v = vector![2, 3, 4];
v.push_back(5);
v.push_front(1);
assert_eq!(vector![1, 2, 3, 4, 5], v);

// pop symmetrically
assert_eq!(Some(5), v.pop_back());
assert_eq!(Some(1), v.pop_front());
assert_eq!(vector![2, 3, 4], v);
```
```

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

### Vector::new and Vector::unit

Source: https://context7.com/jneem/imbl/llms.txt

Creates an empty Vector using `new()` or a single-element Vector using `unit(a)`. Small vectors are stored inline.

```APIDOC
## `Vector::new` / `Vector::unit` — Create a Vector

`new()` constructs an empty vector; `unit(a)` constructs a single-element vector. Small vectors are stored inline on the stack and only heap-allocate once they grow past the chunk size (~64 elements).

```rust
use imbl::{vector, Vector};

let empty: Vector<i32> = Vector::new();
assert!(empty.is_empty());

let single = Vector::unit(42_i32);
assert_eq!(1, single.len());
assert_eq!(Some(&42), single.get(0));

// Collect from an iterator
let from_iter: Vector<i32> = (0..10).collect();
assert_eq!(10, from_iter.len());
```
```

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

### Sort Vectors In-Place

Source: https://context7.com/jneem/imbl/llms.txt

Use `sort()` for standard ascending order, `sort_by()` with a custom comparator for other orders, and `insert_ord()` to insert into an already sorted vector efficiently.

```rust
use imbl::vector;

let mut v = vector![5, 3, 1, 4, 2];
v.sort();
assert_eq!(vector![1, 2, 3, 4, 5], v);
```

```rust
let mut desc = vector![5, 3, 1, 4, 2];
desc.sort_by(|a, b| b.cmp(a));
assert_eq!(vector![5, 4, 3, 2, 1], desc);
```

```rust
let mut sorted = vector![1, 2, 4, 5];
sorted.insert_ord(3);
assert_eq!(vector![1, 2, 3, 4, 5], sorted);
```

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

### Access and Update Nested Data Structures with `update_in!` and `get_in!`

Source: https://context7.com/jneem/imbl/llms.txt

Use these macros to navigate and modify deeply nested Vectors, HashMaps, and OrdMaps using a chain of keys separated by `=>`. Ensure the `imbl` crate is imported.

```rust
use imbl::{vector, hashmap, update_in, get_in};

// Nested vector-of-vectors
let grid = vector![
    vector![1, 2, 3],
    vector![4, 5, 6],
    vector![7, 8, 9],
];

assert_eq!(Some(&6), get_in![grid, 1 => 2]);

let updated = update_in![grid, 2 => 1, 99];
assert_eq!(Some(&99), get_in![updated, 2 => 1]);

// Nested hashmap
let config = hashmap! {
    "db" => hashmap! { "port" => 5432_i32 },
};
assert_eq!(Some(&5432), get_in![config, &"db" => &"port"]);
```

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

### HashSet Operations

Source: https://context7.com/jneem/imbl/llms.txt

Utilizes the `hashset!` macro for creating unordered immutable sets. Supports standard set operations like insert, remove, union, intersection, difference, and subset checks, all with O(log n) complexity per element.

```APIDOC
## `hashset!` macro / `HashSet` operations — Unordered immutable set

`HashSet<A>` wraps a HAMT; it supports the full algebra of insert, remove, union, intersection, difference, and subset checks, all in O(log n) per element.

### Example
```rust
use imbl::{hashset, HashSet};

let mut s: HashSet<i32> = hashset![1, 2, 3, 4, 5];
assert!(s.contains(&3));

s.insert(6);
assert_eq!(6, s.len());

s.remove(&1);
assert!(!s.contains(&1));

let a = hashset![1, 2, 3];
let b = hashset![2, 3, 4];

// Set algebra
let union      = a.clone().union(b.clone());        // {1,2,3,4}
let intersect  = a.clone().intersection(b.clone()); // {2,3}
let difference = a.clone().difference(b.clone());   // {1}

assert_eq!(4, union.len());
assert_eq!(2, intersect.len());
assert_eq!(1, difference.len());

// Subset checks
assert!(intersect.is_subset(a.clone()));
assert!(!a.is_subset(b.clone()));
```
```

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

### Vector Append and Push Front Operations

Source: https://github.com/jneem/imbl/blob/main/proptest-regressions/tests/vector.txt

Appends two vectors and then adds an element to the front. This tests the combination of appending and prepending operations.

```rust
vec.append(Vector::from(vec![127, 142, 241, 16, 254, 11, 153, 252, 3, 104, 61, 225, 73, 56, 149, 247, 142, 67, 4, 24, 96, 169, 234, 215, 227, 30, 84, 45, 209])); // size 29 // len = 228
vec.append(Vector::from(vec![194, 101, 202, 247, 108, 248, 86, 224, 255, 187, 50, 123, 93, 110, 63, 83, 122, 101, 48, 38])); // size 20 // len = 248
vec.push_front(80); // len = 249
vec.append(Vector::from(vec![228, 25, 146, 89, 230, 224, 101])); // size 7 // len = 256
```

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

### Vector Insertion and Appending

Source: https://github.com/jneem/imbl/blob/main/proptest-regressions/tests/vector.txt

Demonstrates inserting an element at a specific index and appending elements to a vector. These operations modify the vector's length and content.

```rust
vec.insert(8, 88); // len = 132
vec.push_back(252); // len = 133
vec.insert(1, 65); // len = 134
```

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

### HashSet Macro and Set Operations

Source: https://context7.com/jneem/imbl/llms.txt

Create and manipulate unordered immutable sets using the `hashset!` macro and `HashSet` type. Supports standard set algebra operations like union, intersection, and difference, all in O(log n) per element.

```rust
use imbl::{hashset, HashSet};

let mut s: HashSet<i32> = hashset![1, 2, 3, 4, 5];
assert!(s.contains(&3));

s.insert(6);
assert_eq!(6, s.len());

s.remove(&1);
assert!(!s.contains(&1));

let a = hashset![1, 2, 3];
let b = hashset![2, 3, 4];

// Set algebra
let union      = a.clone().union(b.clone());        // {1,2,3,4}
let intersect  = a.clone().intersection(b.clone()); // {2,3}
let difference = a.clone().difference(b.clone());   // {1}

assert_eq!(4, union.len());
assert_eq!(2, intersect.len());
assert_eq!(1, difference.len());

// Subset checks
assert!(intersect.is_subset(a.clone()));
assert!(!a.is_subset(b.clone()));
```

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

### HashMap Mutation and Lookup

Source: https://context7.com/jneem/imbl/llms.txt

`insert` overwrites any existing value and returns the old one; `remove` returns the removed value; both are O(log n).

```APIDOC
## `HashMap::insert` / `HashMap::remove` / `HashMap::get` — Mutation and lookup

`insert` overwrites any existing value and returns the old one; `remove` returns the removed value; both are O(log n).

```rust
use imbl::{hashmap, HashMap};

let mut map: HashMap<&str, i32> = hashmap! {
    "a" => 1,
    "b" => 2,
};

// Insert and update
let old = map.insert("a", 10);
assert_eq!(Some(1), old);
assert_eq!(Some(&10), map.get("a"));

// Remove
assert_eq!(Some(10), map.remove("a"));
assert_eq!(None, map.get("a"));

// Functional style — returns new map, original unchanged
let m2 = map.update("c", 3);
assert_eq!(None, map.get("c"));   // original untouched
assert_eq!(Some(&3), m2.get("c")); // new version has the value
```
```

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

### Vector Append and Insert Operations

Source: https://github.com/jneem/imbl/blob/main/proptest-regressions/tests/vector.txt

Appends a new vector and inserts an element at the beginning. This tests the behavior of prepending and extending the vector.

```rust
let mut vec_new = Vector::from(vec![57, 103, 160, 147, 241, 248, 112, 54, 152, 245, 195, 156, 245, 143, 175, 51, 27, 183, 236, 77, 126, 27, 160, 172, 73, 179]); // size 26
vec_new.append(vec);
vec = vec_new; // len = 160
vec.insert(0, 112); // len = 161
```

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

### Vector::split_at, Vector::split_off, and Vector::slice

Source: https://context7.com/jneem/imbl/llms.txt

Operations for splitting Vectors. `split_at` divides into two halves, `split_off` removes and returns the right half in-place, and `slice` extracts a sub-range while rejoining the remainder. All run in O(log n).

```APIDOC
## `Vector::split_at` / `Vector::split_off` / `Vector::slice` — Splitting

`split_at` consumes the vector and returns two halves; `split_off` is in-place and returns the right half; `slice` extracts a sub-range and re-joins the remainder. All run in O(log n).

```rust
use imbl::vector;

let v = vector![1, 2, 3, 4, 5, 6];
let (left, right) = v.split_at(3);
assert_eq!(vector![1, 2, 3], left);
assert_eq!(vector![4, 5, 6], right);

let mut v2 = vector![10, 20, 30, 40, 50];
let tail = v2.split_off(2);
assert_eq!(vector![10, 20], v2);
assert_eq!(vector![30, 40, 50], tail);

// slice removes a range and rejoins
let mut v3 = vector![1, 2, 3, 4, 5];
let middle = v3.slice(1..4);
assert_eq!(vector![1, 5], v3);     // remainder
assert_eq!(vector![2, 3, 4], middle); // extracted slice
```
```

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

### Vector Binary Search

Source: https://context7.com/jneem/imbl/llms.txt

Standard binary search returning `Ok(index)` on a hit or `Err(insertion_index)` on a miss, in O(log n).

```APIDOC
## `Vector::binary_search` / `Vector::binary_search_by` — Search in sorted vectors

Standard binary search returning `Ok(index)` on a hit or `Err(insertion_index)` on a miss, in O(log n).

```rust
use imbl::vector;

let v = vector![1, 3, 5, 7, 9];
assert_eq!(Ok(2), v.binary_search(&5));
assert_eq!(Err(3), v.binary_search(&6)); // would go at index 3

// Custom comparator
let words = vector!["apple", "banana", "cherry"];
let result = v.binary_search_by(|&x| x.cmp(&7));
assert_eq!(Ok(3), result);
```
```

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

### Vector Sorting and Insertion

Source: https://context7.com/jneem/imbl/llms.txt

In-place sort running in O(n log n). `insert_ord` inserts a single element into an already-sorted vector using binary search in O(log n).

```APIDOC
## `Vector::sort` / `Vector::sort_by` / `Vector::insert_ord` — Sorting

In-place sort running in O(n log n). `insert_ord` inserts a single element into an already-sorted vector using binary search in O(log n).

```rust
use imbl::vector;

let mut v = vector![5, 3, 1, 4, 2];
v.sort();
assert_eq!(vector![1, 2, 3, 4, 5], v);

let mut desc = vector![5, 3, 1, 4, 2];
desc.sort_by(|a, b| b.cmp(a));
assert_eq!(vector![5, 4, 3, 2, 1], desc);

let mut sorted = vector![1, 2, 4, 5];
sorted.insert_ord(3);
assert_eq!(vector![1, 2, 3, 4, 5], sorted);
```
```

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

### Binary Search in Sorted Vectors

Source: https://context7.com/jneem/imbl/llms.txt

Perform O(log n) searches on sorted vectors using `binary_search()` for exact matches or `binary_search_by()` with a custom comparator. Returns `Ok(index)` on hit or `Err(insertion_index)` on miss.

```rust
use imbl::vector;

let v = vector![1, 3, 5, 7, 9];
assert_eq!(Ok(2), v.binary_search(&5));
assert_eq!(Err(3), v.binary_search(&6)); // would go at index 3
```

```rust
// Custom comparator
let words = vector!["apple", "banana", "cherry"];
let result = v.binary_search_by(|&x| x.cmp(&7));
assert_eq!(Ok(3), result);
```

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

### Vector Filtering and Slicing

Source: https://context7.com/jneem/imbl/llms.txt

Filtering and slicing helpers. `retain` keeps elements matching a predicate; `skip` / `take` create new vectors without the leading / trailing elements; `truncate` shortens in place.

```APIDOC
## `Vector::retain` / `Vector::skip` / `Vector::take` / `Vector::truncate`

Filtering and slicing helpers. `retain` keeps elements matching a predicate; `skip` / `take` create new vectors without the leading / trailing elements; `truncate` shortens in place.

```rust
use imbl::vector;

let mut v = vector![1, 2, 3, 4, 5, 6];
v.retain(|x| x % 2 == 0);
assert_eq!(vector![2, 4, 6], v);

let src = vector![10, 20, 30, 40, 50];
assert_eq!(vector![30, 40, 50], src.skip(2));
assert_eq!(vector![10, 20, 30], src.take(3));

let mut t = vector![1, 2, 3, 4, 5];
t.truncate(3);
assert_eq!(vector![1, 2, 3], t);
```
```

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

### Vector Split, Insert, and Pop Operations

Source: https://github.com/jneem/imbl/blob/main/proptest-regressions/tests/vector.txt

Splits a vector, inserts an element, removes the first element, and inserts another element. This sequence tests various modification methods.

```rust
vec.split_off(10); // len = 10
vec.insert(6, 131); // len = 11
vec.pop_front(); // len = 10
vec.insert(4, 235); // len = 11
vec.remove(8) // len = 10
vec.insert(6, 48); // len = 11
vec.insert(3, 194); // len = 12
```