Struct XmlTextRef 

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

A shared data type used for collaborative text editing, that can be used in a context of XmlElementRef node. It enables multiple users to add and remove chunks of text in efficient manner. This type is internally represented as a mutable double-linked list of text chunks

• an optimization occurs during [Transaction::commit], which allows to squash multiple consecutively inserted characters together as a single chunk of text even between transaction boundaries in order to preserve more efficient memory model.

Just like XmlElementRef, XmlTextRef can be marked with extra metadata in form of attributes.

XmlTextRef structure internally uses UTF-8 encoding and its length is described in a number of bytes rather than individual characters (a single UTF-8 code point can consist of many bytes).

Like all Yrs shared data types, XmlTextRef is resistant to the problem of interleaving (situation when characters inserted one after another may interleave with other peers concurrent inserts after merging all updates together). In case of Yrs conflict resolution is solved by using unique document id to determine correct and consistent ordering.

XmlTextRef offers a rich text editing capabilities (it’s not limited to simple text operations). Actions like embedding objects, binaries (eg. images) and formatting attributes are all possible using XmlTextRef.

Keep in mind that XmlTextRef::get_string method returns a raw string, while rendering formatting attrbitues as XML tags in-text. However it doesn’t include embedded elements. If there’s a need to include them, use XmlTextRef::diff method instead.

Another note worth reminding is that human-readable numeric indexes are not good for maintaining cursor positions in rich text documents with real-time collaborative capabilities. In such cases any concurrent update incoming and applied from the remote peer may change the order of elements in current XmlTextRef, invalidating numeric index. For such cases you can take advantage of fact that XmlTextRef implements IndexedSequence::sticky_index method that returns a permanent index position that sticks to the same place even when concurrent updates are being made.

Example

use yrs::{Any, Array, ArrayPrelim, Doc, GetString, Text, Transact, WriteTxn, XmlFragment, XmlTextPrelim};
use yrs::types::Attrs;

let doc = Doc::new();
let mut txn = doc.transact_mut();
let f = txn.get_or_insert_xml_fragment("article");
let text = f.insert(&mut txn, 0, XmlTextPrelim::new(""));

let bold = Attrs::from([("b".into(), true.into())]);
let italic = Attrs::from([("i".into(), true.into())]);

text.insert(&mut txn, 0, "hello ");
text.insert_with_attributes(&mut txn, 6, "world", italic);
text.format(&mut txn, 0, 5, bold);

assert_eq!(text.get_string(&txn), "<b>hello</b> <i>world</i>");

// remove formatting
let remove_italic = Attrs::from([("i".into(), Any::Null)]);
text.format(&mut txn, 6, 5, remove_italic);

assert_eq!(text.get_string(&txn), "<b>hello</b> world");

// insert binary payload eg. images
let image = b"deadbeaf".to_vec();
text.insert_embed(&mut txn, 1, image);

// insert nested shared type eg. table as ArrayRef of ArrayRefs
let table = text.insert_embed(&mut txn, 5, ArrayPrelim::default());
let header = table.insert(&mut txn, 0, ArrayPrelim::from(["Book title", "Author"]));
let row = table.insert(&mut txn, 1, ArrayPrelim::from(["\"Moby-Dick\"", "Herman Melville"]));

Trait Implementations

impl AsPrelim for XmlTextRef

type Prelim = XmlDeltaPrelim

fn as_prelim<T>(&self, txn: &T) -> <XmlTextRef 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 XmlTextRef

fn as_ref(&self) -> &Branch

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

impl AsRef<TextRef> for XmlTextRef

fn as_ref(&self) -> &TextRef

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

impl AsRef<XmlTextRef> for TextRef

fn as_ref(&self) -> &XmlTextRef

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

impl Clone for XmlTextRef

fn clone(&self) -> XmlTextRef

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for XmlTextRef

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

Formats the value using the given formatter.

impl DeepObservable for XmlTextRef

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 XmlTextRef

type Prelim = XmlTextPrelim

fn default_prelim() -> <XmlTextRef 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 XmlTextRef

fn from(inner: BranchPtr) -> XmlTextRef

Converts to this type from the input type.

impl GetString for XmlTextRef

fn get_string<T>(&self, _txn: &T) -> String

where T: ReadTxn,

Displays the content of a current collection in string format.

impl IndexedSequence for XmlTextRef

fn sticky_index<T>( &self, txn: &T, index: u32, assoc: Assoc, ) -> Option<StickyIndex>

where T: ReadTxn,

Returns a StickyIndex equivalent to a human-readable index. Returns None if index is beyond the length of current sequence.

impl Observable for XmlTextRef

