Struct FlattenObjects

pub struct FlattenObjects<T, const CAP: usize>
where
    BitsImpl<CAP>: Bits,
{ /* private fields */ }

A container that stores numbered objects.

See the crate-level documentation for more details.

CAP is the maximum number of objects that can be held. It also equals the maximum ID that can be assigned plus one. Currently, CAP must not be greater than 1024.

Implementations

impl<T, const CAP: usize> FlattenObjects<T, CAP>

where BitsImpl<CAP>: Bits,

pub const fn new() -> Self

Creates a new empty FlattenObjects.

Panics

Panics if CAP is greater than 1024.

Example

use flatten_objects::FlattenObjects;

let objects = FlattenObjects::<u32, 20>::new();
assert_eq!(objects.capacity(), 20);

use flatten_objects::FlattenObjects;

let objects = FlattenObjects::<u32, 1025>::new();

pub const fn capacity(&self) -> usize

Returns the maximum number of objects that can be held.

It also equals the maximum ID that can be assigned plus one.

Example

use flatten_objects::FlattenObjects;

let objects = FlattenObjects::<u32, 20>::new();
assert_eq!(objects.capacity(), 20);

pub const fn count(&self) -> usize

Returns the number of objects that have been added.

Example

use flatten_objects::FlattenObjects;

let mut objects = FlattenObjects::<u32, 20>::new();
assert_eq!(objects.count(), 0);
objects.add(23);    // Assign ID 0.
assert_eq!(objects.count(), 1);
objects.add(42);    // Assign ID 1.
assert_eq!(objects.count(), 2);
objects.remove(0);  // ID 0 is assigned.
assert_eq!(objects.count(), 1);
objects.remove(10); // ID 10 is not assigned.
assert_eq!(objects.count(), 1);

pub fn is_assigned(&self, id: usize) -> bool

Checks if the given id is assigned.

Returns false if the id is out of range.

Example

use flatten_objects::FlattenObjects;

let mut objects = FlattenObjects::<u32, 20>::new();
objects.add(23);        // Assign ID 0.
objects.add_at(5, 42);  // Assign ID 5.
assert!(objects.is_assigned(0));
assert!(!objects.is_assigned(1));
assert!(objects.is_assigned(5));
assert!(!objects.is_assigned(10));

pub fn get(&self, id: usize) -> Option<&T>

Returns the reference of the element with the given id if it already be assigned. Otherwise, returns None.

Example

use flatten_objects::FlattenObjects;

let mut objects = FlattenObjects::<u32, 20>::new();
objects.add(23);        // Assign ID 0.
objects.add_at(5, 42);  // Assign ID 5.
assert_eq!(objects.get(0), Some(&23));
assert_eq!(objects.get(1), None);
assert_eq!(objects.get(5), Some(&42));
assert_eq!(objects.get(10), None);

pub fn get_mut(&mut self, id: usize) -> Option<&mut T>

Returns the mutable reference of the element with the given id if it exists. Otherwise, returns None.

Example

use flatten_objects::FlattenObjects;

let mut objects = FlattenObjects::<u32, 20>::new();
objects.add(23);        // Assign ID 0.
objects.add_at(5, 42);  // Assign ID 5.
*objects.get_mut(0).unwrap() = 24;
assert_eq!(objects.get_mut(1), None);
*objects.get_mut(5).unwrap() = 43;
assert_eq!(objects.get_mut(10), None);
assert_eq!(objects.get(0), Some(&24));
assert_eq!(objects.get(5), Some(&43));

pub fn add(&mut self, value: T) -> Result<usize, T>

Add an object and assigns it the smallest available ID.

Returns the ID if there is one available. Otherwise, returns the object itself wrapped in Err.

Example

use flatten_objects::FlattenObjects;

let mut objects = FlattenObjects::<u32, 3>::new();
assert_eq!(objects.add(23), Ok(0));
assert_eq!(objects.add(42), Ok(1));
assert_eq!(objects.add(23), Ok(2));
assert_eq!(objects.add(42), Err(42));
objects.remove(1);
assert_eq!(objects.add(42), Ok(1));

pub fn add_at(&mut self, id: usize, value: T) -> Result<usize, T>

Add an object with the given ID.

Returns the ID if the object is added successfully. Otherwise, returns the object itself wrapped in Err.

Example

use flatten_objects::FlattenObjects;

let mut objects = FlattenObjects::<u32, 20>::new();
assert_eq!(objects.add_at(5, 23), Ok(5));
assert_eq!(objects.add_at(5, 42), Err(42));
assert_eq!(objects.add_at(20, 42), Err(42));

pub fn add_or_replace_at( &mut self, id: usize, value: T, ) -> Result<usize, Option<T>>

Adds an object with the given ID, replacing and returning the old object if the ID is already assigned.

Returns the ID if the object is added successfully. Returns Err(Some(old)) if the ID is already assigned. Returns Err(None) if the ID is out of range.

Example

use flatten_objects::FlattenObjects;

let mut objects = FlattenObjects::<u32, 20>::new();
assert_eq!(objects.add_or_replace_at(5, 23), Ok(5));
assert_eq!(objects.add_or_replace_at(5, 42), Err(Some(23)));
assert_eq!(objects.get(5), Some(&42));
assert_eq!(objects.add_or_replace_at(20, 42), Err(None));

pub fn remove(&mut self, id: usize) -> Option<T>

Removes and returns the object with the given ID.

After this operation, the ID is freed and can be assigned for next object again.

Example

use flatten_objects::FlattenObjects;

let mut objects = FlattenObjects::<u32, 20>::new();
let id = objects.add(23).unwrap();
assert_eq!(objects.remove(id), Some(23));
assert!(!objects.is_assigned(id));
assert_eq!(objects.remove(id), None);

pub fn ids(&self) -> Iter<'_, CAP>

Gets an iterator over the IDs of the assigned objects.

Example

use flatten_objects::FlattenObjects;

let mut objects = FlattenObjects::<u32, 20>::new();
objects.add(23);        // Assign ID 0.
objects.add_at(5, 42);  // Assign ID 5.
let mut iter = objects.ids();
assert_eq!(iter.next(), Some(0));
assert_eq!(iter.next(), Some(5));
assert_eq!(iter.next(), None);