Struct AssocList

pub struct AssocList<K, V, A: Allocator = Global> { /* private fields */ }

An associated list based on a Vec, providing the usual map functionality.

The methods are purely based on the PartialEq implementation of the key types, so most have a runtime characteristic of O(n).

In general, you should prefer to use either a HashMap, or a BTreeMap. The AssocList exists as a fallback if the key implements neither Hash nor Ord.

Note: All methods only require PartialEq for the key, but there is a strong argument to only use key types that are also (at least nearly) Ord. For example, elements associated with a f32::NAN cannot be found or deleted (PartialEq::eq will alway return false).

Implementations

impl<K, V> AssocList<K, V>

pub const fn new() -> Self

Create a new AssocList.

pub fn with_capacity(capacity: usize) -> Self

Create a new AssocList with at least the specified capacity.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

impl<K, V, A: Allocator> AssocList<K, V, A>

pub const fn new_in(alloc: A) -> Self

Available on crate feature allocator_api only.

Create a new AssocList with the provided allocator.

pub fn with_capacity_in(capacity: usize, alloc: A) -> Self

Available on crate feature allocator_api only.

Create a new AssocList with at least the specified capacity with the provided allocator.

impl<K, V, A: Allocator> AssocList<K, V, A>

pub fn keys(&self) -> Keys<'_, K, V>

Return an iterator for all keys in the AssocList.

pub fn into_keys(self) -> IntoKeys<K, V, A>

Return a consuming iterator for all keys in the AssocList.

pub fn values(&self) -> Values<'_, K, V>

Return an iterator for all values in the AssocList.

pub fn values_mut(&mut self) -> ValuesMut<'_, K, V>

Return an iterator for mutable access to all values in the AssocList.

pub fn into_values(self) -> IntoValues<K, V, A>

Return a consuming iterator for all values in the AssocList.

pub fn iter(&self) -> Iter<'_, (K, V)>

Return an iterator for all key-value pairs in the AssocList.

pub fn iter_mut(&mut self) -> IterMut<'_, K, V>

Return an iterator for all key-value pairs in the AssocList.

pub fn drain(&mut self) -> Drain<'_, K, V, A>

Removes all key-value pairs from the AssocList in bulk, returning all removed elements as an iterator. If the iterator is dropped before being fully consumed, it drops the remaining removed elements.

Leaking

See Vec::drain.

pub fn len(&self) -> usize

Return the number of key-value pairs currently contained in the AssocList.

pub fn capacity(&self) -> usize

Returns the total number of elements the AssocList can hold without reallocating.

pub fn is_empty(&self) -> bool

Returns true if the AssocList currently contains no element.

pub fn clear(&mut self)

Clears the AssocList, removing all key-value pairs.

pub fn entry(&mut self, key: K) -> Entry<'_, K, V, A>

where K: PartialEq,

Get the Entry associated with the key.

pub fn contains_key<Q>(&self, key: &Q) -> bool

where K: Borrow<Q>, Q: PartialEq + ?Sized,

Does the AssocList contain a value associated with the key.

pub fn get<Q>(&self, key: &Q) -> Option<&V>

where K: Borrow<Q>, Q: PartialEq + ?Sized,

Get a reference to the value associated with the key.

pub fn get_key_value<Q>(&self, key: &Q) -> Option<(&K, &V)>

where K: Borrow<Q>, Q: PartialEq + ?Sized,

Get a reference to the key-value pair inside the AssocList associated with the key.

pub fn get_mut<Q>(&mut self, key: &Q) -> Option<&mut V>

where K: Borrow<Q>, Q: PartialEq + ?Sized,

Get mutable access to the value associated with the key.

pub fn insert(&mut self, key: K, value: V) -> Option<V>

where K: PartialEq,

Insert a new element for the given key. If the AssocList already contains an element associated with the key, it is replaced and returned.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

pub fn remove<Q>(&mut self, key: &Q) -> Option<V>

where K: Borrow<Q>, Q: PartialEq + ?Sized,

Remove the element associated with the key from the AssocList and return it.

pub fn remove_entry<Q>(&mut self, key: &Q) -> Option<(K, V)>

