pub struct TextRef(/* private fields */);
Expand description
A shared data type used for collaborative text editing. 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.
TextRef 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, TextRef 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.
TextRef 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 TextRef.
Keep in mind that TextRef::get_string method returns a raw string, stripped of formatting attributes or embedded objects. If there’s a need to include them, use TextRef::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 TextRef, invalidating numeric index. For such cases you can take advantage of fact that TextRef 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};
use yrs::types::Attrs;
use yrs::types::text::{Diff, YChange};
let doc = Doc::new();
let text = doc.get_or_insert_text("article");
let mut txn = doc.transact_mut();
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.clone());
text.format(&mut txn, 0, 5, bold.clone());
let chunks = text.diff(&txn, YChange::identity);
assert_eq!(chunks, vec![
Diff::new("hello".into(), Some(Box::new(bold.clone()))),
Diff::new(" ".into(), None),
Diff::new("world".into(), Some(Box::new(italic))),
]);
// remove formatting
let remove_italic = Attrs::from([("i".into(), Any::Null)]);
text.format(&mut txn, 6, 5, remove_italic);
let chunks = text.diff(&txn, YChange::identity);
assert_eq!(chunks, vec![
Diff::new("hello".into(), Some(Box::new(bold.clone()))),
Diff::new(" world".into(), None),
]);
// 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 DeepObservable for TextRef
impl DeepObservable for TextRef
source§fn observe_deep<F>(&self, f: F) -> Subscription
fn observe_deep<F>(&self, f: F) -> Subscription
source§impl GetString for TextRef
impl GetString for TextRef
source§fn get_string<T: ReadTxn>(&self, _txn: &T) -> String
fn get_string<T: ReadTxn>(&self, _txn: &T) -> String
Converts context of this text data structure into a single string value. This method doesn’t render formatting attributes or embedded content. In order to retrieve it, use TextRef::diff method.
source§impl IndexedSequence for TextRef
impl IndexedSequence for TextRef
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 TextRef
impl Observable for TextRef
type Event = TextEvent
source§fn observe<F>(&self, f: F) -> Subscription
fn observe<F>(&self, f: F) -> Subscription
source§impl PartialEq for TextRef
impl PartialEq for TextRef
source§impl Text for TextRef
impl Text for TextRef
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.