Struct kempt::map::Map

pub struct Map<Key, Value>
where
    Key: Sort<Key>,
{ /* private fields */ }

An ordered Key/Value map.

This type is similar to BTreeMap, but utilizes a simpler storage model. Additionally, it provides a more thorough interface and has a merge_with() function.

This type is designed for collections with a limited number of keys. In general, this collection excels when there are fewer entries, while HashMap or BTreeMap will be better choices with larger numbers of entries. Additionally, HashMap will perform better if comparing the keys is expensive.

Implementations

impl<Key, Value> Map<Key, Value>

where Key: Sort<Key>,

pub const fn new() -> Self

Returns an empty map.

pub fn with_capacity(capacity: usize) -> Self

Returns a map with enough memory allocated to store capacity elements without reallocation.

pub fn capacity(&self) -> usize

Returns the current capacity this map can hold before it must reallocate.

pub fn insert(&mut self, key: Key, value: Value) -> Option<Field<Key, Value>>

Inserts key and value. If an entry already existed for key, the value being overwritten is returned.

pub fn insert_with( &mut self, key: Key, value: impl FnOnce() -> Value ) -> Option<Key>

Inserts an entry with key only if the map does not already contain that key.

If an existing key is found, Some(key) is returned. If an existing key isn’t found, value() will be called, a new entry will be inserted, and None will be returned.

This is similar to using Map::entry, except this function does not require that Key implement ToOwned.

pub fn contains<SearchFor>(&self, key: &SearchFor) -> bool

where Key: Sort<SearchFor>, SearchFor: ?Sized,

Returns true if this object contains key.

pub fn get<SearchFor>(&self, key: &SearchFor) -> Option<&Value>

where Key: Sort<SearchFor>, SearchFor: ?Sized,

Returns the value associated with key, if found.

pub fn get_mut<SearchFor>(&mut self, key: &SearchFor) -> Option<&mut Value>

where Key: Sort<SearchFor>, SearchFor: ?Sized,

Returns a mutable value associated with key, if found.

pub fn get_field<SearchFor>( &self, key: &SearchFor ) -> Option<&Field<Key, Value>>

where Key: Sort<SearchFor>, SearchFor: ?Sized,

Returns the field associated with key, if found.

pub fn get_field_mut<SearchFor>( &mut self, key: &SearchFor ) -> Option<&mut Field<Key, Value>>

where Key: Sort<SearchFor>, SearchFor: ?Sized,

Returns the a mutable reference to the field associated with key, if found.

pub fn field(&self, index: usize) -> Option<&Field<Key, Value>>

Returns the Field at the specified index, or None if the index is outside of the bounds of this collection.

pub fn field_mut(&mut self, index: usize) -> Option<&mut Field<Key, Value>>

Returns a mutable reference to the Field at the specified index, or None if the index is outside of the bounds of this collection.

pub fn remove<SearchFor>( &mut self, key: &SearchFor ) -> Option<Field<Key, Value>>

where Key: Sort<SearchFor>, SearchFor: ?Sized,

Removes the value associated with key, if found.

pub fn remove_by_index(&mut self, index: usize) -> Field<Key, Value>

Removes the field at index.

Panics

This function will panic if index is outside of the bounds of this collection.

pub fn len(&self) -> usize

Returns the number of fields in this object.

pub fn is_empty(&self) -> bool

Returns true if this object has no fields.

pub fn entry<'key, SearchFor>( &mut self, key: impl Into<SearchKey<'key, Key, SearchFor>> ) -> Entry<'_, 'key, Key, Value, SearchFor>

where Key: Sort<SearchFor> + Borrow<SearchFor>, SearchFor: ToOwned<Owned = Key> + ?Sized + 'key,

Returns an Entry for the associated key.

pub fn iter(&self) -> Iter<'_, Key, Value>

Returns an iterator over the fields in this object.

pub fn iter_mut(&mut self) -> IterMut<'_, Key, Value>

Returns an iterator over the fields in this object, with mutable access.

pub fn keys(&self) -> Keys<'_, Key, Value>

Returns an iterator over the keys in this object.

pub fn values(&self) -> Values<'_, Key, Value>

Returns an iterator over the values in this object.

pub fn values_mut(&mut self) -> ValuesMut<'_, Key, Value>

Returns an iterator over the fields in this object, with mutable access.

pub fn into_values(self) -> IntoValues<Key, Value>

Returns an iterator returning all of the values contained in this object.

pub fn merged_with( self, other: &Self, filter: impl FnMut(&Key, &Value) -> Option<Value>, merge: impl FnMut(&Key, &mut Value, &Value) ) -> Self

where Key: Clone, Value: Clone,

Merges the fields from self and other into a new object, returning the updated object.

• If a field is contained in other but not contained in self, filter() is called. If filter() returns a value, the returned value is inserted into the new object using the original key.
• If a field is contained in both other and self, merge() is called with mutable access to a clone of the value from self and a reference to the value from other. The merge() function is responsible for updating the value if needed to complete the merge. The merged value is inserted into the returned object.
• If a field is contained in self but not in other, it is always cloned.

use kempt::Map;

let a: Map<&'static str, usize> = [("a", 1), ("b", 2)].into_iter().collect();
let b: Map<&'static str, usize> = [("a", 1), ("c", 3)].into_iter().collect();
let merged = a.merged_with(&b, |_key, b| Some(*b), |_key, a, b| *a += *b);

assert_eq!(merged.get(&"a"), Some(&2));
assert_eq!(merged.get(&"b"), Some(&2));
assert_eq!(merged.get(&"c"), Some(&3));

