Trait granite::Storage[−][src]

pub unsafe trait Storage: Sized {
    type Key: Clone + Debug + Eq;
    type Element;

    const CAPACITY: Option<usize>;

Show methods
    fn add(&mut self, element: Self::Element) -> Self::Key;

    fn remove(&mut self, key: &Self::Key) -> Self::Element;

    fn len(&self) -> usize;

    fn with_capacity(capacity: usize) -> Self;

    unsafe fn get_unchecked(&self, key: &Self::Key) -> &Self::Element;

    unsafe fn get_unchecked_mut(
        &mut self, 
        key: &Self::Key
    ) -> &mut Self::Element;

    fn contains_key(&self, key: &Self::Key) -> bool;

    fn get(&self, key: &Self::Key) -> Option<&Self::Element> { ... }

    fn get_mut(&mut self, key: &Self::Key) -> Option<&mut Self::Element> { ... }

    fn new() -> Self { ... }

    fn is_empty(&self) -> bool { ... }

    fn capacity(&self) -> usize { ... }

    fn reserve(&mut self, additional: usize) { ... }

    fn shrink_to_fit(&mut self) { ... }

}

Trait for various kinds of containers which can be the backing storage for data structures.

Safety

There’s a number of invariants which have to be followed by the container:

  • The length of the storage cannot be modified in the container when it’s borrowed immutably or not borrowed at all;
  • new and with_capacity must return empty storages, i.e. those which have len() == 0 and is_empty() == true;
  • it should be impossible for the length of the storage to overflow usize;
  • Calling get_unchecked or get_unchecked_mut if contains_key on the same key returns true should not cause undefined behavior (otherwise, it may or may not — that is implementation specific);
  • Calling remove if contains_key on the same key should never panic or only perform an aborting panic (i.e. not allowing unwinding), as that might leave the data structure in an invalid state during some operations;
  • If an element is added at a key, it must be retrieveable in the exact same state as it was inserted until it is removed or modified using a method which explicitly does so.
  • If CAPACITY is Some(...), the capacity method is required to return its value.

Data structures may rely on those invariants for safety.

Associated Types

type Key: Clone + Debug + Eq[src]

The type used for element naming.

type Element[src]

The type of the elements stored.

Loading content...

Associated Constants

const CAPACITY: Option<usize>[src]

The fixed capacity, for statically allocated storages. Storages like SmallVec should set this to None, since going above this limit is generally assumed to panic.

Loading content...

Required methods

fn add(&mut self, element: Self::Element) -> Self::Key[src]

Adds an element to the collection with an unspecified key, returning that key.

fn remove(&mut self, key: &Self::Key) -> Self::Element[src]

Removes and returns the element identified by key within the storage.

Panics

Required to panic if the specified key does not exist.

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

Returns the number of elements in the storage, also referred to as its ‘length’.

fn with_capacity(capacity: usize) -> Self[src]

Creates an empty collection with the specified capacity.

Panics

Collections with a fixed capacity should panic if the specified capacity is bigger than their actual one. Collections which use the heap are allowed to panic if an allocation cannot be performed, though using the OOM abort mechanism is also allowed.

unsafe fn get_unchecked(&self, key: &Self::Key) -> &Self::Element[src]

Returns a reference to the specified element in the storage, without checking for presence of the key inside the collection.

Safety

If the element at the specified key is not present in the storage, a dangling reference will be created, causing immediate undefined behavior.

unsafe fn get_unchecked_mut(&mut self, key: &Self::Key) -> &mut Self::Element[src]

Returns a mutable reference to the specified element in the storage, without checking for presence of the key inside the collection.

Safety

If the element at the specified key is not present in the storage, a dangling reference will be created, causing immediate undefined behavior.

fn contains_key(&self, key: &Self::Key) -> bool[src]

Returns true if the specified key is present in the storage, false otherwise.

If this method returned true, calling get_unchecked/get_unchecked_mut on the same key is guaranteed to be safe.

Loading content...

Provided methods

fn get(&self, key: &Self::Key) -> Option<&Self::Element>[src]

Returns a reference to the specified element in the collection, or None if the key is not present in the storage.

fn get_mut(&mut self, key: &Self::Key) -> Option<&mut Self::Element>[src]

Returns a mutable reference to the specified element in the collection, or None if the key is not present in the storage.

fn new() -> Self[src]

Creates a new empty storage. Dynamically-allocated storages created this way do not allocate memory.

The default implementation calls Self::with_capacity(0), which usually doesn’t allocate for heap-based storages.

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

Returns true if the storage contains no elements, false otherwise.

fn capacity(&self) -> usize[src]

Returns the amount of elements the collection can hold without requiring a memory allocation.

The default implementation uses the current length. Implementors are heavily encouraged to override the default behavior.

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

Reserves capacity for at least additional more elements to be inserted in the given storage. The storage 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.

For storages which have a fixed capacity, this should first check for the specified amount of elements to reserve for and if it’s not zero, either reallocate the collection anew or, if that is not supported, panic. The default implementation does exactly that.

fn shrink_to_fit(&mut self)[src]

Shrinks the capacity of the storage as much as possible.

It will drop down as close as possible to the current length, though dynamically allocated storages may not always reallocate exactly as much as it is needed to store all elements and none more.

The default implementation does nothing.

Loading content...

Implementations on Foreign Types

impl<T> Storage for Slab<T>[src]

type Key = usize

type Element = T

impl<K, V> Storage for SlotMap<K, V> where
    K: Key + Debug + Eq,
    V: Slottable, [src]

type Key = K

type Element = V

impl<K, V> Storage for HopSlotMap<K, V> where
    K: Key + Debug + Eq,
    V: Slottable, [src]

type Key = K

type Element = V

impl<K, V> Storage for DenseSlotMap<K, V> where
    K: Key + Debug + Eq,
    V: Slottable, [src]

type Key = K

type Element = V

Loading content...

Implementors

impl<T, E> Storage for T where
    T: ListStorage<Element = E>,
    E: MoveFix, [src]

type Key = usize

type Element = E

Loading content...