Struct enumap::map::EnumMap

pub struct EnumMap<const LENGTH: usize, E: Enum<LENGTH>, V> { /* private fields */ }

An enum map backed by an array.

The map is backed by [Option<V>; E::LENGTH], which means it does not allocate, but depending on the length of the enum and the size of the V it can require a significant amount of space. In some cases it may be beneficial to box the enum map.

To reduce the amount of space required, consider using values with a niche, like NonZeroUsize.

An incorrectly implemented Enum trait will not cause undefined behaviour but may introduce random panics and incorrect results. Consider using the enumap macro to implement Enum correctly.

Implementations

impl<const LENGTH: usize, E: Enum<LENGTH>, V> EnumMap<LENGTH, E, V>

pub fn new() -> Self

Creates an empty EnumMap.

With debug_assertions enabled, the constructor verifies the implementation of the Enum trait.

pub fn as_slice(&self) -> &[Option<V>; LENGTH]

Returns a slice of the underlying array.

Examples

use enumap::EnumMap;

enumap::enumap! {
    #[derive(Debug)]
    enum Fruit {
        Orange,
        Banana,
    }
}

let map = EnumMap::from([(Fruit::Banana, 5)]);
assert_eq!(map.as_slice(), &[None, Some(5)]);

pub fn as_mut_slice(&mut self) -> &mut [Option<V>; LENGTH]

Returns a mutable slice of the underlying array.

Examples

use enumap::EnumMap;

enumap::enumap! {
    #[derive(Debug)]
    enum Fruit {
        Orange,
        Banana,
    }
}

let mut map = EnumMap::from([(Fruit::Banana, 5)]);

for value in map.as_mut_slice() {
    if let Some(value) = value.as_mut() {
        *value *= 2;
    }
}

assert_eq!(map[Fruit::Banana], 10);

pub fn clear(&mut self)

Clears the map, removing all key-value pairs.

Examples

use enumap::EnumMap;

let mut map = EnumMap::new();

map.insert(Fruit::Orange, 3);
assert!(map.contains_key(Fruit::Orange));

map.clear();
assert!(!map.contains_key(Fruit::Orange));

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

Returns true if the map contains a value for the specified key.

Examples

use enumap::EnumMap;

let mut map = EnumMap::new();
map.insert(Fruit::Orange, 3);

assert!(map.contains_key(Fruit::Orange));
assert!(!map.contains_key(Fruit::Banana));

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

Returns a reference to the value for the corresponding key.

Examples

use enumap::EnumMap;

let mut map = EnumMap::new();
map.insert(Fruit::Orange, 3);

assert_eq!(map.get(Fruit::Orange), Some(&3));
assert_eq!(map.get(Fruit::Banana), None);

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

Returns a mutable reference to the value for the corresponding key.

Examples

use enumap::EnumMap;

let mut map = EnumMap::new();
map.insert(Fruit::Orange, 3);

if let Some(value) = map.get_mut(Fruit::Orange) {
    *value += 2;
}
assert_eq!(map[Fruit::Orange], 5);

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

Inserts a key-value pair into the map.

If the map already had a value present for the key, the old value is returned.

Examples

use enumap::EnumMap;

let mut map = EnumMap::new();
assert_eq!(map.insert(Fruit::Orange, 3), None);
assert_eq!(map.insert(Fruit::Orange, 5), Some(3));

pub fn into_values(self) -> IntoValues<LENGTH, E, V>

Creates a consuming iterator visiting all the values in order. The map cannot be used after calling this. The iterator element type is V.

Examples

use enumap::EnumMap;

let mut map = EnumMap::from([
    (Fruit::Grape, 3),
    (Fruit::Banana, 2),
    (Fruit::Orange, 1),
]);

let vec: Vec<i32> = map.into_values().collect();
assert_eq!(vec, vec![1, 2, 3]);

pub fn is_empty(&self) -> bool

Returns true if the map contains no elements.

Examples

use enumap::EnumMap;

let mut map = EnumMap::new();
assert!(map.is_empty());
map.insert(Fruit::Orange, 3);
assert!(!map.is_empty());

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

