itempool 0.1.0

A simple trait for managing pools of reusable items with discard/recycle support.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# itempool

[![Crates.io](https://img.shields.io/crates/v/itempool.svg)](https://crates.io/crates/itempool)
[![Docs.rs](https://docs.rs/itempool/badge.svg)](https://docs.rs/itempool)
[![License](https://img.shields.io/crates/l/itempool.svg)](./LICENSE)

A lightweight Rust library for managing pools of reusable items with support for random selection, unique set retrieval, and item recycling.

## Features

* **Random Item Selection**: Efficiently retrieve random items from a pool with `remove_one()`
* **Unique Sets**: Get sets of unique items without duplicates using `remove_set()`
* **Item Recycling**: Temporarily discard items and recycle them back into the pool
* **Type Safety**: Uses trait bounds ensuring items are `Hash + Eq + Sync`
* **Zero-cost Abstractions**: Trait-based design with minimal overhead
* **WebAssembly Support**: Works with `wasm32-unknown-unknown` target

## Installation

Add `itempool` to your `Cargo.toml`:

```toml
[dependencies]
itempool = "0.1"
```

## Core Concepts

### `PoolItem` Trait

Items in the pool must implement `PoolItem`, which requires:

* **`Hash`**: For use in hash sets and uniqueness checks
* **`Eq`**: For equality comparisons
* **`Sync`**: For safe concurrent access across threads

### `ItemPool<T>` Trait

The main trait for managing a pool of items. Provides:

* `pool(&mut self) -> &mut Vec<T>`: Access to the main item storage
* `put(&mut self, item: T)`: Add an item to the pool
* `remove_one(&mut self) -> Option<T>`: Remove and return one random item
* `remove_many(&mut self, size: usize) -> Vec<T>`: Remove multiple items (duplicates possible)
* `remove_set(&mut self, size: usize) -> HashSet<T>`: Remove a set of unique items

### `RecyclingItemPool<T>` Trait

Extends `ItemPool` with discard/recycle functionality:

* `get_discard_pool(&mut self) -> &mut Vec<T>`: Access to the discard storage
* `discard_one(&mut self, item: T)`: Move an item to the discard pool
* `recycle_discarded(&mut self)`: Move all discarded items back to the main pool
* `get_set(&mut self, size: usize) -> HashSet<T>`: Get unique items, auto-recycling first

## Example

```rust
use itempool::{ItemPool, RecyclingItemPool};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
struct EntityId(u32);

struct EnemyPool {
    available: Vec<EntityId>,
    discarded: Vec<EntityId>,
}

impl ItemPool<EntityId> for EnemyPool {
    fn pool(&mut self) -> &mut Vec<EntityId> {
        &mut self.available
    }
}

impl RecyclingItemPool<EntityId> for EnemyPool {
    fn get_discard_pool(&mut self) -> &mut Vec<EntityId> {
        &mut self.discarded
    }
}

fn main() {
    let mut pool = EnemyPool {
        available: (0..10).map(EntityId).collect(),
        discarded: vec![],
    };

    // Get a single random enemy
    if let Some(enemy) = pool.remove_one() {
        println!("Spawned enemy: {:?}", enemy);
    }

    // Get a squad of 3 unique enemies
    let squad = pool.remove_set(3);
    println!("Enemy squad: {:?}", squad);

    // Discard an enemy temporarily
    pool.discard_one(EntityId(5));

    // Get more enemies (automatically recycles discarded ones)
    let reinforcements = pool.get_set(2);
    println!("Reinforcements: {:?}", reinforcements);
}
```

See the [examples](examples/) directory for more detailed usage.

## Use Cases

* **Game Development**: Managing enemy spawns, item drops, card decks
* **Resource Pooling**: Reusable connection pools, object pools
* **Random Selection**: Lottery systems, random sampling without replacement
* **State Management**: Temporarily unavailable resources that can be restored

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests on [GitHub](https://github.com/caniko/gpool).

## License

Dual-licensed under MIT or Apache License 2.0.