pub struct ZeroMap<'a, K, V>{ /* private fields */ }
Expand description
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§
source§impl<'a, K, V> ZeroMap<'a, K, V>
impl<'a, K, V> ZeroMap<'a, K, V>
sourcepub fn new() -> Self
pub 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());
sourcepub fn with_capacity(capacity: usize) -> Self
pub fn with_capacity(capacity: usize) -> Self
Construct a new ZeroMap
with a given capacity
sourcepub fn as_borrowed(&'a self) -> ZeroMapBorrowed<'a, K, V>
pub fn as_borrowed(&'a self) -> ZeroMapBorrowed<'a, K, V>
Obtain a borrowed version of this map
sourcepub fn reserve(&mut self, additional: usize)
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.
source§impl<'a, K, V> ZeroMap<'a, K, V>
impl<'a, K, V> ZeroMap<'a, K, V>
sourcepub fn get(&self, key: &K) -> Option<&V::GetType>
pub fn get(&self, key: &K) -> Option<&V::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);
sourcepub fn get_by(
&self,
predicate: impl FnMut(&K) -> Ordering,
) -> Option<&V::GetType>
pub fn get_by( &self, predicate: impl FnMut(&K) -> Ordering, ) -> Option<&V::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);
sourcepub fn contains_key(&self, key: &K) -> bool
pub fn contains_key(&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));
sourcepub fn insert(&mut self, key: &K, value: &V) -> Option<V::OwnedType>
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);
sourcepub fn remove(&mut self, key: &K) -> Option<V::OwnedType>
pub fn remove(&mut self, key: &K) -> 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);
sourcepub fn try_append<'b>(
&mut self,
key: &'b K,
value: &'b V,
) -> Option<(&'b K, &'b V)>
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);
source§impl<'a, K, V> ZeroMap<'a, K, V>
impl<'a, K, V> ZeroMap<'a, K, V>
sourcepub fn iter<'b>(
&'b self,
) -> impl ExactSizeIterator<Item = (&'b <K as ZeroMapKV<'a>>::GetType, &'b <V as ZeroMapKV<'a>>::GetType)>
pub fn iter<'b>( &'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
sourcepub fn iter_keys<'b>(
&'b self,
) -> impl ExactSizeIterator<Item = &'b <K as ZeroMapKV<'a>>::GetType>
pub fn iter_keys<'b>( &'b self, ) -> impl ExactSizeIterator<Item = &'b <K as ZeroMapKV<'a>>::GetType>
Produce an ordered iterator over keys
sourcepub fn iter_values<'b>(
&'b self,
) -> impl ExactSizeIterator<Item = &'b <V as ZeroMapKV<'a>>::GetType>
pub fn iter_values<'b>( &'b self, ) -> impl ExactSizeIterator<Item = &'b <V as ZeroMapKV<'a>>::GetType>
Produce an iterator over values, ordered by keys
source§impl<'a, K, V> ZeroMap<'a, K, V>
impl<'a, K, V> ZeroMap<'a, K, V>
sourcepub fn cast_zv_k_unchecked<P>(self) -> ZeroMap<'a, P, V>
pub fn cast_zv_k_unchecked<P>(self) -> ZeroMap<'a, P, V>
sourcepub fn try_convert_zv_k_unchecked<P>(
self,
) -> Result<ZeroMap<'a, P, V>, ZeroVecError>
pub fn try_convert_zv_k_unchecked<P>( self, ) -> Result<ZeroMap<'a, P, V>, ZeroVecError>
source§impl<'a, K, V> ZeroMap<'a, K, V>
impl<'a, K, V> ZeroMap<'a, K, V>
sourcepub fn cast_zv_v_unchecked<P>(self) -> ZeroMap<'a, K, P>
pub fn cast_zv_v_unchecked<P>(self) -> ZeroMap<'a, K, P>
sourcepub fn try_convert_zv_v_unchecked<P>(
self,
) -> Result<ZeroMap<'a, K, P>, ZeroVecError>
pub fn try_convert_zv_v_unchecked<P>( self, ) -> Result<ZeroMap<'a, K, P>, ZeroVecError>
source§impl<'a, K, V> ZeroMap<'a, K, V>
impl<'a, K, V> ZeroMap<'a, K, V>
sourcepub fn insert_var_v<VE: EncodeAsVarULE<V>>(
&mut self,
key: &K,
value: &VE,
) -> Option<Box<V>>
pub fn insert_var_v<VE: EncodeAsVarULE<V>>( &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());
source§impl<'a, K, V> ZeroMap<'a, K, V>
impl<'a, K, V> ZeroMap<'a, K, V>
sourcepub fn get_copied(&self, key: &K) -> Option<V>
pub fn get_copied(&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);
sourcepub fn get_copied_by(&self, predicate: impl FnMut(&K) -> Ordering) -> Option<V>
pub fn get_copied_by(&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);
source§impl<'a, K, V> ZeroMap<'a, K, V>
impl<'a, K, V> ZeroMap<'a, K, V>
sourcepub fn iter_copied_values<'b>(
&'b self,
) -> impl Iterator<Item = (&'b <K as ZeroMapKV<'a>>::GetType, V)>
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
source§impl<'a, K, V> ZeroMap<'a, K, V>
impl<'a, K, V> ZeroMap<'a, K, V>
sourcepub fn iter_copied<'b>(&'b self) -> impl Iterator<Item = (K, V)> + 'b
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§
source§impl<'a, K, V> From<ZeroMapBorrowed<'a, K, V>> for ZeroMap<'a, K, V>
impl<'a, K, V> From<ZeroMapBorrowed<'a, K, V>> for ZeroMap<'a, K, V>
source§fn from(other: ZeroMapBorrowed<'a, K, V>) -> Self
fn from(other: ZeroMapBorrowed<'a, K, V>) -> Self
source§impl<'a, A, B, K, V> FromIterator<(A, B)> for ZeroMap<'a, K, V>
impl<'a, A, B, K, V> FromIterator<(A, B)> for ZeroMap<'a, K, V>
source§impl<'a, K, V> Yokeable<'a> for ZeroMap<'static, K, V>
impl<'a, K, V> Yokeable<'a> for ZeroMap<'static, K, V>
This impl requires enabling the optional yoke
Cargo feature of the zerovec
crate
source§type Output = ZeroMap<'a, K, V>
type Output = ZeroMap<'a, K, V>
Self
with the 'static
replaced with 'a
, i.e. Self<'a>
source§fn transform_owned(self) -> Self::Output
fn transform_owned(self) -> Self::Output
Auto Trait Implementations§
impl<'a, K, V> Freeze for ZeroMap<'a, K, V>
impl<'a, K, V> RefUnwindSafe for ZeroMap<'a, K, V>where
<K as ZeroMapKV<'a>>::Container: RefUnwindSafe,
<V as ZeroMapKV<'a>>::Container: RefUnwindSafe,
K: ?Sized,
V: ?Sized,
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> UnwindSafe for ZeroMap<'a, K, V>where
<K as ZeroMapKV<'a>>::Container: UnwindSafe,
<V as ZeroMapKV<'a>>::Container: UnwindSafe,
K: ?Sized,
V: ?Sized,
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)