yrs/
branch.rs

1use crate::block::{BlockCell, Item, ItemContent, ItemPosition, ItemPtr, Prelim};
2use crate::types::array::ArrayEvent;
3use crate::types::map::MapEvent;
4use crate::types::text::TextEvent;
5use crate::types::xml::{XmlEvent, XmlTextEvent};
6use crate::types::{
7    Entries, Event, Events, Path, PathSegment, RootRef, SharedRef, TypePtr, TypeRef,
8};
9use crate::{
10    ArrayRef, Doc, MapRef, Observer, Origin, Out, ReadTxn, Subscription, TextRef, TransactionMut,
11    WriteTxn, XmlElementRef, XmlFragmentRef, XmlTextRef, ID,
12};
13use serde::{Deserialize, Serialize};
14use std::borrow::Borrow;
15use std::collections::{HashMap, HashSet, VecDeque};
16use std::convert::TryFrom;
17use std::fmt::Formatter;
18use std::hash::{Hash, Hasher};
19use std::marker::PhantomData;
20use std::ops::{Deref, DerefMut};
21use std::ptr::NonNull;
22use std::sync::Arc;
23
24/// A wrapper around [Branch] cell, supplied with a bunch of convenience methods to operate on both
25/// map-like and array-like contents of a [Branch].
26#[repr(transparent)]
27#[derive(Clone, Copy, Hash)]
28pub struct BranchPtr(NonNull<Branch>);
29
30unsafe impl Send for BranchPtr {}
31unsafe impl Sync for BranchPtr {}
32
33impl BranchPtr {
34    pub(crate) fn trigger(
35        &self,
36        txn: &TransactionMut,
37        subs: HashSet<Option<Arc<str>>>,
38    ) -> Option<Event> {
39        let e = self.make_event(subs)?;
40        self.observers.trigger(|fun| fun(txn, &e));
41        Some(e)
42    }
43
44    pub(crate) fn trigger_deep(&self, txn: &TransactionMut, e: &Events) {
45        self.deep_observers.trigger(|fun| fun(txn, e));
46    }
47}
48
49impl TryFrom<ItemPtr> for BranchPtr {
50    type Error = ItemPtr;
51
52    fn try_from(value: ItemPtr) -> Result<Self, Self::Error> {
53        if let ItemContent::Type(branch) = &value.content {
54            Ok(BranchPtr::from(branch))
55        } else {
56            Err(value)
57        }
58    }
59}
60
61impl Into<TypePtr> for BranchPtr {
62    fn into(self) -> TypePtr {
63        TypePtr::Branch(self)
64    }
65}
66
67impl Into<Origin> for BranchPtr {
68    fn into(self) -> Origin {
69        let addr = self.0.as_ptr() as usize;
70        let bytes = addr.to_be_bytes();
71        Origin::from(bytes.as_ref())
72    }
73}
74
75impl AsRef<Branch> for BranchPtr {
76    fn as_ref(&self) -> &Branch {
77        self.deref()
78    }
79}
80
81impl AsMut<Branch> for BranchPtr {
82    fn as_mut(&mut self) -> &mut Branch {
83        self.deref_mut()
84    }
85}
86
87impl Deref for BranchPtr {
88    type Target = Branch;
89
90    fn deref(&self) -> &Self::Target {
91        unsafe { self.0.as_ref() }
92    }
93}
94
95impl DerefMut for BranchPtr {
96    fn deref_mut(&mut self) -> &mut Self::Target {
97        unsafe { self.0.as_mut() }
98    }
99}
100
101impl<'a> From<&'a mut Box<Branch>> for BranchPtr {
102    fn from(branch: &'a mut Box<Branch>) -> Self {
103        let ptr = NonNull::from(branch.as_ref());
104        BranchPtr(ptr)
105    }
106}
107
108impl<'a> From<&'a Box<Branch>> for BranchPtr {
109    fn from(branch: &'a Box<Branch>) -> Self {
110        let b: &Branch = &*branch;
111
112        let ptr = unsafe { NonNull::new_unchecked(b as *const Branch as *mut Branch) };
113        BranchPtr(ptr)
114    }
115}
116
117impl<'a> From<&'a Branch> for BranchPtr {
118    fn from(branch: &'a Branch) -> Self {
119        let ptr = unsafe { NonNull::new_unchecked(branch as *const Branch as *mut Branch) };
120        BranchPtr(ptr)
121    }
122}
123
124impl Into<Out> for BranchPtr {
125    /// Converts current branch data into a [Out]. It uses a type ref information to resolve,
126    /// which value variant is a correct one for this branch. Since branch represent only complex
127    /// types [Out::Any] will never be returned from this method.
128    fn into(self) -> Out {
129        match self.type_ref() {
130            TypeRef::Array => Out::YArray(ArrayRef::from(self)),
131            TypeRef::Map => Out::YMap(MapRef::from(self)),
132            TypeRef::Text => Out::YText(TextRef::from(self)),
133            TypeRef::XmlElement(_) => Out::YXmlElement(XmlElementRef::from(self)),
134            TypeRef::XmlFragment => Out::YXmlFragment(XmlFragmentRef::from(self)),
135            TypeRef::XmlText => Out::YXmlText(XmlTextRef::from(self)),
136            //TYPE_REFS_XML_HOOK => Value::YXmlHook(XmlHookRef::from(self)),
137            #[cfg(feature = "weak")]
138            TypeRef::WeakLink(_) => Out::YWeakLink(crate::WeakRef::from(self)),
139            _ => Out::UndefinedRef(self),
140        }
141    }
142}
143
144impl Eq for BranchPtr {}
145
146#[cfg(not(test))]
147impl PartialEq for BranchPtr {
148    fn eq(&self, other: &Self) -> bool {
149        std::ptr::eq(self.0.as_ptr(), other.0.as_ptr())
150    }
151}
152
153#[cfg(test)]
154impl PartialEq for BranchPtr {
155    fn eq(&self, other: &Self) -> bool {
156        if NonNull::eq(&self.0, &other.0) {
157            true
158        } else {
159            let a: &Branch = self.deref();
160            let b: &Branch = other.deref();
161            a.eq(b)
162        }
163    }
164}
165
166impl std::fmt::Debug for BranchPtr {
167    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
168        write!(f, "{:?}", self.id())
169    }
170}
171
172/// Branch describes a content of a complex Yrs data structures, such as arrays or maps.
173pub struct Branch {
174    /// A pointer to a first block of a indexed sequence component of this branch node. If `None`,
175    /// it means that sequence is empty or a branch doesn't act as an indexed sequence. Indexed
176    /// sequences include:
177    ///
178    /// - [Array]: all elements are stored as a double linked list, while the head of the list is
179    ///   kept in this field.
180    /// - [XmlElement]: this field acts as a head to a first child element stored within current XML
181    ///   node.
182    /// - [Text] and [XmlText]: this field point to a first chunk of text appended to collaborative
183    ///   text data structure.
184    pub(crate) start: Option<ItemPtr>,
185
186    /// A map component of this branch node, used by some of the specialized complex types
187    /// including:
188    ///
189    /// - [Map]: all of the map elements are based on this field. The value of each entry points
190    ///   to the last modified value.
191    /// - [XmlElement]: this field stores attributes assigned to a given XML node.
192    pub(crate) map: HashMap<Arc<str>, ItemPtr>,
193
194    /// Unique identifier of a current branch node. It can be contain either a named string - which
195    /// means, this branch is a root-level complex data structure - or a block identifier. In latter
196    /// case it means, that this branch is a complex type (eg. Map or Array) nested inside of
197    /// another complex type.
198    pub(crate) item: Option<ItemPtr>,
199
200    /// For root-level types, this is a name of a branch.
201    pub(crate) name: Option<Arc<str>>,
202
203    /// A length of an indexed sequence component of a current branch node. Map component elements
204    /// are computed on demand.
205    pub block_len: u32,
206
207    pub content_len: u32,
208
209    /// An identifier of an underlying complex data type (eg. is it an Array or a Map).
210    pub(crate) type_ref: TypeRef,
211
212    pub(crate) observers: Observer<ObserveFn>,
213
214    pub(crate) deep_observers: Observer<DeepObserveFn>,
215}
216
217#[cfg(feature = "sync")]
218type ObserveFn = Box<dyn Fn(&TransactionMut, &Event) + Send + Sync + 'static>;
219#[cfg(feature = "sync")]
220type DeepObserveFn = Box<dyn Fn(&TransactionMut, &Events) + Send + Sync + 'static>;
221
222#[cfg(not(feature = "sync"))]
223type ObserveFn = Box<dyn Fn(&TransactionMut, &Event) + 'static>;
224#[cfg(not(feature = "sync"))]
225type DeepObserveFn = Box<dyn Fn(&TransactionMut, &Events) + 'static>;
226
227impl std::fmt::Debug for Branch {
228    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
229        std::fmt::Display::fmt(self, f)
230    }
231}
232
233impl Eq for Branch {}
234
235impl PartialEq for Branch {
236    fn eq(&self, other: &Self) -> bool {
237        self.item == other.item
238            && self.start == other.start
239            && self.map == other.map
240            && self.block_len == other.block_len
241            && self.type_ref == other.type_ref
242    }
243}
244
245impl Branch {
246    pub fn new(type_ref: TypeRef) -> Box<Self> {
247        Box::new(Self {
248            start: None,
249            map: HashMap::default(),
250            block_len: 0,
251            content_len: 0,
252            item: None,
253            name: None,
254            type_ref,
255            observers: Observer::default(),
256            deep_observers: Observer::default(),
257        })
258    }
259
260    pub fn is_deleted(&self) -> bool {
261        match self.item {
262            Some(ptr) => ptr.is_deleted(),
263            None => false,
264        }
265    }
266
267    pub fn id(&self) -> BranchID {
268        if let Some(ptr) = self.item {
269            BranchID::Nested(ptr.id)
270        } else if let Some(name) = &self.name {
271            BranchID::Root(name.clone())
272        } else {
273            unreachable!("Could not get ID for branch")
274        }
275    }
276
277    pub fn as_subdoc(&self) -> Option<Doc> {
278        let item = self.item?;
279        if let ItemContent::Doc(_, doc) = &item.content {
280            Some(doc.clone())
281        } else {
282            None
283        }
284    }
285
286    /// Returns an identifier of an underlying complex data type (eg. is it an Array or a Map).
287    pub fn type_ref(&self) -> &TypeRef {
288        &self.type_ref
289    }
290
291    pub(crate) fn repair_type_ref(&mut self, type_ref: TypeRef) {
292        if self.type_ref == TypeRef::Undefined {
293            self.type_ref = type_ref;
294        }
295    }
296
297    /// Returns a length of an indexed sequence component of a current branch node.
298    /// Map component elements are computed on demand.
299    pub fn len(&self) -> u32 {
300        self.block_len
301    }
302
303    pub fn content_len(&self) -> u32 {
304        self.content_len
305    }
306
307    /// Get iterator over (String, Block) entries of a map component of a current root type.
308    /// Deleted blocks are skipped by this iterator.
309    pub(crate) fn entries<'a, T: ReadTxn + 'a>(&'a self, txn: &'a T) -> Entries<'a, &'a T, T> {
310        Entries::from_ref(&self.map, txn)
311    }
312
313    /// Get iterator over Block entries of an array component of a current root type.
314    /// Deleted blocks are skipped by this iterator.
315    pub(crate) fn iter<'a, T: ReadTxn + 'a>(&'a self, txn: &'a T) -> Iter<'a, T> {
316        Iter::new(self.start.as_ref(), txn)
317    }
318
319    /// Returns a materialized value of non-deleted entry under a given `key` of a map component
320    /// of a current root type.
321    pub(crate) fn get<T: ReadTxn>(&self, _txn: &T, key: &str) -> Option<Out> {
322        let item = self.map.get(key)?;
323        if !item.is_deleted() {
324            item.content.get_last()
325        } else {
326            None
327        }
328    }
329
330    /// Given an `index` parameter, returns an item content reference which contains that index
331    /// together with an offset inside of this content, which points precisely to an `index`
332    /// location within wrapping item content.
333    /// If `index` was outside of the array component boundary of current branch node, `None` will
334    /// be returned.
335    pub(crate) fn get_at(&self, mut index: u32) -> Option<(&ItemContent, usize)> {
336        let mut ptr = self.start.as_ref();
337        while let Some(item) = ptr.map(ItemPtr::deref) {
338            let len = item.len();
339            if !item.is_deleted() && item.is_countable() {
340                if index < len {
341                    return Some((&item.content, index as usize));
342                }
343
344                index -= len;
345            }
346            ptr = item.right.as_ref();
347        }
348
349        None
350    }
351
352    /// Removes an entry under given `key` of a map component of a current root type, returning
353    /// a materialized representation of value stored underneath if entry existed prior deletion.
354    pub(crate) fn remove(&self, txn: &mut TransactionMut, key: &str) -> Option<Out> {
355        let item = *self.map.get(key)?;
356        let prev = if !item.is_deleted() {
357            item.content.get_last()
358        } else {
359            None
360        };
361        txn.delete(item);
362        prev
363    }
364
365    /// Returns a first non-deleted item from an array component of a current root type.
366    pub(crate) fn first(&self) -> Option<&Item> {
367        let mut ptr = self.start.as_ref();
368        while let Some(item) = ptr.map(ItemPtr::deref) {
369            if item.is_deleted() {
370                ptr = item.right.as_ref();
371            } else {
372                return Some(item);
373            }
374        }
375
376        None
377    }
378
379    /// Given an `index` and start block `ptr`, returns a pair of block pointers.
380    ///
381    /// If `index` happens to point inside of an existing block content, such block will be split at
382    /// position of an `index`. In such case left tuple value contains end of a block pointer on
383    /// a left side of an `index` and a pointer to a block directly on the right side of an `index`.
384    ///
385    /// If `index` point to the end of a block and no splitting is necessary, tuple will return only
386    /// left side (beginning of a block), while right side will be `None`.
387    ///
388    /// If `index` is outside the range of an array component of current branch node, both tuple
389    /// values will be `None`.
390    fn index_to_ptr(
391        txn: &mut TransactionMut,
392        mut ptr: Option<ItemPtr>,
393        mut index: u32,
394    ) -> (Option<ItemPtr>, Option<ItemPtr>) {
395        let encoding = txn.store.offset_kind;
396        while let Some(item) = ptr {
397            let content_len = item.content_len(encoding);
398            if !item.is_deleted() && item.is_countable() {
399                if index == content_len {
400                    let left = ptr;
401                    let right = item.right.clone();
402                    return (left, right);
403                } else if index < content_len {
404                    let index = if let ItemContent::String(s) = &item.content {
405                        s.block_offset(index, encoding)
406                    } else {
407                        index
408                    };
409                    let right = txn.store.blocks.split_block(item, index, encoding);
410                    if let Some(_) = item.moved {
411                        if let Some(src) = right {
412                            if let Some(&prev_dst) = txn.prev_moved.get(&item) {
413                                txn.prev_moved.insert(src, prev_dst);
414                            }
415                        }
416                    }
417                    return (ptr, right);
418                }
419                index -= content_len;
420            }
421            ptr = item.right.clone();
422        }
423        (None, None)
424    }
425    /// Removes up to a `len` of countable elements from current branch sequence, starting at the
426    /// given `index`. Returns number of removed elements.
427    pub(crate) fn remove_at(&self, txn: &mut TransactionMut, index: u32, len: u32) -> u32 {
428        let mut remaining = len;
429        let start = { self.start };
430        let (_, mut ptr) = if index == 0 {
431            (None, start)
432        } else {
433            Branch::index_to_ptr(txn, start, index)
434        };
435        while remaining > 0 {
436            if let Some(item) = ptr {
437                let encoding = txn.store().offset_kind;
438                if !item.is_deleted() {
439                    let content_len = item.content_len(encoding);
440                    let (l, r) = if remaining < content_len {
441                        let offset = if let ItemContent::String(s) = &item.content {
442                            s.block_offset(remaining, encoding)
443                        } else {
444                            remaining
445                        };
446                        remaining = 0;
447                        let new_right = txn.store.blocks.split_block(item, offset, encoding);
448                        if let Some(_) = item.moved {
449                            if let Some(src) = new_right {
450                                if let Some(&prev_dst) = txn.prev_moved.get(&item) {
451                                    txn.prev_moved.insert(src, prev_dst);
452                                }
453                            }
454                        }
455                        (item, new_right)
456                    } else {
457                        remaining -= content_len;
458                        (item, item.right.clone())
459                    };
460                    txn.delete(l);
461                    ptr = r;
462                } else {
463                    ptr = item.right.clone();
464                }
465            } else {
466                break;
467            }
468        }
469
470        len - remaining
471    }
472
473    /// Inserts a preliminary `value` into a current branch indexed sequence component at the given
474    /// `index`. Returns an item reference created as a result of this operation.
475    pub(crate) fn insert_at<V: Prelim>(
476        &self,
477        txn: &mut TransactionMut,
478        index: u32,
479        value: V,
480    ) -> Option<ItemPtr> {
481        let (start, parent) = {
482            if index <= self.len() {
483                (self.start, BranchPtr::from(self))
484            } else {
485                panic!("Cannot insert item at index over the length of an array")
486            }
487        };
488        let (left, right) = if index == 0 {
489            (None, None)
490        } else {
491            Branch::index_to_ptr(txn, start, index)
492        };
493        let pos = ItemPosition {
494            parent: parent.into(),
495            left,
496            right,
497            index: 0,
498            current_attrs: None,
499        };
500
501        txn.create_item(&pos, value, None)
502    }
503
504    pub(crate) fn path(from: BranchPtr, to: BranchPtr) -> Path {
505        let parent = from;
506        let mut child = to;
507        let mut path = VecDeque::default();
508        while let Some(item) = &child.item {
509            if parent.item == child.item {
510                break;
511            }
512            let item_id = item.id.clone();
513            let parent_sub = item.parent_sub.clone();
514            child = *item.parent.as_branch().unwrap();
515            if let Some(parent_sub) = parent_sub {
516                // parent is map-ish
517                path.push_front(PathSegment::Key(parent_sub));
518            } else {
519                // parent is array-ish
520                let mut i = 0;
521                let mut c = child.start;
522                while let Some(ptr) = c {
523                    if ptr.id() == &item_id {
524                        break;
525                    }
526                    if !ptr.is_deleted() && ptr.is_countable() {
527                        i += ptr.len();
528                    }
529                    c = ptr.right;
530                }
531                path.push_front(PathSegment::Index(i));
532            }
533        }
534        path
535    }
536
537    #[cfg(feature = "sync")]
538    pub fn observe<F>(&mut self, f: F) -> Subscription
539    where
540        F: Fn(&TransactionMut, &Event) + Send + Sync + 'static,
541    {
542        self.observers.subscribe(Box::new(f))
543    }
544
545    #[cfg(not(feature = "sync"))]
546    pub fn observe<F>(&mut self, f: F) -> Subscription
547    where
548        F: Fn(&TransactionMut, &Event) + 'static,
549    {
550        self.observers.subscribe(Box::new(f))
551    }
552
553    #[cfg(feature = "sync")]
554
555    pub fn observe_with<F>(&mut self, key: Origin, f: F)
556    where
557        F: Fn(&TransactionMut, &Event) + Send + Sync + 'static,
558    {
559        self.observers.subscribe_with(key, Box::new(f))
560    }
561
562    #[cfg(not(feature = "sync"))]
563    pub fn observe_with<F>(&mut self, key: Origin, f: F)
564    where
565        F: Fn(&TransactionMut, &Event) + 'static,
566    {
567        self.observers.subscribe_with(key, Box::new(f))
568    }
569
570    pub fn unobserve(&mut self, key: &Origin) -> bool {
571        self.observers.unsubscribe(&key)
572    }
573
574    #[cfg(feature = "sync")]
575    pub fn observe_deep<F>(&self, f: F) -> Subscription
576    where
577        F: Fn(&TransactionMut, &Events) + Send + Sync + 'static,
578    {
579        self.deep_observers.subscribe(Box::new(f))
580    }
581
582    #[cfg(not(feature = "sync"))]
583    pub fn observe_deep<F>(&self, f: F) -> Subscription
584    where
585        F: Fn(&TransactionMut, &Events) + 'static,
586    {
587        self.deep_observers.subscribe(Box::new(f))
588    }
589
590    #[cfg(feature = "sync")]
591    pub fn observe_deep_with<F>(&self, key: Origin, f: F)
592    where
593        F: Fn(&TransactionMut, &Events) + Send + Sync + 'static,
594    {
595        self.deep_observers.subscribe_with(key, Box::new(f))
596    }
597
598    #[cfg(not(feature = "sync"))]
599    pub fn observe_deep_with<F>(&self, key: Origin, f: F)
600    where
601        F: Fn(&TransactionMut, &Events) + 'static,
602    {
603        self.deep_observers.subscribe_with(key, Box::new(f))
604    }
605
606    pub(crate) fn is_parent_of(&self, mut ptr: Option<ItemPtr>) -> bool {
607        while let Some(i) = ptr.as_deref() {
608            if let Some(parent) = i.parent.as_branch() {
609                if parent.deref() == self {
610                    return true;
611                }
612                ptr = parent.item;
613            } else {
614                break;
615            }
616        }
617        false
618    }
619
620    pub(crate) fn make_event(&self, keys: HashSet<Option<Arc<str>>>) -> Option<Event> {
621        let self_ptr = BranchPtr::from(self);
622        let event = match self.type_ref() {
623            TypeRef::Array => Event::Array(ArrayEvent::new(self_ptr)),
624            TypeRef::Map => Event::Map(MapEvent::new(self_ptr, keys)),
625            TypeRef::Text => Event::Text(TextEvent::new(self_ptr)),
626            TypeRef::XmlElement(_) | TypeRef::XmlFragment => {
627                Event::XmlFragment(XmlEvent::new(self_ptr, keys))
628            }
629            TypeRef::XmlText => Event::XmlText(XmlTextEvent::new(self_ptr, keys)),
630            #[cfg(feature = "weak")]
631            TypeRef::WeakLink(_) => Event::Weak(crate::types::weak::WeakEvent::new(self_ptr)),
632            _ => return None,
633        };
634
635        Some(event)
636    }
637}
638
639pub(crate) struct Iter<'a, T> {
640    ptr: Option<&'a ItemPtr>,
641    _txn: &'a T,
642}
643
644impl<'a, T: ReadTxn> Iter<'a, T> {
645    fn new(ptr: Option<&'a ItemPtr>, txn: &'a T) -> Self {
646        Iter { ptr, _txn: txn }
647    }
648}
649
650impl<'a, T: ReadTxn> Iterator for Iter<'a, T> {
651    type Item = &'a Item;
652
653    fn next(&mut self) -> Option<Self::Item> {
654        let item = self.ptr.take()?;
655        self.ptr = item.right.as_ref();
656        Some(item)
657    }
658}
659
660/// A logical reference to a root-level shared collection. It can be shared across different
661/// documents to reference the same logical type.
662///
663/// # Example
664///
665/// ```rust
666/// use yrs::{Doc, RootRef, SharedRef, TextRef, Transact};
667///
668/// let root = TextRef::root("hello");
669///
670/// let doc1 = Doc::new();
671/// let txt1 = root.get_or_create(&mut doc1.transact_mut());
672///
673/// let doc2 = Doc::new();
674/// let txt2 = root.get_or_create(&mut doc2.transact_mut());
675///
676/// // instances of TextRef point to different heap objects
677/// assert_ne!(&txt1 as *const _, &txt2 as *const _);
678///
679/// // logical descriptors of both TextRef are the same as they refer to the
680/// // same logical entity
681/// assert_eq!(txt1.hook(), txt2.hook());
682/// ```
683#[repr(transparent)]
684#[derive(Debug, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]
685pub struct Root<S> {
686    /// Unique identifier of root-level shared collection.
687    pub name: Arc<str>,
688    _tag: PhantomData<S>,
689}
690
691impl<S: RootRef> Root<S> {
692    /// Creates a new logical reference for a root-level shared collection of a given name and type.
693    /// Returned value can be used to resolve instances of root-level types by calling [Root::get]
694    /// or [Root::get_or_create].
695    pub fn new<N: Into<Arc<str>>>(name: N) -> Self {
696        Root {
697            name: name.into(),
698            _tag: PhantomData::default(),
699        }
700    }
701
702    /// Returns a reference to a shared root-level collection current [Root] represents, or creates
703    /// it if it wasn't instantiated before.
704    pub fn get_or_create<T: WriteTxn>(&self, txn: &mut T) -> S {
705        let store = txn.store_mut();
706        let branch = store.get_or_create_type(self.name.clone(), S::type_ref());
707        S::from(branch)
708    }
709}
710
711impl<S: SharedRef> Root<S> {
712    /// Returns a reference to a shared collection current [Root] represents, or returns `None` if
713    /// that collection hasn't been instantiated yet.
714    pub fn get<T: ReadTxn>(&self, txn: &T) -> Option<S> {
715        txn.store().get_type(self.name.clone()).map(S::from)
716    }
717}
718
719impl<S> Into<BranchID> for Root<S> {
720    fn into(self) -> BranchID {
721        BranchID::Root(self.name)
722    }
723}
724
725/// A logical reference used to represent a shared collection nested within another one. Unlike
726/// [Root]-level types which cannot be deleted and exist eternally, [Nested] collections can be
727/// added (therefore don't exist prior their instantiation) and deleted (so that any [SharedRef]
728/// values referencing them become unsafe and can point to objects that no longer exists!).
729///
730/// Use [Nested::get] in order to materialize current nested logical reference into shared ref type.
731///
732/// # Example
733///
734/// ```rust
735/// use yrs::{Doc, Map, Nested, SharedRef, TextPrelim, TextRef, Transact, WriteTxn};
736///
737/// let doc = Doc::new();
738/// let mut txn = doc.transact_mut();
739/// let root = txn.get_or_insert_map("root"); // root-level collection
740/// let text = root.insert(&mut txn, "nested", TextPrelim::new("")); // nested collection
741///
742/// // convert nested TextRef into logical pointer
743/// let nested: Nested<TextRef> = text.hook().into_nested().unwrap();
744///
745/// // logical reference can be used to retrieve accessible TextRef when its alive
746/// assert_eq!(nested.get(&txn), Some(text));
747///
748/// // delete nested collection
749/// root.remove(&mut txn, "nested");
750///
751/// // logical reference cannot resolve shared collections that have been deleted already
752/// assert_eq!(nested.get(&txn), None);
753/// ```
754#[repr(transparent)]
755#[derive(Debug, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]
756pub struct Nested<S> {
757    pub id: ID,
758    _tag: PhantomData<S>,
759}
760
761impl<S> Nested<S> {
762    pub fn new(id: ID) -> Self {
763        Nested {
764            id,
765            _tag: PhantomData::default(),
766        }
767    }
768}
769
770impl<S: SharedRef> Nested<S> {
771    /// If current [Nested] logical reference points to an instantiated and not-deleted shared
772    /// collection, a reference to that collection will be returned.
773    /// If the referenced collection has been deleted or was not yet present in current transaction
774    /// scope i.e. due to missing update, a `None` will be returned.  
775    pub fn get<T: ReadTxn>(&self, txn: &T) -> Option<S> {
776        let store = txn.store();
777        let block = store.blocks.get_block(&self.id)?;
778        if let BlockCell::Block(block) = block {
779            if let ItemContent::Type(branch) = &block.content {
780                if let Some(ptr) = branch.item {
781                    if !ptr.is_deleted() {
782                        return Some(S::from(BranchPtr::from(&*branch)));
783                    }
784                }
785            }
786        }
787        None
788    }
789}
790
791impl<S> Into<BranchID> for Nested<S> {
792    fn into(self) -> BranchID {
793        BranchID::Nested(self.id)
794    }
795}
796
797/// A descriptor used to reference to shared collections by their unique logical identifiers,
798/// which can be either [Root]-level collections or shared collections [Nested] into each other.
799/// It can be resolved from any shared reference using [SharedRef::hook].
800#[derive(Clone, Serialize, Deserialize)]
801pub struct Hook<S> {
802    id: BranchID,
803    _tag: PhantomData<S>,
804}
805
806impl<S> Hook<S> {
807    /// Unique logical identifier of a shared collection.
808    #[inline]
809    pub fn id(&self) -> &BranchID {
810        &self.id
811    }
812}
813
814impl<S> std::fmt::Debug for Hook<S> {
815    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
816        write!(f, "{:?}", self.id)
817    }
818}
819
820impl<S> Eq for Hook<S> {}
821
822impl<S> PartialEq for Hook<S> {
823    fn eq(&self, other: &Self) -> bool {
824        self.id == other.id
825    }
826}
827
828impl<S> Hash for Hook<S> {
829    fn hash<H: Hasher>(&self, state: &mut H) {
830        self.id.hash(state)
831    }
832}
833
834impl<S: SharedRef> Hook<S> {
835    /// Returns a reference to a shared collection current hook points to, if it exists and
836    /// (in case of nested collections) has not been deleted.
837    ///
838    /// # Example
839    ///
840    /// ```rust
841    /// use yrs::{Hook, Doc, Map, MapRef, Nested, SharedRef, TextPrelim, TextRef, Transact, WriteTxn};
842    ///
843    /// let doc = Doc::new();
844    /// let mut txn = doc.transact_mut();
845    /// let root = txn.get_or_insert_map("root"); // root-level collection
846    /// let nested = root.insert(&mut txn, "nested", TextPrelim::new("")); // nested collection
847    ///
848    /// let root_hook: Hook<MapRef> = root.hook();
849    /// let nested_hook: Hook<TextRef> = nested.hook();
850    ///
851    /// // hook can be used to retrieve collection reference as long as its alive
852    /// assert_eq!(nested_hook.get(&txn), Some(nested));
853    ///
854    /// // after nested collection is deleted it can no longer be referenced
855    /// root.remove(&mut txn, "nested");
856    /// assert_eq!(nested_hook.get(&txn), None, "wtf");
857    ///
858    /// // descriptors work also for root types
859    /// assert_eq!(root_hook.get(&txn), Some(root));
860    /// ```
861    pub fn get<T: ReadTxn>(&self, txn: &T) -> Option<S> {
862        let branch = self.id.get_branch(txn)?;
863        match branch.item {
864            Some(ptr) if ptr.is_deleted() => None,
865            _ => Some(S::from(branch)),
866        }
867    }
868
869    /// Attempts to convert current [Hook] type into [Nested] one.
870    /// Returns `None` if current descriptor doesn't reference a nested shared collection.  
871    pub fn into_nested(self) -> Option<Nested<S>> {
872        match self.id {
873            BranchID::Nested(id) => Some(Nested::new(id)),
874            BranchID::Root(_) => None,
875        }
876    }
877}
878
879impl<S: RootRef> Hook<S> {
880    /// Attempts to convert current [Hook] type into [Root] one.
881    /// Returns `None` if current descriptor doesn't reference a root-level shared collection.
882    pub fn into_root(self) -> Option<Root<S>> {
883        match self.id {
884            BranchID::Root(name) => Some(Root::new(name)),
885            BranchID::Nested(_) => None,
886        }
887    }
888}
889
890impl<S> From<Root<S>> for Hook<S> {
891    fn from(root: Root<S>) -> Self {
892        Hook {
893            id: root.into(),
894            _tag: PhantomData::default(),
895        }
896    }
897}
898
899impl<S> From<Nested<S>> for Hook<S> {
900    fn from(nested: Nested<S>) -> Self {
901        Hook {
902            id: nested.into(),
903            _tag: PhantomData::default(),
904        }
905    }
906}
907
908impl<S> From<BranchID> for Hook<S> {
909    fn from(id: BranchID) -> Self {
910        Hook {
911            id,
912            _tag: PhantomData::default(),
913        }
914    }
915}
916
917impl<S> Into<BranchID> for Hook<S> {
918    fn into(self) -> BranchID {
919        self.id
920    }
921}
922
923/// An unique logical identifier of a shared collection. Can be shared across document boundaries
924/// to reference to the same logical entity across different replicas of a document.
925#[derive(Clone, Ord, PartialOrd, Eq, PartialEq, Hash, Serialize, Deserialize)]
926pub enum BranchID {
927    Nested(ID),
928    Root(Arc<str>),
929}
930
931impl BranchID {
932    #[inline]
933    pub fn get_root<T: ReadTxn, K: Borrow<str>>(txn: &T, name: K) -> Option<BranchPtr> {
934        txn.store().get_type(name)
935    }
936
937    pub fn get_nested<T: ReadTxn>(txn: &T, id: &ID) -> Option<BranchPtr> {
938        let block = txn.store().blocks.get_block(id)?;
939        if let BlockCell::Block(block) = block {
940            if let ItemContent::Type(branch) = &block.content {
941                return Some(BranchPtr::from(&*branch));
942            }
943        }
944        None
945    }
946
947    pub fn get_branch<T: ReadTxn>(&self, txn: &T) -> Option<BranchPtr> {
948        match self {
949            BranchID::Root(name) => Self::get_root(txn, name.as_ref()),
950            BranchID::Nested(id) => Self::get_nested(txn, id),
951        }
952    }
953}
954
955impl std::fmt::Debug for BranchID {
956    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
957        match self {
958            BranchID::Nested(id) => write!(f, "{}", id),
959            BranchID::Root(name) => write!(f, "'{}'", name),
960        }
961    }
962}
yrs/branch.rs

yrs/
branch.rs
