Struct zerovec::map::ZeroMap

pub struct ZeroMap<'a, K, V> where
    K: ZeroMapKV<'a>,
    V: ZeroMapKV<'a>,
    K: ?Sized,
    V: ?Sized,  { /* fields omitted */ }

A zero-copy map datastructure, built on sorted binary-searchable ZeroVec and VarZeroVec.

This type, like ZeroVec and VarZeroVec, is able to zero-copy deserialize from appropriately formatted byte buffers. It is internally copy-on-write, so it can be mutated afterwards as necessary.

Internally, a ZeroMap is a zero-copy vector for keys paired with a zero-copy vector for values, sorted by the keys. Therefore, all types used in ZeroMap need to work with either ZeroVec or VarZeroVec.

Examples

use zerovec::ZeroMap;

// Example byte buffer representing the map { 1: "one" }
let BINCODE_BYTES: &[u8; 31] = &[
    4, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 11, 0, 0, 0, 0, 0, 0, 0,
    1, 0, 0, 0, 0, 0, 0, 0, 111, 110, 101
];

// Deserializing to ZeroMap requires no heap allocations.
let zero_map: ZeroMap<u32, str> = bincode::deserialize(BINCODE_BYTES)
    .expect("Should deserialize successfully");
assert_eq!(zero_map.get(&1), Some("one"));

Implementations

impl<'a, K, V> ZeroMap<'a, K, V> where
    K: ZeroMapKV<'a>,
    V: ZeroMapKV<'a>,
    K: ?Sized,
    V: ?Sized, 

pub fn new() -> Self

Construct a new ZeroMap

pub fn with_capacity(capacity: usize) -> Self

Construct a new ZeroMap with a given capacity

pub fn len(&self) -> usize

The number of elements in the ZeroMap

pub fn is_empty(&self) -> bool

Whether the ZeroMap is empty

pub fn clear(&mut self)

Remove all elements from the ZeroMap

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

Reserve capacity for additional more elements to be inserted into the ZeroMap to avoid frequent reallocations.

See Vec::reserve() for more information.

pub fn get(&self, key: &K::NeedleType) -> Option<&V::GetType>

Get the value associated with key, if it exists.

use zerovec::ZeroMap;

let mut map = ZeroMap::new();
map.insert(&1, "one");
map.insert(&2, "two");
assert_eq!(map.get(&1), Some("one"));
assert_eq!(map.get(&3), None);

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

Returns whether key is contained in this map

use zerovec::ZeroMap;

let mut map = ZeroMap::new();
map.insert(&1, "one");
map.insert(&2, "two");
assert_eq!(map.contains_key(&1), true);
assert_eq!(map.contains_key(&3), false);

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

Insert value with key, returning the existing value if it exists.

use zerovec::ZeroMap;

let mut map = ZeroMap::new();
map.insert(&1, "one");
map.insert(&2, "two");
assert_eq!(map.get(&1), Some("one"));
assert_eq!(map.get(&3), None);

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

Remove the value at key, returning it if it exists.

use zerovec::ZeroMap;

let mut map = ZeroMap::new();
map.insert(&1, "one");
map.insert(&2, "two");
assert_eq!(map.remove(&1), Some("one".to_owned().into_boxed_str()));
assert_eq!(map.get(&1), None);

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

Appends value with key to the end of the underlying vector, returning key and value if it failed. Useful for extending with an existing sorted list.

use zerovec::ZeroMap;

let mut map = ZeroMap::new();
assert!(map.try_append(&1, "uno").is_none());
assert!(map.try_append(&3, "tres").is_none());

let unsuccessful = map.try_append(&3, "tres-updated");
assert!(unsuccessful.is_some(), "append duplicate of last key");

let unsuccessful = map.try_append(&2, "dos");
assert!(unsuccessful.is_some(), "append out of order");

assert_eq!(map.get(&1), Some("uno"));

// contains the original value for the key: 3
assert_eq!(map.get(&3), Some("tres"));

// not appended since it wasn't in order
assert_eq!(map.get(&2), None);

pub fn iter<'b>(
    &'b self
) -> impl Iterator<Item = (&'b <K as ZeroMapKV<'a>>::GetType, &'b <V as ZeroMapKV<'a>>::GetType)>

Produce an ordered iterator over key-value pairs

pub fn iter_keys<'b>(
    &'b self
) -> impl Iterator<Item = &'b <K as ZeroMapKV<'a>>::GetType>

Produce an ordered iterator over keys

pub fn iter_values<'b>(
    &'b self
) -> impl Iterator<Item = &'b <V as ZeroMapKV<'a>>::GetType>

Produce an iterator over values, ordered by keys

