Struct zerovec::ZeroMap

source · [−]
pub struct ZeroMap<'a, K, V>where
    K: ZeroMapKV<'a> + ?Sized,
    V: ZeroMapKV<'a> + ?Sized,{ /* 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

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

Examples
use zerovec::ZeroMap;

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

Construct a new ZeroMap with a given capacity

Obtain a borrowed version of this map

The number of elements in the ZeroMap

Whether the ZeroMap is empty

Remove all elements from the ZeroMap

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

See Vec::reserve() for more information.

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

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

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

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

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

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

Produce an ordered iterator over key-value pairs

Produce an ordered iterator over keys

Produce an iterator over values, ordered by keys

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

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

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

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

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

Returns a TokenStream that would evalutate to self. Read more
Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
Returns the “default value” for a type. Read more

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

Deserialize this value from the given Serde deserializer. Read more
Converts to this type from the input type.
Creates a value from an iterator. Read more
This method tests for self and other values to be equal, and is used by ==. Read more
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

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

Serialize this value into the given Serde serializer. Read more

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

This type MUST be Self with the 'static replaced with 'a, i.e. Self<'a>
This method must cast self between &'a Self<'static> and &'a Self<'a>. Read more
This method must cast self between Self<'static> and Self<'a>. Read more
This method can be used to cast away Self<'a>’s lifetime. Read more
This method must cast self between &'a mut Self<'static> and &'a mut Self<'a>, and pass it to f. Read more
Clone the other C into a struct that may retain references into C.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

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

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.