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

impl Eq for MapRef