where K: Borrow<Q>, Q: PartialEq + ?Sized,

Remove the key-value pair associated with the key from the AssocList and return it.

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

Reserves capacity for at least additional more key-value pairs to be inserted in the given AssocList. The collection may reserve more space to speculatively 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 exceeds isize::MAX bytes.

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

Reserves the minimum capacity for at least additional more key-value pairs to be inserted in the given AssocList. Unlike reserve, this will not deliberately over-allocate to speculatively avoid frequent allocations. 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 exceeds isize::MAX bytes.

pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>

Tries to reserve capacity for at least additional more key-value pairs to be inserted in the given AssocList. The collection may reserve more space to speculatively avoid frequent reallocations. After calling try_reserve, capacity will be greater than or equal to self.len() + additional if it returns [Ok(())]. Does nothing if capacity is already sufficient. This method preserves the contents even if an error occurs.

Errors

If the capacity overflows, or the allocator reports a failure, then an error is returned.

pub fn try_reserve_exact( &mut self, additional: usize, ) -> Result<(), TryReserveError>

Tries to reserve the minimum capacity for at least additional key-value pairs to be inserted in the given AssocList. Unlike try_reserve, this will not deliberately over-allocate to speculatively avoid frequent allocations. After calling try_reserve_exact, capacity will be greater than or equal to self.len() + additional if it returns [Ok(())]. 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 try_reserve if future insertions are expected.

Errors

If the capacity overflows, or the allocator reports a failure, then an error is returned.

pub fn shrink_to(&mut self, min_capacity: usize)

Shrinks the capacity of the underlying Vec with a lower bound.

The capacity will remain at least as large as both the length and the supplied value.

If the current capacity is less than the lower limit, this is a no-op.

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the underlying Vec 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.

Trait Implementations

impl<K: Clone, V: Clone, A: Clone + Allocator> Clone for AssocList<K, V, A>

fn clone(&self) -> AssocList<K, V, A>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<K: Debug, V: Debug, A: Allocator> Debug for AssocList<K, V, A>

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<K: Default, V: Default> Default for AssocList<K, V>

fn default() -> Self

Returns the “default value” for a type.

impl<'a, K, V, A: Allocator> Extend<(&'a K, &'a V)> for AssocList<K, V, A>

where K: PartialEq + Clone, V: Clone,

fn extend<T: IntoIterator<Item = (&'a K, &'a V)>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

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

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

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

Reserves capacity in a collection for the given number of additional elements.

impl<K: PartialEq, V, A: Allocator> Extend<(K, V)> for AssocList<K, V, A>

fn extend<T: IntoIterator<Item = (K, V)>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

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

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

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

Reserves capacity in a collection for the given number of additional elements.

impl<K: PartialEq, V, const N: usize> From<[(K, V); N]> for AssocList<K, V>

fn from(array: [(K, V); N]) -> Self

Converts to this type from the input type.

impl<K: PartialEq, V> FromIterator<(K, V)> for AssocList<K, V>

fn from_iter<T: IntoIterator<Item = (K, V)>>(iter: T) -> Self

Creates a value from an iterator.

impl<Q: PartialEq, K: Borrow<Q>, V, A: Allocator> Index<Q> for AssocList<K, V, A>

type Output = V

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<Q: PartialEq, K: Borrow<Q>, V, A: Allocator> IndexMut<Q> for AssocList<K, V, A>

fn index_mut(&mut self, key: Q) -> &mut Self::Output

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

impl<'a, K, V, A: Allocator> IntoIterator for &'a AssocList<K, V, A>

type Item = &'a (K, V)

The type of the elements being iterated over.

type IntoIter = Iter<'a, (K, V)>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, K, V, A: Allocator> IntoIterator for &'a mut AssocList<K, V, A>

type Item = (&'a K, &'a mut V)

The type of the elements being iterated over.

type IntoIter = IterMut<'a, K, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<K, V, A: Allocator> IntoIterator for AssocList<K, V, A>

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = IntoIter<(K, V), A>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<K: PartialEq, V: PartialEq, A: Allocator> PartialEq for AssocList<K, V, A>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K: Eq, V: Eq, A: Allocator> Eq for AssocList<K, V, A>