# Struct slab::Slab [−] [src]

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

Pre-allocated storage for a uniform data type

See the module documentation for more details.

## Implementations

### `impl<T> Slab<T>` [src]

#### `pub fn new() -> Slab<T>` [src]

Construct a new, empty `Slab`.

The function does not allocate and the returned slab will have no capacity until `insert` is called or capacity is explicitly reserved.

# Examples

    let slab: Slab<i32> = Slab::new();

#### `pub fn with_capacity(capacity: usize) -> Slab<T>` [src]

Construct a new, empty `Slab` with the specified capacity.

The returned slab will be able to store exactly `capacity` without reallocating. If `capacity` is 0, the slab will not allocate.

It is important to note that this function does not specify the length of the returned slab, but only the capacity. 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 values, 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 capacity(&self) -> usize` [src]

Return the number of values the slab can store without reallocating.

# Examples

    let slab: Slab<i32> = Slab::with_capacity(10);
    assert_eq!(slab.capacity(), 10);

#### `pub fn reserve(&mut self, additional: usize)` [src]

Reserve capacity for at least `additional` more values to be stored without allocating.

`reserve` does nothing if the slab already has sufficient capacity for `additional` more values. If more capacity is required, a new segment of memory will be allocated and all existing values will be copied into it. As such, if the slab is already very large, a call to `reserve` can end up being expensive.

The slab may reserve more than `additional` extra space in order to avoid frequent reallocations. Use `reserve_exact` instead to guarantee that only the requested space is allocated.

# Panics

Panics if the new capacity overflows `usize`.

# Examples

    let mut slab = Slab::new();
    slab.insert("hello");
    slab.reserve(10);
    assert!(slab.capacity() >= 11);

#### `pub fn reserve_exact(&mut self, additional: usize)` [src]

Reserve the minimum capacity required to store exactly `additional` more values.

`reserve_exact` does nothing if the slab already has sufficient capacity for `additional` more valus. If more capacity is required, a new segment of memory will be allocated and all existing values will be copied into it. As such, if the slab is already very large, a call to `reserve` can end up being expensive.

Note that the allocator may give the slab 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 overflows `usize`.

# Examples

    let mut slab = Slab::new();
    slab.insert("hello");
    slab.reserve_exact(10);
    assert!(slab.capacity() >= 11);

#### `pub fn shrink_to_fit(&mut self)` [src]

Shrink the capacity of the slab as much as possible.

It will drop down as close as possible to the length but the allocator may still inform the vector that there is space for a few more elements. Also, since values are not moved, the slab cannot shrink past any stored values.

# Examples

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

    for i in 0..3 {
        slab.insert(i);
    }

    assert_eq!(slab.capacity(), 10);
    slab.shrink_to_fit();
    assert!(slab.capacity() >= 3);

In this case, even though two values are removed, the slab cannot shrink past the last value.

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

    for i in 0..3 {
        slab.insert(i);
    }

    slab.remove(0);
    slab.remove(1);

    assert_eq!(slab.capacity(), 10);
    slab.shrink_to_fit();
    assert!(slab.capacity() >= 3);

#### `pub fn clear(&mut self)` [src]

Clear the slab of all values.

# Examples

    let mut slab = Slab::new();

    for i in 0..3 {
        slab.insert(i);
    }

    slab.clear();
    assert!(slab.is_empty());

#### `pub fn len(&self) -> usize` [src]

Return the number of stored values.

# Examples

    let mut slab = Slab::new();

    for i in 0..3 {
        slab.insert(i);
    }

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

#### `pub fn is_empty(&self) -> bool` [src]

Return `true` if there are no values stored in the slab.

# Examples

    let mut slab = Slab::new();
    assert!(slab.is_empty());

    slab.insert(1);
    assert!(!slab.is_empty());

#### `pub fn iter(&self) -> Iter<'_, T>ⓘ

### Notable traits for Iter<'a, T>

`impl<'a, T> Iterator for Iter<'a, T> type Item = (usize, &'a T);`
` [src]

Return an iterator over the slab.

This function should generally be avoided as it is not efficient. Iterators must iterate over every slot in the slab even if it is vacant. As such, a slab with a capacity of 1 million but only one stored value must still iterate the million slots.

# Examples

    let mut slab = Slab::new();

    for i in 0..3 {
        slab.insert(i);
    }

    let mut iterator = slab.iter();

    assert_eq!(iterator.next(), Some((0, &0)));
    assert_eq!(iterator.next(), Some((1, &1)));
    assert_eq!(iterator.next(), Some((2, &2)));
    assert_eq!(iterator.next(), None);

#### `pub fn iter_mut(&mut self) -> IterMut<'_, T>ⓘ

