Trait Text 

pub trait Text: Sized + AsRef<Branch> {
    // Provided methods
    fn len<T>(&self, _txn: &T) -> u32
       where T: ReadTxn { ... }
    fn insert(&self, txn: &mut TransactionMut<'_>, index: u32, chunk: &str) { ... }
    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>,
    ) { ... }
    fn insert_embed<V>(
        &self,
        txn: &mut TransactionMut<'_>,
        index: u32,
        content: V,
    ) -> <V as Prelim>::Return
       where V: Into<EmbedPrelim<V>> + Prelim { ... }
    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 { ... }
    fn push(&self, txn: &mut TransactionMut<'_>, chunk: &str) { ... }
    fn remove_range(&self, txn: &mut TransactionMut<'_>, index: u32, len: u32) { ... }
    fn format(
        &self,
        txn: &mut TransactionMut<'_>,
        index: u32,
        len: u32,
        attributes: HashMap<Arc<str>, Any>,
    ) { ... }
    fn diff<T, D, F>(&self, _txn: &T, compute_ychange: F) -> Vec<Diff<D>>
       where T: ReadTxn,
             F: Fn(YChange) -> D { ... }
    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 { ... }
}

Provided Methods

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.

This method will panic if provided index is greater than the length of a current text.

Examples

By default Document uses byte offset:

use yrs::{Doc, Text, GetString, Transact};

let doc = Doc::new();
let ytext = doc.get_or_insert_text("text");
let txn = &mut doc.transact_mut();
ytext.push(txn, "Hi ★ to you");

// The same as `String::len()`
assert_eq!(ytext.len(txn), 13);

// To insert you have to count bytes and not chars.
ytext.insert(txn, 6, "!");
assert_eq!(ytext.get_string(txn), "Hi ★! to you");

You can override how Yrs calculates the index with OffsetKind:

use yrs::{Doc, Options, Text, GetString, Transact, OffsetKind};

let doc = Doc::with_options(Options {
    offset_kind: OffsetKind::Utf16,
    ..Default::default()
});
let ytext = doc.get_or_insert_text("text");
let txn = &mut doc.transact_mut();
ytext.push(txn, "Hi ★ to you");

// The same as `String::chars()::count()`
assert_eq!(ytext.len(txn), 11);

// To insert you have to count chars.
ytext.insert(txn, 4, "!");
assert_eq!(ytext.get_string(txn), "Hi ★! to you");

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.

This method will panic if provided index is greater than the length of a current text.

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.

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 embed will be appended at the end of it.

This method will panic if provided index is greater than the length of a current text.

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.

This method will panic if provided index is greater than the length of a current text.

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.

compute_ychange callback is used to attach custom data to produced chunks.

Example

use yrs::{Doc, 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_with_attributes(&mut txn, 0, "hello world", italic.clone()); // "<i>hello world</i>"
text.format(&mut txn, 6, 5, bold.clone()); // "<i>hello <b>world</b></i>"
let image = vec![0, 0, 0, 0];
text.insert_embed(&mut txn, 5, image.clone()); // insert binary after "hello"

let italic_and_bold = Attrs::from([
  ("b".into(), true.into()),
  ("i".into(), true.into())
]);
let chunks = text.diff(&txn, YChange::identity);
assert_eq!(chunks, vec![
    Diff::new("hello".into(), Some(Box::new(italic.clone()))),
    Diff::new(image.into(), Some(Box::new(italic.clone()))),
    Diff::new(" ".into(), Some(Box::new(italic))),
    Diff::new("world".into(), Some(Box::new(italic_and_bold))),
]);

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.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Text for TextRef

impl Text for XmlTextRef