Struct ruyi_slab::Slab

pub struct Slab<T> { /* fields omitted */ }

An object based allocator backed by a contiguous growable array of slots.

Examples

let mut slab = Slab::new();
let one = slab.insert(1);
let two = slab.insert(2);

assert_eq!(slab.len(), 2);
assert_eq!(slab[two], 2);

slab.remove(one);

assert_eq!(slab.len(), 1);

let entry = slab.free_entry();
let index = entry.index();
entry.insert(index);

assert_eq!(slab.len(), 2);
assert_eq!(slab[index], index);

Capacity and reallocation

The capacity of a slab is the amount of space allocated for any future objects that will be inserted to the slab. This is not to be confused with the length of a slab, which specifies the number of actual objects within the slab. If a slab's length exceeds its capacity, its capacity will automatically be increased, but its objects will have to be reallocated.

For example, a slab with capacity 10 and length 0 would be an empty slab with space for 10 more objects. Inserting 10 or fewer objects into the slab will not change its capacity or cause reallocation to occur. However, if the slab's length is increased to 11, it will have to reallocate, which can be slow. For this reason, it is recommended to use Slab::with_capacity whenever possible to specify how big the slab is expected to get.

Implementations

impl<T> Slab<T>

pub const fn new() -> Self

Constructs a new empty Slab<T>. The allocator will not allocate until the first object is inserted.

Examples

let mut slab = Slab::new();

pub fn with_capacity(capacity: usize) -> Self

Constructs a new, empty Slab<T> with the specified capacity.

The slab will be able to hold exactly capacity objects without reallocating. If capacity is 0, the slab will not allocate.

It is important to note that although the returned slab has the capacity specified, the slab will have a zero length. For an explanation of the difference between length and capacity, see Capacity and reallocation.

Examples

let mut slab = Slab::with_capacity(10);

// The slab contains no objects, even though it has capacity for more
assert_eq!(slab.len(), 0);

// These are all done without reallocating...
for i in 0..10 {
    slab.insert(i);
}

// ...but this may make the slab reallocate
slab.insert(11);

pub fn len(&self) -> usize

Returns the number of objects in the slab.

Examples

let mut slab = Slab::with_capacity(3);
slab.insert(1);
slab.insert(2);
slab.insert(3);

assert_eq!(slab.len(), 3);

pub fn capacity(&self) -> usize

Returns the number of objects the slab can hold without reallocating.

Examples

let slab: Slab<i32> = Slab::with_capacity(10);

assert_eq!(slab.capacity(), 10);

pub fn is_empty(&self) -> bool

Returns true if the slab contains no objects.

Examples

let mut slab = Slab::new();

assert!(slab.is_empty());

slab.insert(1);

assert!(!slab.is_empty());

pub fn clear(&mut self)

Clears the slab, removing all objects.

Note that this method has no effect on the allocated capacity of the slab.

Examples

let mut slab = Slab::with_capacity(3);
slab.insert(1);
slab.insert(2);
slab.clear();

assert!(slab.is_empty());

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more objects to be inserted in the given Slab<T>. The slab may reserve more space to avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if capacity is already sufficient.

Panics

Panics if the new capacity overflows usize.

Examples

let mut slab = Slab::with_capacity(1);
slab.insert(1);
slab.reserve(10);

assert!(slab.capacity() >= 11);

pub fn reserve_exact(&mut self, additional: usize)

Reserves the minimum capacity for exactly additional more objects to be inserted in the given Slab<T>. After calling reserve_exact, capacity will be greater than or equal to self.len() + additional. Does nothing if the capacity is already sufficient.

Note that the allocator may give the collection more space than it requests. Therefore, capacity can not be relied upon to be precisely minimal. Prefer reserve if future insertions are expected.

Panics

Panics if the new capacity overflowsusize.

Examples

let mut slab = Slab::with_capacity(1);
slab.insert(1);
slab.reserve_exact(10);