pub fn merge_with( &mut self, other: &Self, filter: impl FnMut(&Key, &Value) -> Option<Value>, merge: impl FnMut(&Key, &mut Value, &Value) )

where Key: Clone,

Merges the fields from other into self.

• If a field is contained in other but not contained in self, filter() is called. If filter() returns a value, the returned value is inserted into self using the original key.
• If a field is contained in both other and self, merge() is called with mutable access to the value from self and a reference to the value from other. The merge() function is responsible for updating the value if needed to complete the merge.
• If a field is contained in self but not in other, it is ignored.

use kempt::Map;

let mut a: Map<&'static str, usize> = [("a", 1), ("b", 2)].into_iter().collect();
let b: Map<&'static str, usize> = [("a", 1), ("c", 3)].into_iter().collect();
a.merge_with(&b, |_key, b| Some(*b), |_key, a, b| *a += *b);
assert_eq!(a.get(&"a"), Some(&2));
assert_eq!(a.get(&"b"), Some(&2));
assert_eq!(a.get(&"c"), Some(&3));

pub fn drain(&mut self) -> Drain<'_, Key, Value>

Returns an iterator that returns all of the elements in this collection. After the iterator is dropped, this object will be empty.

pub fn clear(&mut self)

Clears the contents of this collection.

This does not return any allocated memory to the OS.

pub fn shrink_to_fit(&mut self)

Resizes this collection to fit its contents exactly.

This function will reallocate its internal storage to fit the contents of this collection’s current size. If the allocation is already the correct size, this is a no-op.

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

Resizes this collection to be able to hold min_capacity.

This function will reallocate its internal storage to fit the contents of this collection’s current size. If the allocation is already the correct size, this is a no-op.

If the length of this collection is larger than min_capacity, this function will behave identically to shrink_to_fit().

pub fn union<'a>(&'a self, other: &'a Self) -> Union<'a, Key, Value>

Returns an iterator that yields Unioned entries.

The iterator will return a single result for each unique Key contained in either self or other. If both collections contain a key, the iterator will contain Unioned::Both for that key.

This iterator is guaranteed to return results in the sort order of the Key type.

pub fn intersection<'a>( &'a self, other: &'a Self ) -> Intersection<'a, Key, Value>

Returns an iterator that yields entries that appear in both self and other.

The iterator will return a result for each Key contained in both self and other. If a particular key is only found in one collection, it will not be included.

This iterator is guaranteed to return results in the sort order of the Key type.

pub fn difference<'a>(&'a self, other: &'a Self) -> Difference<'a, Key, Value>

Returns an iterator that yields entries that appear in self, but not in other.

The iterator will return a result for each Key contained in self but not contained in other. If a Key is only in other or is in both collections, it will not be returned.

This iterator is guaranteed to return results in the sort order of the Key type.

Trait Implementations

impl<Key, Value: Clone> Clone for Map<Key, Value>

where Key: Sort<Key> + Clone,

fn clone(&self) -> Map<Key, Value>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Key, Value> Debug for Map<Key, Value>

where Key: Debug + Sort<Key>, Value: Debug,

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

Formats the value using the given formatter.

impl<Key, Value> Default for Map<Key, Value>

where Key: Sort<Key>,

fn default() -> Self

Returns the “default value” for a type.

impl<Key, Value> FromIterator<(Key, Value)> for Map<Key, Value>

where Key: Sort<Key>,

fn from_iter<T: IntoIterator<Item = (Key, Value)>>(iter: T) -> Self

Creates a value from an iterator.

impl<Key, Value: Hash> Hash for Map<Key, Value>

where Key: Sort<Key> + Hash,

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a, SearchFor, Key, V> Index<&'a SearchFor> for Map<Key, V>

where Key: Sort<Key> + Sort<SearchFor>, SearchFor: ?Sized,

type Output = V

The returned type after indexing.

fn index(&self, index: &'a SearchFor) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<'a, SearchFor, Key, V> IndexMut<&'a SearchFor> for Map<Key, V>

where Key: Sort<Key> + Sort<SearchFor>, SearchFor: ?Sized,

fn index_mut(&mut self, index: &'a SearchFor) -> &mut Self::Output

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

impl<'a, Key, Value> IntoIterator for &'a Map<Key, Value>

where Key: Sort<Key>,

type IntoIter = Iter<'a, Key, Value>

Which kind of iterator are we turning this into?

type Item = &'a Field<Key, Value>

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, Key, Value> IntoIterator for &'a mut Map<Key, Value>

where Key: Sort<Key>,

type IntoIter = IterMut<'a, Key, Value>

Which kind of iterator are we turning this into?

type Item = (&'a Key, &'a mut Value)

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<Key, Value> IntoIterator for Map<Key, Value>

where Key: Sort<Key>,

type IntoIter = IntoIter<Key, Value>

Which kind of iterator are we turning this into?

type Item = Field<Key, Value>

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<Key, Value: Ord> Ord for Map<Key, Value>

where Key: Sort<Key> + Ord,

fn cmp(&self, other: &Map<Key, Value>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<Key, Value: PartialEq> PartialEq for Map<Key, Value>

where Key: Sort<Key> + PartialEq,

fn eq(&self, other: &Map<Key, Value>) -> 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<Key, Value: PartialOrd> PartialOrd for Map<Key, Value>

where Key: Sort<Key> + PartialOrd,

fn partial_cmp(&self, other: &Map<Key, Value>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<Key, Value: Eq> Eq for Map<Key, Value>

where Key: Sort<Key> + Eq,

impl<Key, Value> StructuralPartialEq for Map<Key, Value>

where Key: Sort<Key>,