Struct MapRef 

pub struct MapRef(/* private fields */);

Collection used to store key-value entries in an unordered manner. Keys are always represented as UTF-8 strings. Values can be any value type supported by Yrs: JSON-like primitives as well as shared data types.

In terms of conflict resolution, MapRef uses logical last-write-wins principle, meaning the past updates are automatically overridden and discarded by newer ones, while concurrent updates made by different peers are resolved into a single value using document id seniority to establish order.

Example

use yrs::{any, Doc, Map, MapPrelim, Transact};
use yrs::types::ToJson;

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

// insert value
map.insert(&mut txn, "key1", "value1");

// insert nested shared type
let nested = map.insert(&mut txn, "key2", MapPrelim::from([("inner", "value2")]));
nested.insert(&mut txn, "inner2", 100);

assert_eq!(map.to_json(&txn), any!({
  "key1": "value1",
  "key2": {
    "inner": "value2",
    "inner2": 100
  }
}));

// get value
assert_eq!(map.get(&txn, "key1"), Some("value1".into()));

// remove entry
map.remove(&mut txn, "key1");
assert_eq!(map.get(&txn, "key1"), None);

Trait Implementations

impl AsPrelim for MapRef

type Prelim = MapPrelim

fn as_prelim<T>(&self, txn: &T) -> <MapRef as AsPrelim>::Prelim

where T: ReadTxn,

Converts current type contents into a Prelim type that can be used to create a new type that’s a deep copy equivalent of a current type.

impl AsRef<Branch> for MapRef

fn as_ref(&self) -> &Branch

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<MapRef> for XmlHookRef

fn as_ref(&self) -> &MapRef

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for MapRef

fn clone(&self) -> MapRef

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MapRef

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

Formats the value using the given formatter.

impl DeepObservable for MapRef

fn observe_deep<F>(&self, f: F) -> Arc<dyn Drop>

where F: Fn(&TransactionMut<'_>, &Events<'_>) + 'static,

Subscribe a callback f for all events emitted by this and nested collaborative types. Callback is accepting transaction which triggered that event and event itself, wrapped within an Event structure.

fn observe_deep_with<K, F>(&self, key: K, f: F)

where K: Into<Origin>, F: Fn(&TransactionMut<'_>, &Events<'_>) + 'static,

Subscribe a callback f for all events emitted by this and nested collaborative types. Callback is accepting transaction which triggered that event and event itself, wrapped within an Event structure.

fn unobserve_deep<K>(&self, key: K) -> bool

where K: Into<Origin>,

Unsubscribe a callback identified by a given key, that was previously subscribed using Self::observe_deep_with.

impl DefaultPrelim for MapRef

type Prelim = MapPrelim

fn default_prelim() -> <MapRef as DefaultPrelim>::Prelim

Returns an instance of Prelim-compatible type, which will turn into reference of a current type after being integrated into the document store.

impl From<BranchPtr> for MapRef

fn from(inner: BranchPtr) -> MapRef

Converts to this type from the input type.

impl Map for MapRef

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

where T: ReadTxn,

Returns a number of entries stored within current map.

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

where T: ReadTxn + 'a,

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>(&'a self, txn: &'a T) -> Values<'a, &'a T, T>

where T: ReadTxn + 'a,

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

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

where T: ReadTxn + 'a,

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

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

where T: ReadTxn + 'a,

fn insert<K, V>( &self, txn: &mut TransactionMut<'_>, key: K, value: V, ) -> <V as Prelim>::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.

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.

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

where T: ReadTxn,

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

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

where T: ReadTxn,

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.

impl Observable for MapRef

type Event = MapEvent

fn observe<F>(&self, f: F) -> Arc<dyn Drop>

where F: Fn(&TransactionMut<'_>, &Self::Event) + 'static, Event: AsRef<Self::Event>,

Subscribes a given callback to be triggered whenever current y-type is changed. A callback is triggered whenever a transaction gets committed. This function does not trigger if changes have been observed by nested shared collections.

fn observe_with<K, F>(&self, key: K, f: F)

where K: Into<Origin>, F: Fn(&TransactionMut<'_>, &Self::Event) + 'static, Event: AsRef<Self::Event>,

Subscribes a given callback to be triggered whenever current y-type is changed. A callback is triggered whenever a transaction gets committed. This function does not trigger if changes have been observed by nested shared collections.

fn unobserve<K>(&self, key: K) -> bool

where K: Into<Origin>,

Unsubscribes a given callback identified by key, that was previously subscribed using Self::observe_with.

impl PartialEq for MapRef

fn eq(&self, other: &MapRef) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RootRef for MapRef

fn type_ref() -> TypeRef

fn root<N>(name: N) -> Root<Self>

where N: Into<Arc<str>>,

Create a logical collaborative collection reference to a root-level type with a given name

impl SharedRef for MapRef

fn hook(&self) -> Hook<Self>

Returns a logical descriptor of a current shared collection.

impl ToJson for MapRef

fn to_json<T>(&self, txn: &T) -> Any

where T: ReadTxn,

Converts all contents of a current type into a JSON-like representation.

impl TryFrom<ItemPtr> for MapRef

type Error = ItemPtr

The type returned in the event of a conversion error.

fn try_from( value: ItemPtr, ) -> Result<MapRef, <MapRef as TryFrom<ItemPtr>>::Error>

Performs the conversion.

impl TryFrom<Out> for MapRef

type Error = Out

The type returned in the event of a conversion error.

fn try_from(value: Out) -> Result<MapRef, <MapRef as TryFrom<Out>>::Error>

Performs the conversion.

impl Eq for MapRef