### Notable traits for IterMut<'a, T>

`impl<'a, T> Iterator for IterMut<'a, T> type Item = (usize, &'a mut T);`
` [src]

Return an iterator that allows modifying each value.

This function should generally be avoided as it is not efficient. Iterators must iterate over every slot in the slab even if it is vacant. As such, a slab with a capacity of 1 million but only one stored value must still iterate the million slots.

# Examples

    let mut slab = Slab::new();

    let key1 = slab.insert(0);
    let key2 = slab.insert(1);

    for (key, val) in slab.iter_mut() {
        if key == key1 {
            *val += 2;
        }
    }

    assert_eq!(slab[key1], 2);
    assert_eq!(slab[key2], 1);

#### `pub fn get(&self, key: usize) -> Option<&T>` [src]

Return a reference to the value associated with the given key.

If the given key is not associated with a value, then `None` is returned.

# Examples

    let mut slab = Slab::new();
    let key = slab.insert("hello");

    assert_eq!(slab.get(key), Some(&"hello"));
    assert_eq!(slab.get(123), None);

#### `pub fn get_mut(&mut self, key: usize) -> Option<&mut T>` [src]

Return a mutable reference to the value associated with the given key.

If the given key is not associated with a value, then `None` is returned.

# Examples

    let mut slab = Slab::new();
    let key = slab.insert("hello");

    *slab.get_mut(key).unwrap() = "world";

    assert_eq!(slab[key], "world");
    assert_eq!(slab.get_mut(123), None);

#### `pub unsafe fn get_unchecked(&self, key: usize) -> &T` [src]

Return a reference to the value associated with the given key without performing bounds checking.

This function should be used with care.

# Examples

    let mut slab = Slab::new();
    let key = slab.insert(2);

    unsafe {
        assert_eq!(slab.get_unchecked(key), &2);
    }

#### `pub unsafe fn get_unchecked_mut(&mut self, key: usize) -> &mut T` [src]

Return a mutable reference to the value associated with the given key without performing bounds checking.

This function should be used with care.

# Examples

    let mut slab = Slab::new();
    let key = slab.insert(2);

    unsafe {
        let val = slab.get_unchecked_mut(key);
        *val = 13;
    }

    assert_eq!(slab[key], 13);

#### `pub fn insert(&mut self, val: T) -> usize` [src]

Insert a value in the slab, returning key assigned to the value.

The returned key can later be used to retrieve or remove the value using indexed lookup and `remove`. Additional capacity is allocated if needed. See Capacity and reallocation.

# Panics

Panics if the number of elements in the vector overflows a `usize`.

# Examples

    let mut slab = Slab::new();
    let key = slab.insert("hello");
    assert_eq!(slab[key], "hello");

#### `pub fn vacant_entry(&mut self) -> VacantEntry<'_, T>` [src]

Return a handle to a vacant entry allowing for further manipulation.

This function is useful when creating values that must contain their slab key. The returned `VacantEntry` reserves a slot in the slab and is able to query the associated key.

# Examples

    let mut slab = Slab::new();

    let hello = {
        let entry = slab.vacant_entry();
        let key = entry.key();

        entry.insert((key, "hello"));
        key
    };

    assert_eq!(hello, slab[hello].0);
    assert_eq!("hello", slab[hello].1);

#### `pub fn remove(&mut self, key: usize) -> T` [src]

Remove and return the value associated with the given key.

The key is then released and may be associated with future stored values.

# Panics

Panics if `key` is not associated with a value.

# Examples

    let mut slab = Slab::new();

    let hello = slab.insert("hello");

    assert_eq!(slab.remove(hello), "hello");
    assert!(!slab.contains(hello));

#### `pub fn contains(&self, key: usize) -> bool` [src]

Return `true` if a value is associated with the given key.

# Examples

    let mut slab = Slab::new();

    let hello = slab.insert("hello");
    assert!(slab.contains(hello));

    slab.remove(hello);

    assert!(!slab.contains(hello));

