Struct ZeroMap

struct ZeroMap<'a, K, V> { ... }
where
    K: ZeroMapKV<'a> + ?Sized,
    V: ZeroMapKV<'a> + ?Sized

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.

This does mean that for fixed-size data, one must use the regular type (u32, u8, char, etc), whereas for variable-size data, ZeroMap will use the dynamically sized version (str not String, ZeroSlice not ZeroVec, FooULE not Foo for custom types)

Examples

use zerovec::ZeroMap;

#[derive(serde::Serialize, serde::Deserialize)]
struct Data<'a> {
    #[serde(borrow)]
    map: ZeroMap<'a, u32, str>,
}

let mut map = ZeroMap::new();
map.insert(&1, "one");
map.insert(&2, "two");
map.insert(&4, "four");

let data = Data { map };

let bincode_bytes =
    bincode::serialize(&data).expect("Serialization should be successful");

// Will deserialize without any allocations
let deserialized: Data = bincode::deserialize(&bincode_bytes)
    .expect("Deserialization should be successful");

assert_eq!(data.map.get(&1), Some("one"));
assert_eq!(data.map.get(&2), Some("two"));

Implementations

impl<'a, K, V> ZeroMap<'a, K, V>

fn insert_var_v<VE: EncodeAsVarULE<V>>(self: &mut Self, key: &K, value: &VE) -> Option<Box<V>>

Same as insert(), but allows using EncodeAsVarULE types with the value to avoid an extra allocation when dealing with custom ULE types.

use std::borrow::Cow;
use zerovec::ZeroMap;

#[zerovec::make_varule(PersonULE)]
#[derive(Clone, Eq, PartialEq, Ord, PartialOrd)]
struct Person<'a> {
    age: u8,
    name: Cow<'a, str>,
}

let mut map: ZeroMap<u32, PersonULE> = ZeroMap::new();
map.insert_var_v(
    &1,
    &Person {
        age: 20,
        name: "Joseph".into(),
    },
);
map.insert_var_v(
    &1,
    &Person {
        age: 35,
        name: "Carla".into(),
    },
);
assert_eq!(&map.get(&1).unwrap().name, "Carla");
assert!(map.get(&3).is_none());

impl<'a, K, V> ZeroMap<'a, K, V>

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

Produce an ordered iterator over key-value pairs

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

Produce an ordered iterator over keys

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

Produce an iterator over values, ordered by keys

impl<'a, K, V> ZeroMap<'a, K, V>

fn cast_zv_k_unchecked<P>(self: Self) -> ZeroMap<'a, P, V>
where
    P: AsULE<ULE = <K as >::ULE> + ZeroMapKV<'a, Container = ZeroVec<'a, P>>

Cast a ZeroMap<K, V> to ZeroMap<P, V> where K and P are AsULE types with the same representation.

Unchecked Invariants

If K and P have different ordering semantics, unexpected behavior may occur.

fn try_convert_zv_k_unchecked<P>(self: Self) -> Result<ZeroMap<'a, P, V>, UleError>
where
    P: AsULE + ZeroMapKV<'a, Container = ZeroVec<'a, P>>

Convert a ZeroMap<K, V> to ZeroMap<P, V> where K and P are AsULE types with the same size.

Unchecked Invariants

If K and P have different ordering semantics, unexpected behavior may occur.

Panics

Panics if K::ULE and P::ULE are not the same size.

impl<'a, K, V> ZeroMap<'a, K, V>

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

Get the value associated with key, if it exists.

For fixed-size (AsULE) V types, this will return their corresponding AsULE::ULE type. If you wish to work with the V type directly, [Self::get_copied()] exists for convenience.

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);

fn get_by<impl FnMut(&K) -> Ordering: FnMut(&K) -> Ordering>(self: &Self, predicate: impl FnMut(&K) -> Ordering) -> Option<&<V as >::GetType>

Binary search the map with predicate to find a key, returning the value.

use zerovec::ZeroMap;

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

fn contains_key(self: &Self, key: &K) -> 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!(map.contains_key(&1));
assert!(!map.contains_key(&3));

fn insert(self: &mut Self, key: &K, value: &V) -> Option<<V as >::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);

fn remove(self: &mut Self, key: &K) -> Option<<V as >::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);

fn try_append<'b>(self: &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);

impl<'a, K, V> ZeroMap<'a, K, V>

fn iter_copied<'b>(self: &'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

impl<'a, K, V> ZeroMap<'a, K, V>

fn cast_zv_v_unchecked<P>(self: Self) -> ZeroMap<'a, K, P>
where
    P: AsULE<ULE = <V as >::ULE> + ZeroMapKV<'a, Container = ZeroVec<'a, P>>

Cast a ZeroMap<K, V> to ZeroMap<K, P> where V and P are AsULE types with the same representation.

Unchecked Invariants

