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 AsRef<Branch> for MapRef

fn as_ref(&self) -> &Branch

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

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.

impl Eq for MapRef

impl From<BranchPtr> for MapRef

fn from(inner: BranchPtr) -> MapRef

Converts to this type from the input type.

impl Into<MapRef> for XmlElementRef

fn into(self) -> MapRef

Converts this type into the (usually inferred) input type.

impl Into<MapRef> for XmlHookRef

fn into(self) -> MapRef

Converts this type into the (usually inferred) 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 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 remove(&self, txn: &mut TransactionMut<'_>, key: &str) -> Option<Value>

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<Value>

where T: ReadTxn,

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

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

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.

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<Value> for MapRef

type Error = Value

The type returned in the event of a conversion error.

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

Performs the conversion.