Struct TextRef 

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

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

impl AsPrelim for TextRef

type Prelim = DeltaPrelim

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

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 TextRef

fn clone(&self) -> TextRef

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TextRef

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

Formats the value using the given formatter.

impl DeepObservable for TextRef

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 TextRef

type Prelim = TextPrelim

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

fn from(inner: BranchPtr) -> TextRef

Converts to this type from the input type.

impl GetString for TextRef

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

where T: ReadTxn,

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.

impl IndexedSequence for TextRef

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 TextRef

type Event = TextEvent

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 TextRef

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

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 TextRef

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

Returns a logical descriptor of a current shared collection.

impl Text for TextRef

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 TextRef

type Error = ItemPtr

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Out> for TextRef

type Error = Out

The type returned in the event of a conversion error.

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

Performs the conversion.

impl Eq for TextRef