An iterator visiting all key-value pairs in order, with references to the values. The iterator element type is (E, &'a V).

Examples

use enumap::EnumMap;

let mut map = EnumMap::from([
    (Fruit::Orange, 1),
    (Fruit::Banana, 2),
    (Fruit::Grape, 3),
]);

for (key, value) in map.iter() {
    println!("key: {key:?} value: {value}");
}

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

An iterator visiting all key-value pairs in order, with mutable references to the values. The iterator element type is (E, &'a mut V).

Examples

use enumap::EnumMap;

let mut map = EnumMap::from([
    (Fruit::Orange, 1),
    (Fruit::Banana, 2),
    (Fruit::Grape, 3),
]);

for (_, value) in map.iter_mut() {
    *value *= 2;
}

assert_eq!(map[Fruit::Orange], 2);
assert_eq!(map[Fruit::Banana], 4);
assert_eq!(map[Fruit::Grape], 6);

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

An iterator visiting all keys in order. The iterator element type is E.

Examples

use enumap::EnumMap;

let mut map = EnumMap::from([
    (Fruit::Orange, 1),
    (Fruit::Grape, 2),
]);

for key in map.keys() {
    println!("{key:?}");
}

pub fn len(&self) -> usize

Returns the number of elements in the map.

Examples

use enumap::EnumMap;

let mut map = EnumMap::new();
assert_eq!(map.len(), 0);
map.insert(Fruit::Orange, "a");
assert_eq!(map.len(), 1);

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

Removes a key from the map, returning the value at the key if the key was previously in the map.

Examples

use enumap::EnumMap;

let mut map = EnumMap::new();
map.insert(Fruit::Orange, "a");
assert_eq!(map.remove(Fruit::Orange), Some("a"));

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

An iterator visiting all values in order. The iterator element type is &'a V.

Examples

use enumap::EnumMap;

let mut map = EnumMap::from([
    (Fruit::Orange, 1),
    (Fruit::Grape, 2),
]);

for value in map.values() {
    println!("{value:?}");
}

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

An iterator visiting all values mutably in order. The iterator element type is &'a mut V.

Examples

use enumap::EnumMap;

let mut map = EnumMap::from([
    (Fruit::Orange, 1),
    (Fruit::Grape, 2),
]);

for value in map.values_mut() {
    *value += 10;
}

assert_eq!(map[Fruit::Orange], 11);
assert_eq!(map[Fruit::Grape], 12);

Trait Implementations

impl<const LENGTH: usize, E: Clone + Enum<LENGTH>, V: Clone> Clone for EnumMap<LENGTH, E, V>

fn clone(&self) -> EnumMap<LENGTH, E, V>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<const LENGTH: usize, E, V> Debug for EnumMap<LENGTH, E, V>

where E: Debug + Enum<LENGTH>, V: Debug,

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

Formats the value using the given formatter.

impl<const LENGTH: usize, E: Enum<LENGTH>, V> Default for EnumMap<LENGTH, E, V>

fn default() -> Self

Returns the “default value” for a type.

impl<'de, const LENGTH: usize, E, V> Deserialize<'de> for EnumMap<LENGTH, E, V>

where E: Deserialize<'de> + Enum<LENGTH>, V: Deserialize<'de>,

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<const LENGTH: usize, E: Enum<LENGTH>, V> Extend<(E, V)> for EnumMap<LENGTH, E, V>

Inserts all new key-values from the iterator and replaces values with existing keys with new values returned from the iterator.

fn extend<T: IntoIterator<Item = (E, 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<const LENGTH: usize, E: Enum<LENGTH>, V> From<&EnumMap<LENGTH, E, V>> for EnumSet<LENGTH, E>

fn from(value: &EnumMap<LENGTH, E, V>) -> Self

Converts an &EnumMap into an EnumSet containing all of the map’s keys.

Examples

use enumap::{EnumMap, EnumSet};

let map = EnumMap::from([(Fruit::Banana, 100), (Fruit::Grape, 200)]);
let set = EnumSet::from(&map);

assert_eq!(set.len(), map.len());
for fruit in set {
    assert!(map.contains_key(fruit));
}

impl<const LENGTH: usize, E: Enum<LENGTH>, V, const N: usize> From<[(E, V); N]> for EnumMap<LENGTH, E, V>

fn from(value: [(E, V); N]) -> Self

Creates an EnumMap from key-value pairs.

Examples

use enumap::{EnumMap, Enum};

let map1 = EnumMap::from([(Fruit::Orange, 1), (Fruit::Banana, 2)]);
let map2: EnumMap<{ Fruit::LENGTH }, _, _> = [(Fruit::Orange, 1), (Fruit::Banana, 2)].into();
assert_eq!(map1, map2);

impl<const LENGTH: usize, E: Enum<LENGTH>, V> From<[Option<V>; LENGTH]> for EnumMap<LENGTH, E, V>

fn from(value: [Option<V>; LENGTH]) -> Self

Creates an enum map from the underlying array representation.

Examples

use enumap::EnumMap;

let map = EnumMap::from([None, Some(1), None]);
assert_eq!(map[Fruit::Banana], 1);
assert!(map.get(Fruit::Orange).is_none());

impl<const LENGTH: usize, E: Enum<LENGTH>, V> From<EnumMap<LENGTH, E, V>> for [Option<V>; LENGTH]

fn from(value: EnumMap<LENGTH, E, V>) -> Self

Extracts the underlying array representation from an EnumMap.

Examples

use enumap::{EnumMap, Enum};

let map = EnumMap::from([(Fruit::Banana, 1)]);
assert_eq!(<[_; { Fruit::LENGTH }]>::from(map), [None, Some(1), None]);

impl<const LENGTH: usize, E: Enum<LENGTH>, V> From<EnumMap<LENGTH, E, V>> for EnumSet<LENGTH, E>

fn from(value: EnumMap<LENGTH, E, V>) -> Self

Converts an EnumMap into an EnumSet containing all of the map’s keys.

Examples

use enumap::{EnumMap, EnumSet};

let map = EnumMap::from([(Fruit::Banana, 100), (Fruit::Grape, 200)]);
let set = EnumSet::from(map);

assert!(set.contains(Fruit::Banana));
assert!(set.contains(Fruit::Grape));
assert!(!set.contains(Fruit::Orange));

impl<const LENGTH: usize, E: Enum<LENGTH>, V> FromIterator<(E, V)> for EnumMap<LENGTH, E, V>

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

Creates a value from an iterator.

impl<const LENGTH: usize, E: Enum<LENGTH>, V> Index<E> for EnumMap<LENGTH, E, V>

type Output = V

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<'a, const LENGTH: usize, E: Enum<LENGTH>, V> IntoIterator for &'a EnumMap<LENGTH, E, V>

type Item = (E, &'a V)

The type of the elements being iterated over.

type IntoIter = Iter<'a, LENGTH, E, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<const LENGTH: usize, E: Enum<LENGTH>, V> IntoIterator for EnumMap<LENGTH, E, V>

type Item = (E, V)

The type of the elements being iterated over.

type IntoIter = IntoIter<LENGTH, E, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<const LENGTH: usize, E: PartialEq + Enum<LENGTH>, V: PartialEq> PartialEq for EnumMap<LENGTH, E, V>

fn eq(&self, other: &EnumMap<LENGTH, E, V>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<const LENGTH: usize, E, V> Serialize for EnumMap<LENGTH, E, V>

where E: Serialize + Enum<LENGTH>, V: Serialize,

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<const LENGTH: usize, E: Copy + Enum<LENGTH>, V: Copy> Copy for EnumMap<LENGTH, E, V>

impl<const LENGTH: usize, E: Eq + Enum<LENGTH>, V: Eq> Eq for EnumMap<LENGTH, E, V>

impl<const LENGTH: usize, E: Enum<LENGTH>, V> StructuralPartialEq for EnumMap<LENGTH, E, V>