assert!(slab.capacity() >= 11);

pub fn insert(&mut self, obj: T) -> usize

Inserts an object to the slab.

Examples

let mut slab = Slab::with_capacity(3);
slab.insert(1);
slab.insert(2);

assert_eq!(slab.len(), 2);

slab.insert(3);

assert_eq!(slab.len(), 3);

pub fn free_entry(&mut self) -> Entry<T>

Returns an entry referring to an unused slot for further manipulation. It is useful when an object to be inserted need know its slab index.

Examples

let mut slab = Slab::with_capacity(1);
let entry = slab.free_entry();
let index = entry.index();
let obj = (index, "My slab index");
entry.insert(obj);

assert_eq!(slab[index].0, index);

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

Removes and returns the object at the specified index, and the slot will be put to the list of free slots for reusing. None is returned if no object is found at the specified index.

Examples

let mut slab = Slab::with_capacity(1);
let one = slab.insert(1);

assert_eq!(slab.len(), 1);
assert_eq!(slab.remove(one).unwrap(), 1);
assert!(slab.is_empty());

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

Returns a reference to the object at the specified index if the object exists. Otherwise, None is returned.

Examples

let mut slab = Slab::with_capacity(3);
let one = slab.insert(1);
let two = slab.insert(2);
let three = slab.insert(3);

assert_eq!(slab.get(one), Some(&1));
assert_eq!(slab.get(three), Some(&3));
assert_eq!(slab.get(slab.len()), None);

slab.remove(two);

assert_eq!(slab.get(two), None);
assert_eq!(slab.get(slab.capacity()), None);

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

Returns a mutable reference to the object at the specified index if the object exists. Otherwise, None is returned.

Examples

let mut slab = Slab::with_capacity(2);
let one = slab.insert(1);
let two = slab.insert(2);

assert_eq!(slab[one], 1);
assert_eq!(slab[two], 2);

*slab.get_mut(one).unwrap() = 3;
slab.remove(two);

assert_eq!(slab[one], 3);
assert_eq!(slab.get_mut(two), None);

pub unsafe fn remove_unchecked(&mut self, index: usize) -> T

Removes and returns the object at the specified index without checking if the object exists or not.

Safety

If the slot at the specified index does not have an object, the behavior of calling this method is undefined.

Examples

let mut slab = Slab::with_capacity(1);
let one = slab.insert(1);

assert_eq!(slab.len(), 1);
unsafe {
    assert_eq!(slab.remove_unchecked(one), 1);
}
assert!(slab.is_empty());

pub unsafe fn get_unchecked(&self, index: usize) -> &T

Returns a reference to the object at the specified index without checking if the object exists or not.

Safety

If the slot at the specified index does not have an object, the behavior of calling this method is undefined even if the resulting reference is not used.

For a safe alternative see get.

Examples

let mut slab = Slab::with_capacity(1);
let one = slab.insert(1);

unsafe {
    assert_eq!(slab.get_unchecked(one), &1);
}

pub unsafe fn get_unchecked_mut(&mut self, index: usize) -> &mut T

Returns a mutable reference to the object at the specified index without checking if the object exists or not.

Safety

If the slot at the specified index does not have an object, the behavior of calling this method is undefined even if the resulting reference is not used.

For a safe alternative see get_mut.

Examples

let mut slab = Slab::with_capacity(1);
let one = slab.insert(1);

assert_eq!(slab[one], 1);

unsafe {
    *slab.get_unchecked_mut(one) = 2;
}

assert_eq!(slab[one], 2);

Trait Implementations

impl<T: Debug> Debug for Slab<T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T> Default for Slab<T>

fn default() -> Self

Returns the "default value" for a type.

impl<T> Drop for Slab<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Index<usize> for Slab<T>

type Output = T

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T> IndexMut<usize> for Slab<T>

fn index_mut(&mut self, index: usize) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<T: Send> Send for Slab<T>