#### `pub fn retain<F>(&mut self, f: F) where
F: FnMut(usize, &mut T) -> bool,` [src]

Retain only the elements specified by the predicate.

In other words, remove all elements `e` such that `f(usize, &mut e)` returns false. This method operates in place and preserves the key associated with the retained values.

# Examples

    let mut slab = Slab::new();

    let k1 = slab.insert(0);
    let k2 = slab.insert(1);
    let k3 = slab.insert(2);

    slab.retain(|key, val| key == k1 || *val == 1);

    assert!(slab.contains(k1));
    assert!(slab.contains(k2));
    assert!(!slab.contains(k3));

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

#### `pub fn drain(&mut self) -> Drain<'_, T>ⓘ

### Notable traits for Drain<'a, T>

`impl<'a, T> Iterator for Drain<'a, T> type Item = T;`
` [src]

Return a draining iterator that removes all elements from the slab and yields the removed items.

Note: Elements are removed even if the iterator is only partially consumed or not consumed at all.

# Examples

    let mut slab = Slab::new();

    let _ = slab.insert(0);
    let _ = slab.insert(1);
    let _ = slab.insert(2);

    {
        let mut drain = slab.drain();

        assert_eq!(Some(0), drain.next());
        assert_eq!(Some(1), drain.next());
        assert_eq!(Some(2), drain.next());
        assert_eq!(None, drain.next());
    }

    assert!(slab.is_empty());

## Trait Implementations

### `impl<T: Clone> Clone for Slab<T>` [src]

#### `fn clone(&self) -> Slab<T>` [src]

Returns a copy of the value. Read more

#### `pub fn clone_from(&mut self, source: &Self)`1.0.0 [src]

Performs copy-assignment from `source`. Read more

### `impl<T> Debug for Slab<T> where
T: Debug,` [src]

#### `fn fmt(&self, fmt: &mut Formatter<'_>) -> Result` [src]

Formats the value using the given formatter. Read more

### `impl<T> Default for Slab<T>` [src]

#### `fn default() -> Self` [src]

Returns the “default value” for a type. Read more

### `impl<T> Index<usize> for Slab<T>` [src]

#### `type Output = T`

The returned type after indexing.

#### `fn index(&self, key: usize) -> &T` [src]

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

### `impl<T> IndexMut<usize> for Slab<T>` [src]

#### `fn index_mut(&mut self, key: usize) -> &mut T` [src]

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

### `impl<'a, T> IntoIterator for &'a Slab<T>` [src]

#### `type Item = (usize, &'a T)`

The type of the elements being iterated over.

#### `type IntoIter = Iter<'a, T>`

Which kind of iterator are we turning this into?

#### `fn into_iter(self) -> Iter<'a, T>ⓘ

### Notable traits for Iter<'a, T>

`impl<'a, T> Iterator for Iter<'a, T> type Item = (usize, &'a T);`
` [src]

Creates an iterator from a value. Read more

### `impl<'a, T> IntoIterator for &'a mut Slab<T>` [src]

#### `type Item = (usize, &'a mut T)`

The type of the elements being iterated over.

#### `type IntoIter = IterMut<'a, T>`

Which kind of iterator are we turning this into?

#### `fn into_iter(self) -> IterMut<'a, T>ⓘ

### Notable traits for IterMut<'a, T>

`impl<'a, T> Iterator for IterMut<'a, T> type Item = (usize, &'a mut T);`
` [src]

Creates an iterator from a value. Read more

## Auto Trait Implementations

### `impl<T> RefUnwindSafe for Slab<T> where
T: RefUnwindSafe,`

### `impl<T> Send for Slab<T> where
T: Send,`

### `impl<T> Sync for Slab<T> where
T: Sync,`

### `impl<T> Unpin for Slab<T> where
T: Unpin,`

### `impl<T> UnwindSafe for Slab<T> where
T: UnwindSafe,`

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &T` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut T` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T> ToOwned for T where
T: Clone,` [src]

#### `type Owned = T`

The resulting type after obtaining ownership.

#### `pub fn to_owned(&self) -> T` [src]

Creates owned data from borrowed data, usually by cloning. Read more

#### `pub fn clone_into(&self, target: &mut T)` [src]

🔬 This is a nightly-only experimental API. (`toowned_clone_into`)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.