impl<'a, K, V> ZeroMap<'a, K, V> where
    K: ZeroMapKV<'a>,
    V: ZeroMapKV<'a, Container = ZeroVec<'a, V>>,
    V: AsULE + Copy, 

pub fn get_copied(&self, key: &K::NeedleType) -> Option<V>

For cases when V is fixed-size, obtain a direct copy of V instead of V::ULE

pub fn iter_copied_values<'b>(
    &'b self
) -> impl Iterator<Item = (&'b <K as ZeroMapKV<'a>>::GetType, V)>

Similar to Self::iter() except it returns a direct copy of the values instead of references to V::ULE, in cases when V is fixed-size

impl<'a, K, V> ZeroMap<'a, K, V> where
    K: ZeroMapKV<'a, Container = ZeroVec<'a, K>>,
    V: ZeroMapKV<'a, Container = ZeroVec<'a, V>>,
    K: AsULE + Copy,
    V: AsULE + Copy, 

pub fn iter_copied<'b>(&'b self) -> impl Iterator<Item = (K, V)> + 'b

Similar to Self::iter() except it returns a direct copy of the keys values instead of references to K::ULE and V::ULE, in cases when K and V are fixed-size

Trait Implementations

impl<'a, K, V> Default for ZeroMap<'a, K, V> where
    K: ZeroMapKV<'a>,
    V: ZeroMapKV<'a>,
    K: ?Sized,
    V: ?Sized, 

fn default() -> Self

Returns the “default value” for a type.

impl<'de, K: ?Sized, V: ?Sized> Deserialize<'de> for ZeroMap<'de, K, V> where
    K: Ord,
    K::Container: Deserialize<'de>,
    V::Container: Deserialize<'de>,
    K: ZeroMapKV<'de>,
    V: ZeroMapKV<'de>,
    K::OwnedType: Deserialize<'de>,
    V::OwnedType: Deserialize<'de>, 

This impl can be made available by enabling the optional serde feature of the zerovec crate

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<'a, K, V> Serialize for ZeroMap<'a, K, V> where
    K: ZeroMapKV<'a>,
    V: ZeroMapKV<'a>,
    K: ?Sized,
    V: ?Sized,
    K::Container: Serialize,
    V::Container: Serialize,
    K::SerializeType: Serialize,
    V::SerializeType: Serialize, 

This impl can be made available by enabling the optional serde feature of the zerovec crate

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

Serialize this value into the given Serde serializer.

impl<'a, K, V> Yokeable<'a> for ZeroMap<'static, K, V> where
    K: 'static + for<'b> ZeroMapKV<'b> + ?Sized,
    V: 'static + for<'b> ZeroMapKV<'b> + ?Sized, 

This impl can be made available by enabling the optional yoke feature of the zerovec crate

type Output = ZeroMap<'a, K, V>

This type MUST be Self with the 'static replaced with 'a, i.e. Self<'a>

fn transform(&'a self) -> &'a ZeroMap<'a, K, V>

This method must cast self between &'a Self<'static> and &'a Self<'a>.

fn transform_owned(self) -> ZeroMap<'a, K, V>

This method must cast self between Self<'static> and Self<'a>.

unsafe fn make(from: ZeroMap<'a, K, V>) -> Self

This method can be used to cast away Self<'a>’s lifetime.

fn transform_mut<F>(&'a mut self, f: F) where
    F: 'static + for<'b> FnOnce(&'b mut Self::Output), 

This method must cast self between &'a mut Self<'static> and &'a mut Self<'a>, and pass it to f.

impl<'a, K, V> ZeroCopyFrom<ZeroMap<'a, K, V>> for ZeroMap<'static, K, V> where
    K: 'static + for<'b> ZeroMapKV<'b> + ?Sized,
    V: 'static + for<'b> ZeroMapKV<'b> + ?Sized,
    <K as ZeroMapKV<'static>>::Container: for<'b> ZeroCopyFrom<<K as ZeroMapKV<'b>>::Container>,
    <V as ZeroMapKV<'static>>::Container: for<'b> ZeroCopyFrom<<V as ZeroMapKV<'b>>::Container>,
    <K as ZeroMapKV<'static>>::Container: for<'b> Yokeable<'b, Output = <K as ZeroMapKV<'b>>::Container>,
    <V as ZeroMapKV<'static>>::Container: for<'b> Yokeable<'b, Output = <V as ZeroMapKV<'b>>::Container>, 

fn zero_copy_from<'b>(cart: &'b ZeroMap<'a, K, V>) -> ZeroMap<'b, K, V>

Clone the cart C into a Yokeable struct, which may retain references into C.