pub struct Map<K, V> { /* private fields */ }Expand description
A map from K to V.
Cheap to clone and cheap to keep around: the handle is a pointer and an index, so cloning one does not copy anything and every clone is the same collection.
The type parameters are not decoration. They are the collection’s shape
(15 section 3), they are written down when it is created, and they are
what a later open is checked against.
§Borrowed lookups
A lookup takes a borrowed form of the key, the same way HashMap does, so
a Map<String, u64> is read with map.get("home") and not with a String
built for the length of one call.
let db = yo::open(yo::MEMORY)?;
let hits = db.map::<String, u64>("hits")?;
hits.set("home", &1)?;
assert_eq!(hits.get("home")?, Some(1));
assert_eq!(hits.get("about")?, None);Implementations§
Source§impl<K: Decode, V: Decode> Map<K, V>
impl<K: Decode, V: Decode> Map<K, V>
Sourcepub fn name(&self) -> Result<String>
pub fn name(&self) -> Result<String>
The name this collection was opened under.
§Errors
Code::Invalid if called from inside a callback that is already
holding this database.
Sourcepub fn tag(&self) -> Tag
pub fn tag(&self) -> Tag
This collection’s shape tag.
The same 128 bits that a file carries and that another language’s binding computes for the same type. Carried in the handle rather than read out of the database, so it costs nothing and cannot fail.
Sourcepub fn get<Q>(&self, key: &Q) -> Result<Option<V>>
pub fn get<Q>(&self, key: &Q) -> Result<Option<V>>
Read a value, owned.
One allocation for the value, and none for the key. When even that one
is too many, Map::with hands over the bytes where they lie.
§Errors
Code::Corrupt if the stored bytes are not a V, which means the
file disagrees with its own shape.
Sourcepub fn with<Q, R>(
&self,
key: &Q,
f: impl FnOnce(V::Ref<'_>) -> R,
) -> Result<Option<R>>
pub fn with<Q, R>( &self, key: &Q, f: impl FnOnce(V::Ref<'_>) -> R, ) -> Result<Option<R>>
Read a value without copying it, by handing the borrowed view to f.
This is Y29 in one method: zero copy is always available and never
mandatory. The view points into the arena, so nothing is allocated and
nothing is decoded beyond checking that the bytes are a V. It is also
where G6’s point read budget is spent, which is why the closure takes
the view rather than the value.
f runs while the database is borrowed, so it cannot call back into
the same database. One that tries gets Code::Invalid rather than a
panic.
let db = yo::open(yo::MEMORY)?;
let names = db.map::<u64, String>("names")?;
names.set(&7, "ada")?;
// No String is built here, and no bytes are copied.
let len = names.with(&7, str::len)?;
assert_eq!(len, Some(3));§Errors
Code::Corrupt if the stored bytes are not a V.
Sourcepub fn set<Q, W>(&self, key: &Q, value: &W) -> Result<()>
pub fn set<Q, W>(&self, key: &Q, value: &W) -> Result<()>
Store a value, replacing whatever was there.
The value is taken borrowed as well as the key, so a
Map<String, String> is written with map.set("k", "v").
§Errors
Code::Full if the key and the value together are larger than
Map::max_entry. A value that big belongs in the log region, which
arrives with the file format in M5.
Sourcepub fn del<Q>(&self, key: &Q) -> Result<bool>
pub fn del<Q>(&self, key: &Q) -> Result<bool>
Remove a key, returning whether it was there.
§Errors
Code::Invalid if called from inside a callback that is already
holding this database.
Sourcepub fn contains<Q>(&self, key: &Q) -> Result<bool>
pub fn contains<Q>(&self, key: &Q) -> Result<bool>
Whether a key is present, without reading its value.
§Errors
Code::Invalid if called from inside a callback that is already
holding this database.
Sourcepub fn len(&self) -> Result<usize>
pub fn len(&self) -> Result<usize>
How many keys are stored.
§Errors
Code::Invalid if called from inside a callback that is already
holding this database.