Struct yrs::types::xml::XmlTextRef
source · pub struct XmlTextRef(/* private fields */);
Expand description
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§
source§impl AsRef<Branch> for XmlTextRef
impl AsRef<Branch> for XmlTextRef
source§impl Clone for XmlTextRef
impl Clone for XmlTextRef
source§fn clone(&self) -> XmlTextRef
fn clone(&self) -> XmlTextRef
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for XmlTextRef
impl Debug for XmlTextRef
source§impl DeepObservable for XmlTextRef
impl DeepObservable for XmlTextRef
source§fn observe_deep<F>(&self, f: F) -> Subscription
fn observe_deep<F>(&self, f: F) -> Subscription
source§impl From<BranchPtr> for XmlTextRef
impl From<BranchPtr> for XmlTextRef
source§impl GetString for XmlTextRef
impl GetString for XmlTextRef
source§impl IndexedSequence for XmlTextRef
impl IndexedSequence for XmlTextRef
source§fn sticky_index(
&self,
txn: &mut TransactionMut<'_>,
index: u32,
assoc: Assoc
) -> Option<StickyIndex>
fn sticky_index( &self, txn: &mut TransactionMut<'_>, index: u32, assoc: Assoc ) -> Option<StickyIndex>
index
.
Returns None
if index
is beyond the length of current sequence.source§impl Into<TextRef> for XmlTextRef
impl Into<TextRef> for XmlTextRef
source§impl Into<XmlTextRef> for TextRef
impl Into<XmlTextRef> for TextRef
source§fn into(self) -> XmlTextRef
fn into(self) -> XmlTextRef
source§impl Observable for XmlTextRef
impl Observable for XmlTextRef
type Event = XmlTextEvent
source§fn observe<F>(&self, f: F) -> Subscription
fn observe<F>(&self, f: F) -> Subscription
source§impl PartialEq for XmlTextRef
impl PartialEq for XmlTextRef
source§impl Text for XmlTextRef
impl Text for XmlTextRef
source§fn len<T: ReadTxn>(&self, _txn: &T) -> u32
fn len<T: ReadTxn>(&self, _txn: &T) -> u32
source§fn insert(&self, txn: &mut TransactionMut<'_>, index: u32, chunk: &str)
fn insert(&self, txn: &mut TransactionMut<'_>, index: u32, chunk: &str)
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. Read moresource§fn insert_with_attributes(
&self,
txn: &mut TransactionMut<'_>,
index: u32,
chunk: &str,
attributes: Attrs
)
fn insert_with_attributes( &self, txn: &mut TransactionMut<'_>, index: u32, chunk: &str, attributes: Attrs )
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. Read moresource§fn insert_embed<V>(
&self,
txn: &mut TransactionMut<'_>,
index: u32,
content: V
) -> V::Return
fn insert_embed<V>( &self, txn: &mut TransactionMut<'_>, index: u32, content: V ) -> V::Return
source§fn insert_embed_with_attributes<V>(
&self,
txn: &mut TransactionMut<'_>,
index: u32,
embed: V,
attributes: Attrs
) -> V::Return
fn insert_embed_with_attributes<V>( &self, txn: &mut TransactionMut<'_>, index: u32, embed: V, attributes: Attrs ) -> V::Return
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. Read moresource§fn push(&self, txn: &mut TransactionMut<'_>, chunk: &str)
fn push(&self, txn: &mut TransactionMut<'_>, chunk: &str)
chunk
of text at the end of a current text structure.source§fn remove_range(&self, txn: &mut TransactionMut<'_>, index: u32, len: u32)
fn remove_range(&self, txn: &mut TransactionMut<'_>, index: u32, len: u32)
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.source§fn format(
&self,
txn: &mut TransactionMut<'_>,
index: u32,
len: u32,
attributes: Attrs
)
fn format( &self, txn: &mut TransactionMut<'_>, index: u32, len: u32, attributes: Attrs )
index
-len
parameters with
formatting blocks containing provided attributes
metadata.source§fn diff<T, D, F>(&self, _txn: &T, compute_ychange: F) -> Vec<Diff<D>>
fn diff<T, D, F>(&self, _txn: &T, compute_ychange: F) -> Vec<Diff<D>>
source§impl TryFrom<ItemPtr> for XmlTextRef
impl TryFrom<ItemPtr> for XmlTextRef
source§impl TryFrom<Value> for XmlTextRef
impl TryFrom<Value> for XmlTextRef
source§impl TryInto<XmlTextRef> for XmlNode
impl TryInto<XmlTextRef> for XmlNode
source§impl Xml for XmlTextRef
impl Xml for XmlTextRef
fn parent(&self) -> Option<XmlNode>
source§fn remove_attribute<K>(&self, txn: &mut TransactionMut<'_>, attr_name: &K)
fn remove_attribute<K>(&self, txn: &mut TransactionMut<'_>, attr_name: &K)
attr_name
from a current XML element.source§fn insert_attribute<K, V>(
&self,
txn: &mut TransactionMut<'_>,
attr_name: K,
attr_value: V
)
fn insert_attribute<K, V>( &self, txn: &mut TransactionMut<'_>, attr_name: K, attr_value: V )
source§fn get_attribute<T: ReadTxn>(&self, txn: &T, attr_name: &str) -> Option<String>
fn get_attribute<T: ReadTxn>(&self, txn: &T, attr_name: &str) -> Option<String>
attr_name
. Returns None
if no such attribute
can be found inside of a current XML element.