type Event = XmlTextEvent

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 XmlTextRef

fn eq(&self, other: &XmlTextRef) -> 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 SharedRef for XmlTextRef

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

Returns a logical descriptor of a current shared collection.

impl Text for XmlTextRef

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

where T: ReadTxn,

Returns a number of characters visible in a current text data structure.

fn insert(&self, txn: &mut TransactionMut<'_>, index: u32, chunk: &str)

Inserts a chunk of text at a given index. If index is 0, this chunk will be inserted at the beginning of a current text. If index is equal to current data structure length, this chunk will be appended at the end of it.

fn apply_delta<D, P>(&self, txn: &mut TransactionMut<'_>, delta: D)

where D: IntoIterator<Item = Delta<P>>, P: Prelim,

fn insert_with_attributes( &self, txn: &mut TransactionMut<'_>, index: u32, chunk: &str, attributes: HashMap<Arc<str>, Any>, )

Inserts a chunk of text at a given index. If index is 0, this chunk will be inserted at the beginning of a current text. If index is equal to current data structure length, this chunk will be appended at the end of it. Collection of supplied attributes will be used to wrap provided text chunk range with a formatting blocks.

fn insert_embed<V>( &self, txn: &mut TransactionMut<'_>, index: u32, content: V, ) -> <V as Prelim>::Return

where V: Into<EmbedPrelim<V>> + Prelim,

Inserts an embed content at a given index.

fn insert_embed_with_attributes<V>( &self, txn: &mut TransactionMut<'_>, index: u32, embed: V, attributes: HashMap<Arc<str>, Any>, ) -> <V as Prelim>::Return

where V: Into<EmbedPrelim<V>> + Prelim,

Inserts an embed content of text at a given index. If index is 0, this content will be inserted at the beginning of a current text. If index is equal to current data structure length, this chunk will be appended at the end of it. Collection of supplied attributes will be used to wrap provided text content range with a formatting blocks.

fn push(&self, txn: &mut TransactionMut<'_>, chunk: &str)

Appends a given chunk of text at the end of a current text structure.

fn remove_range(&self, txn: &mut TransactionMut<'_>, index: u32, len: u32)

Removes up to a len characters from a current text structure, starting at given index. This method panics in case when not all expected characters were removed (due to insufficient number of characters to remove) or index is outside of the bounds of text.

fn format( &self, txn: &mut TransactionMut<'_>, index: u32, len: u32, attributes: HashMap<Arc<str>, Any>, )

Wraps an existing piece of text within a range described by index-len parameters with formatting blocks containing provided attributes metadata.

fn diff<T, D, F>(&self, _txn: &T, compute_ychange: F) -> Vec<Diff<D>>

where T: ReadTxn, F: Fn(YChange) -> D,

Returns an ordered sequence of formatted chunks, current Text corresponds of. These chunks may contain inserted pieces of text or more complex elements like embedded binaries of shared objects. Chunks are organized by type of inserted value and formatting attributes wrapping it around. If formatting attributes are nested into each other, they will be split into separate Diff chunks.

fn diff_range<D, F>( &self, txn: &mut TransactionMut<'_>, hi: Option<&Snapshot>, lo: Option<&Snapshot>, compute_ychange: F, ) -> Vec<Diff<D>>

where F: Fn(YChange) -> D,

Returns the Delta representation of this YText type.

impl TryFrom<ItemPtr> for XmlTextRef

type Error = ItemPtr

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Out> for XmlTextRef

type Error = Out

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryInto<XmlTextRef> for XmlOut

type Error = XmlOut

The type returned in the event of a conversion error.

fn try_into(self) -> Result<XmlTextRef, <XmlOut as TryInto<XmlTextRef>>::Error>

Performs the conversion.

impl Xml for XmlTextRef

fn parent(&self) -> Option<XmlOut>

fn remove_attribute<K>(&self, txn: &mut TransactionMut<'_>, attr_name: &K)

where K: AsRef<str>,

Removes an attribute recognized by an attr_name from a current XML element.

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

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

Inserts an attribute entry into current XML element.

fn get_attribute<T>(&self, txn: &T, attr_name: &str) -> Option<Out>

where T: ReadTxn,

Returns a value of an attribute given its attr_name. Returns None if no such attribute can be found inside of a current XML element.

fn attributes<'a, T>(&'a self, txn: &'a T) -> Attributes<'a, &'a T, T>

where T: ReadTxn,

Returns an unordered iterator over all attributes (key-value pairs), that can be found inside of a current XML element.

fn siblings<'a, T>(&self, txn: &'a T) -> Siblings<'a, T>

where T: ReadTxn,

impl Eq for XmlTextRef