ItemPool

itempool

Trait ItemPool 

Source 
pub trait ItemPool<T: PoolItem> {
    // Required method
    fn pool(&mut self) -> &mut Vec<T>;

    // Provided methods
    fn put(&mut self, item: T) { ... }
    fn remove_one(&mut self) -> Option<T> { ... }
    fn remove_many(&mut self, size: usize) -> Vec<T> { ... }
    fn remove_set(&mut self, size: usize) -> HashSet<T> { ... }
}
Expand description

Trait for a resource that manages a single store of items.

This trait provides methods for adding items to a pool and retrieving them randomly. Items are removed from the pool when retrieved.

§Type Parameters

  • T - The type of items stored in the pool, must implement PoolItem

§Examples

use itempool::ItemPool;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
struct Item(i32);

struct SimplePool {
    items: Vec<Item>,
}

impl ItemPool<Item> for SimplePool {
    fn pool(&mut self) -> &mut Vec<Item> {
        &mut self.items
    }
}

Required Methods§

Source

fn pool(&mut self) -> &mut Vec<T>

Returns a mutable reference to the main pool of items.

This is the primary storage for available items that can be retrieved.

Provided Methods§

Source

fn put(&mut self, item: T)

Adds an item to the pool.

§Arguments
  • item - The item to add to the pool
§Examples
pool.put(Item);
Source

fn remove_one(&mut self) -> Option<T>

Retrieves and removes one randomly selected item from the pool.

§Returns
  • Some(T) - A randomly selected item from the pool
  • None - If the pool is empty
§Examples
if let Some(item) = pool.remove_one() {
    println!("Got item: {:?}", item);
}
Examples found in repository?
examples/enemy_example.rs (line 44)
37fn main() {
38    let mut enemy_pool = EnemyPool::new(10); // Pool contains EntityId(0) to EntityId(9)
39    println!("Initial Pool: {:?}", enemy_pool.pool()); // [EntityId(0), ..., EntityId(9)]
40    println!("Initial Discard: {:?}", enemy_pool.get_discard_pool()); // []
41    println!("---");
42
43    // Get a single enemy
44    let enemy1 = enemy_pool.remove_one();
45    println!("Got one enemy: {:?}", enemy1);
46    println!("Pool after remove_one: {:?}", enemy_pool.pool());
47    println!(
48        "Discard after remove_one: {:?}",
49        enemy_pool.get_discard_pool()
50    );
51    println!("---");
52
53    // Get a set of enemies
54    let enemy_squad = enemy_pool.remove_set(3);
55    println!("Got enemy squad: {:?}", enemy_squad);
56    println!("Pool after remove_set: {:?}", enemy_pool.pool());
57    println!(
58        "Discard after remove_set: {:?}",
59        enemy_pool.get_discard_pool()
60    );
61    println!("---");
62
63    // Manually discard an enemy
64    let enemy_to_disable = EntityId(5);
65    enemy_pool.discard_one(enemy_to_disable);
66    println!("Discarded enemy ID: {:?}", enemy_to_disable);
67    println!("Pool after discard_one: {:?}", enemy_pool.pool());
68    println!(
69        "Discard after discard_one: {:?}",
70        enemy_pool.get_discard_pool()
71    ); // Contains EntityId(5)
72    println!("---");
73
74    // Get another enemy using get_set - this will trigger recycling first
75    println!("Calling get_set, which will recycle first...");
76    let enemy2 = enemy_pool.get_set(1);
77    println!("Got another enemy: {:?}", enemy2);
78    println!("Pool after recycle + get_set: {:?}", enemy_pool.pool());
79    println!(
80        "Discard after recycle + get_set: {:?}",
81        enemy_pool.get_discard_pool()
82    ); // Empty now
83    println!("---");
84
85    // Demonstrate manual recycling
86    enemy_pool.discard_one(EntityId(7));
87    enemy_pool.discard_one(EntityId(8));
88    println!("Discarded 2 more enemies");
89    println!("Pool before recycle: {:?}", enemy_pool.pool());
90    println!(
91        "Discard before recycle: {:?}",
92        enemy_pool.get_discard_pool()
93    );
94
95    enemy_pool.recycle_discarded();
96    println!("Pool after manual recycle: {:?}", enemy_pool.pool());
97    println!(
98        "Discard after manual recycle: {:?}",
99        enemy_pool.get_discard_pool()
100    );
101}
Source

