Struct LinearMap

pub struct LinearMap<K, V> { /* private fields */ }

A map implemented by searching linearly in a vector.

LinearMap’s keys are compared using the Eq trait. All search operations (contains_key, get, get_mut, insert, and remove) run in O(n) time, making this implementation suitable only for small numbers of keys. The ordering of the keys in the underlying vector is arbitrary.

It is a logic error for a key to be modified in such a way that the key’s equality, as determined by the Eq trait, changes while it is in the map. This is normally only possible through Cell, RefCell, global state, I/O, or unsafe code.

Example

use linear_map::LinearMap;

// type inference lets us omit an explicit type signature (which
// would be `LinearMap<&str, &str>` in this example).
let mut book_reviews = LinearMap::new();

// review some books.
book_reviews.insert("Adventures of Huckleberry Finn",    "My favorite book.");
book_reviews.insert("Grimms' Fairy Tales",               "Masterpiece.");
book_reviews.insert("Pride and Prejudice",               "Very enjoyable.");
book_reviews.insert("The Adventures of Sherlock Holmes", "Eye lyked it alot.");

// check for a specific one.
if !book_reviews.contains_key("Les Misérables") {
    println!("We've got {} reviews, but Les Misérables ain't one.",
             book_reviews.len());
}

// oops, this review has a lot of spelling mistakes. let's delete it.
book_reviews.remove("The Adventures of Sherlock Holmes");

// look up the values associated with some keys.
let to_find = ["Pride and Prejudice", "Alice's Adventure in Wonderland"];
for book in &to_find {
    match book_reviews.get(book) {
        Some(review) => println!("{}: {}", book, review),
        None => println!("{} is unreviewed.", book)
    }
}

// iterate over everything.
for (book, review) in &book_reviews {
    println!("{}: \"{}\"", book, review);
}

Implementations

impl<K: Eq, V> LinearMap<K, V>

pub fn new() -> Self

Creates an empty map. This method does not allocate.

pub fn with_capacity(capacity: usize) -> Self

Creates an empty map with the given initial capacity.

pub fn capacity(&self) -> usize

Returns the number of elements the map can hold without reallocating.

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

Reserves capacity for at least additional more to be inserted in the map. The collection may reserve more space to avoid frequent reallocations.

Panics

Panics if the new allocation size overflows usize.

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

Reserves the minimum capacity for exactly additional more elemnnts to be inserted in the map.

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

Panics

Panics if the new capacity overflows usize.

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the map as much as possible.

It will drop down as close as possible to the current length but the allocator may still inform the map that there is more space than necessary. Therefore capacity cannot be relid upon to be minimal.

pub fn len(&self) -> usize

Returns the number of elements in the map.

pub fn is_empty(&self) -> bool

Returns true if the map contains no elements.

pub fn clear(&mut self)

Clears the map, removing all elements. Keeps the allocated memory for reuse.

pub fn retain<F>(&mut self, keep_fn: F)

where F: FnMut(&K, &mut V) -> bool,

Scan through the map and keep those key-value pairs where the closure returns true.

The order the elements are visited is not specified.

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

Removes all key-value pairs from the map and returns an iterator that yields them in arbitrary order.

All key-value pairs are removed even if the iterator is not exhausted. However, the behavior of this method is unspecified if the iterator is leaked.

The iterator’s item type is (K, V).

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

Returns an iterator yielding references to the map’s keys and their corresponding values in arbitrary order.

The iterator’s item type is (&K, &V).

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

Returns an iterator yielding references to the map’s keys and mutable references to their corresponding values in arbitrary order.

The iterator’s item type is (&K, &mut V).

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

Returns an iterator yielding references to the map’s keys in arbitrary order.

The iterator’s item type is &K.

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

Returns an iterator yielding references to the map’s values in arbitrary order.

The iterator’s item type is &V.

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

where K: Borrow<Q>,

Returns a reference to the value in the map whose key is equal to the given key.

Returns None if the map contains no such key.

The given key may be any borrowed form of the map’s key type, but Eq on the borrowed form must match that of the key type.

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

where K: Borrow<Q>,

Returns a mutable reference to the value in the map whose key is equal to the given key.

Returns None if the map contains no such key.

The given key may be any borrowed form of the map’s key type, but Eq on the borrowed form must match that of the key type.

pub fn contains_key<Q: ?Sized + Eq>(&self, key: &Q) -> bool

where K: Borrow<Q>,

Checks if the map contains a key that is equal to the given key.

The given key may be any borrowed form of the map’s key type, but Eq on the borrowed form must match that of the key type.

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

Inserts a key-value pair into the map.

Returns None if the map did not contain a key that is equal to the given key.

If the map did contain such a key, its corresponding value is replaced with the given value, and the old value is returned. The key is not updated, though. This matters for values that can be == without being identical. See the [standard library’s documentation] std for more details.

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

where K: Borrow<Q>,

Removes the key in the map that is equal to the given key and returns its corresponding value.

Returns None if the map contained no such key.

The given key may be any borrowed form of the map’s key type, but Eq on the borrowed form must match that of the key type.

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

Returns the given key’s corresponding entry in the map for in-place manipulation.

Trait Implementations

impl<K: Clone, V: Clone> Clone for LinearMap<K, V>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<K: Eq + Debug, V: Debug> Debug for LinearMap<K, V>

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

Formats the value using the given formatter.

impl<K: Eq, V> Default for LinearMap<K, V>

fn default() -> Self

Returns the “default value” for a type.

impl<K: Eq, V> Extend<(K, V)> for LinearMap<K, V>

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

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: Eq, V> FromIterator<(K, V)> for LinearMap<K, V>

fn from_iter<I: IntoIterator<Item = (K, V)>>(key_values: I) -> Self

Creates a value from an iterator.

impl<'a, K: Eq + Borrow<Q>, V, Q: ?Sized + Eq> Index<&'a Q> for LinearMap<K, V>

type Output = V

The returned type after indexing.

fn index(&self, key: &'a Q) -> &V

Performs the indexing (container[index]) operation.

impl<K: Eq, V> Into<Vec<(K, V)>> for LinearMap<K, V>

fn into(self) -> Vec<(K, V)>

Converts this type into the (usually inferred) input type.

impl<'a, K: Eq, V> IntoIterator for &'a LinearMap<K, V>

type Item = (&'a K, &'a 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) -> Iter<'a, K, V>

Creates an iterator from a value.

impl<'a, K: Eq, V> IntoIterator for &'a mut LinearMap<K, V>

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) -> IterMut<'a, K, V>

Creates an iterator from a value.

impl<K: Eq, V> IntoIterator for LinearMap<K, V>

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = IntoIter<K, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> IntoIter<K, V>

Creates an iterator from a value.

impl<K: Eq, V: PartialEq> PartialEq for LinearMap<K, V>

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> Eq for LinearMap<K, V>