If V and P have different ordering semantics, unexpected behavior may occur.

fn try_convert_zv_v_unchecked<P>(self: Self) -> Result<ZeroMap<'a, K, P>, UleError>
where
    P: AsULE + ZeroMapKV<'a, Container = ZeroVec<'a, P>>

Convert a ZeroMap<K, V> to ZeroMap<K, P> where V and P are AsULE types with the same size.

Unchecked Invariants

If V and P have different ordering semantics, unexpected behavior may occur.

Panics

Panics if V::ULE and P::ULE are not the same size.

impl<'a, K, V> ZeroMap<'a, K, V>

fn iter_copied_values<'b>(self: &'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>

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

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

Examples

use zerovec::ZeroMap;

let mut map = ZeroMap::new();
map.insert(&1, &'a');
map.insert(&2, &'b');
assert_eq!(map.get_copied(&1), Some('a'));
assert_eq!(map.get_copied(&3), None);

fn get_copied_by<impl FnMut(&K) -> Ordering: FnMut(&K) -> Ordering>(self: &Self, predicate: impl FnMut(&K) -> Ordering) -> Option<V>

Binary search the map with predicate to find a key, returning the value.

For cases when V is fixed-size, use this method to obtain a direct copy of V instead of V::ULE.

Examples

use zerovec::ZeroMap;

let mut map = ZeroMap::new();
map.insert(&1, &'a');
map.insert(&2, &'b');
assert_eq!(map.get_copied_by(|probe| probe.cmp(&1)), Some('a'));
assert_eq!(map.get_copied_by(|probe| probe.cmp(&3)), None);

impl<'a, K, V> ZeroMap<'a, K, V>

fn new() -> Self

Creates a new, empty ZeroMap<K, V>.

Examples

use zerovec::ZeroMap;

let zm: ZeroMap<u16, str> = ZeroMap::new();
assert!(zm.is_empty());

fn with_capacity(capacity: usize) -> Self

Construct a new ZeroMap with a given capacity

fn as_borrowed(self: &'a Self) -> ZeroMapBorrowed<'a, K, V>

Obtain a borrowed version of this map

fn len(self: &Self) -> usize

The number of elements in the ZeroMap

fn is_empty(self: &Self) -> bool

Whether the ZeroMap is empty

fn clear(self: &mut Self)

Remove all elements from the ZeroMap

fn reserve(self: &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.

impl<'a, 'b, K, V> PartialEq for ZeroMap<'a, K, V>

fn eq(self: &Self, other: &ZeroMap<'b, K, V>) -> bool

impl<'a, A, B, K, V> FromIterator for ZeroMap<'a, K, V>

fn from_iter<T>(iter: T) -> Self
where
    T: IntoIterator<Item = (A, B)>

impl<'a, K, V> Clone for ZeroMap<'a, K, V>

fn clone(self: &Self) -> Self

impl<'a, K, V> Debug for ZeroMap<'a, K, V>

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

impl<'a, K, V> Default for ZeroMap<'a, K, V>

fn default() -> Self

impl<'a, K, V> Freeze for ZeroMap<'a, K, V>

impl<'a, K, V> From for ZeroMap<'a, K, V>

fn from(other: ZeroMapBorrowed<'a, K, V>) -> Self

impl<'a, K, V> RefUnwindSafe for ZeroMap<'a, K, V>

impl<'a, K, V> Send for ZeroMap<'a, K, V>

impl<'a, K, V> Sync for ZeroMap<'a, K, V>

impl<'a, K, V> Unpin for ZeroMap<'a, K, V>

impl<'a, K, V> UnsafeUnpin for ZeroMap<'a, K, V>

impl<'a, K, V> UnwindSafe for ZeroMap<'a, K, V>

impl<'a, K, V> Yokeable for ZeroMap<'static, K, V>

fn transform(self: &'a Self) -> &'a <Self as >::Output
fn transform_owned(self: Self) -> <Self as >::Output
unsafe fn make(from: <Self as >::Output) -> Self
fn transform_mut<F>(self: &'a mut Self, f: F)
where
    F: 'static + for<'b> FnOnce(&'b mut <Self as >::Output)

impl<'zf, 's, K, V> ZeroFrom for ZeroMap<'zf, K, V>

fn zero_from(other: &'zf ZeroMap<'s, K, V>) -> Self

impl<T> Any for ZeroMap<'a, K, V>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for ZeroMap<'a, K, V>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for ZeroMap<'a, K, V>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for ZeroMap<'a, K, V>

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> ErasedDestructor for ZeroMap<'a, K, V>

impl<T> From for ZeroMap<'a, K, V>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for ZeroMap<'a, K, V>

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

impl<T, U> Into for ZeroMap<'a, K, V>

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for ZeroMap<'a, K, V>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for ZeroMap<'a, K, V>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>