Trait Map

pub trait Map: AsRef<Branch> + Sized {
    // Provided methods
    fn len<T: ReadTxn>(&self, _txn: &T) -> u32 { ... }
    fn keys<'a, T: ReadTxn + 'a>(&'a self, txn: &'a T) -> Keys<'a, &'a T, T>  { ... }
    fn values<'a, T: ReadTxn + 'a>(&'a self, txn: &'a T) -> Values<'a, &'a T, T>  { ... }
    fn iter<'a, T: ReadTxn + 'a>(&'a self, txn: &'a T) -> MapIter<'a, &'a T, T>  { ... }
    fn into_iter<'a, T: ReadTxn + 'a>(self, txn: &'a T) -> MapIntoIter<'a, T>  { ... }
    fn insert<K, V>(
        &self,
        txn: &mut TransactionMut<'_>,
        key: K,
        value: V,
    ) -> V::Return
       where K: Into<Arc<str>>,
             V: Prelim { ... }
    fn try_update<K, V>(
        &self,
        txn: &mut TransactionMut<'_>,
        key: K,
        value: V,
    ) -> bool
       where K: Into<Arc<str>>,
             V: Into<Any> { ... }
    fn get_or_init<K, V>(&self, txn: &mut TransactionMut<'_>, key: K) -> V
       where K: Into<Arc<str>>,
             V: DefaultPrelim + TryFrom<Out> { ... }
    fn remove(&self, txn: &mut TransactionMut<'_>, key: &str) -> Option<Out> { ... }
    fn get<T: ReadTxn>(&self, txn: &T, key: &str) -> Option<Out> { ... }
    fn get_as<T, V>(&self, txn: &T, key: &str) -> Result<V, Error>
       where T: ReadTxn,
             V: DeserializeOwned { ... }
    fn contains_key<T: ReadTxn>(&self, _txn: &T, key: &str) -> bool { ... }
    fn clear(&self, txn: &mut TransactionMut<'_>) { ... }
}

Provided Methods

fn len<T: ReadTxn>(&self, _txn: &T) -> u32

Returns a number of entries stored within current map.

fn keys<'a, T: ReadTxn + 'a>(&'a self, txn: &'a T) -> Keys<'a, &'a T, T>

Returns an iterator that enables to traverse over all keys of entries stored within current map. These keys are not ordered.

fn values<'a, T: ReadTxn + 'a>(&'a self, txn: &'a T) -> Values<'a, &'a T, T>

Returns an iterator that enables to traverse over all values stored within current map.

fn iter<'a, T: ReadTxn + 'a>(&'a self, txn: &'a T) -> MapIter<'a, &'a T, T>

Returns an iterator that enables to traverse over all entries - tuple of key-value pairs - stored within current map.

fn into_iter<'a, T: ReadTxn + 'a>(self, txn: &'a T) -> MapIntoIter<'a, T>

fn insert<K, V>( &self, txn: &mut TransactionMut<'_>, key: K, value: V, ) -> V::Return

where K: Into<Arc<str>>, V: Prelim,

Inserts a new value under given key into current map. Returns an integrated value.

fn try_update<K, V>( &self, txn: &mut TransactionMut<'_>, key: K, value: V, ) -> bool

where K: Into<Arc<str>>, V: Into<Any>,

Tries to update a value stored under a given key within current map, if it’s different from the current one. Returns true if the value was updated, false otherwise.

The main difference from Map::insert is that this method will not insert a new value if it’s the same as the current one. It’s important distinction when dealing with shared types, as inserting an element will force previous value to be tombstoned, causing minimal memory overhead.

Example

use yrs::{Doc, Map, Transact, WriteTxn};

let doc = Doc::new();
let mut txn = doc.transact_mut();
let map = txn.get_or_insert_map("map");

assert!(map.try_update(&mut txn, "key", 1)); // created a new entry
assert!(!map.try_update(&mut txn, "key", 1)); // unchanged value doesn't trigger inserts...
assert!(map.try_update(&mut txn, "key", 2)); // ... but changed one does

fn get_or_init<K, V>(&self, txn: &mut TransactionMut<'_>, key: K) -> V

where K: Into<Arc<str>>, V: DefaultPrelim + TryFrom<Out>,

Returns an existing instance of a type stored under a given key within current map. If the given entry was not found, has been deleted or its type is different from expected, that entry will be reset to a given type and its reference will be returned.

fn remove(&self, txn: &mut TransactionMut<'_>, key: &str) -> Option<Out>

Removes a stored within current map under a given key. Returns that value or None if no entry with a given key was present in current map.

Removing nested shared types

In case when a nested shared type (eg. MapRef, ArrayRef, TextRef) is being removed, all of its contents will also be deleted recursively. A returned value will contain a reference to a current removed shared type (which will be empty due to all of its elements being deleted), not the content prior the removal.

fn get<T: ReadTxn>(&self, txn: &T, key: &str) -> Option<Out>

Returns a value stored under a given key within current map, or None if no entry with such key existed.

fn get_as<T, V>(&self, txn: &T, key: &str) -> Result<V, Error>

where T: ReadTxn, V: DeserializeOwned,

Returns a value stored under a given key within current map, deserializing it into expected type if found. If value was not found, the Any::Null will be substituted and deserialized instead (i.e. into instance of Option type, if so desired).

Example

use yrs::{Doc, In, Map, MapPrelim, Transact, WriteTxn};

let doc = Doc::new();
let mut txn = doc.transact_mut();
let map = txn.get_or_insert_map("map");

// insert a multi-nested shared refs
let alice = map.insert(&mut txn, "Alice", MapPrelim::from([
  ("name", In::from("Alice")),
  ("age", In::from(30)),
  ("address", MapPrelim::from([
    ("city", In::from("London")),
    ("street", In::from("Baker st.")),
  ]).into())
]));

// define Rust types to map from the shared refs

#[derive(Debug, PartialEq, serde::Deserialize)]
struct Person {
  name: String,
  age: u32,
  address: Option<Address>,
}

#[derive(Debug, PartialEq, serde::Deserialize)]
struct Address {
  city: String,
  street: String,
}

// retrieve and deserialize the value across multiple shared refs
let alice: Person = map.get_as(&txn, "Alice").unwrap();
assert_eq!(alice, Person {
  name: "Alice".to_string(),
  age: 30,
  address: Some(Address {
    city: "London".to_string(),
    street: "Baker st.".to_string(),
  })
});

// try to retrieve value that doesn't exist
let bob: Option<Person> = map.get_as(&txn, "Bob").unwrap();
assert_eq!(bob, None);

fn contains_key<T: ReadTxn>(&self, _txn: &T, key: &str) -> bool

Checks if an entry with given key can be found within current map.

fn clear(&self, txn: &mut TransactionMut<'_>)

Clears the contents of current map, effectively removing all of its entries.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Map for XmlHookRef

impl Map for MapRef