fn remove_many(&mut self, size: usize) -> Vec<T>

Retrieves and removes a specified number of items from the pool.

Items are selected randomly. Note that uniqueness is not guaranteed - the same item may appear multiple times if it was in the pool multiple times.

§Arguments
  • size - The number of items to retrieve
§Returns

A vector containing the requested items

§Panics

Panics in debug mode if:

  • The pool is empty
  • size exceeds the number of available items
§Examples
let items = pool.remove_many(3);
assert_eq!(items.len(), 3);
Source

fn remove_set(&mut self, size: usize) -> HashSet<T>

Retrieves and removes a specified number of unique items from the pool.

Items are randomly selected. If a selected item is already in the result set, it is temporarily set aside and another item is selected. Items that collide are returned to the pool after selection is complete.

§Arguments
  • size - The number of unique items to retrieve
§Returns

A HashSet containing the unique items

§Panics

Panics in debug mode if:

  • The pool is empty
  • size exceeds the number of available items
§Examples
let items = pool.remove_set(5);
assert_eq!(items.len(), 5); // All items are unique
Examples found in repository?
examples/enemy_example.rs (line 54)
37fn main() {
38    let mut enemy_pool = EnemyPool::new(10); // Pool contains EntityId(0) to EntityId(9)
39    println!("Initial Pool: {:?}", enemy_pool.pool()); // [EntityId(0), ..., EntityId(9)]
40    println!("Initial Discard: {:?}", enemy_pool.get_discard_pool()); // []
41    println!("---");
42
43    // Get a single enemy
44    let enemy1 = enemy_pool.remove_one();
45    println!("Got one enemy: {:?}", enemy1);
46    println!("Pool after remove_one: {:?}", enemy_pool.pool());
47    println!(
48        "Discard after remove_one: {:?}",
49        enemy_pool.get_discard_pool()
50    );
51    println!("---");
52
53    // Get a set of enemies
54    let enemy_squad = enemy_pool.remove_set(3);
55    println!("Got enemy squad: {:?}", enemy_squad);
56    println!("Pool after remove_set: {:?}", enemy_pool.pool());
57    println!(
58        "Discard after remove_set: {:?}",
59        enemy_pool.get_discard_pool()
60    );
61    println!("---");
62
63    // Manually discard an enemy
64    let enemy_to_disable = EntityId(5);
65    enemy_pool.discard_one(enemy_to_disable);
66    println!("Discarded enemy ID: {:?}", enemy_to_disable);
67    println!("Pool after discard_one: {:?}", enemy_pool.pool());
68    println!(
69        "Discard after discard_one: {:?}",
70        enemy_pool.get_discard_pool()
71    ); // Contains EntityId(5)
72    println!("---");
73
74    // Get another enemy using get_set - this will trigger recycling first
75    println!("Calling get_set, which will recycle first...");
76    let enemy2 = enemy_pool.get_set(1);
77    println!("Got another enemy: {:?}", enemy2);
78    println!("Pool after recycle + get_set: {:?}", enemy_pool.pool());
79    println!(
80        "Discard after recycle + get_set: {:?}",
81        enemy_pool.get_discard_pool()
82    ); // Empty now
83    println!("---");
84
85    // Demonstrate manual recycling
86    enemy_pool.discard_one(EntityId(7));
87    enemy_pool.discard_one(EntityId(8));
88    println!("Discarded 2 more enemies");
89    println!("Pool before recycle: {:?}", enemy_pool.pool());
90    println!(
91        "Discard before recycle: {:?}",
92        enemy_pool.get_discard_pool()
93    );
94
95    enemy_pool.recycle_discarded();
96    println!("Pool after manual recycle: {:?}", enemy_pool.pool());
97    println!(
98        "Discard after manual recycle: {:?}",
99        enemy_pool.get_discard_pool()
100    );
101}

Implementors§