Trait yrs::types::text::Text

source · 
pub trait Text: AsRef<Branch> + Sized {
    // Provided methods
    fn len<T: ReadTxn>(&self, _txn: &T) -> u32 { ... }
    fn insert(&self, txn: &mut TransactionMut<'_>, index: u32, chunk: &str) { ... }
    fn insert_with_attributes(
        &self,
        txn: &mut TransactionMut<'_>,
        index: u32,
        chunk: &str,
        attributes: Attrs
    ) { ... }
    fn insert_embed<V>(
        &self,
        txn: &mut TransactionMut<'_>,
        index: u32,
        content: V
    ) -> V::Return
       where V: Into<EmbedPrelim<V>> + Prelim { ... }
    fn insert_embed_with_attributes<V>(
        &self,
        txn: &mut TransactionMut<'_>,
        index: u32,
        embed: V,
        attributes: Attrs
    ) -> V::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: Attrs
    ) { ... }
    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§

source

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

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

source

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");
source

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

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.

source

fn insert_embed<V>( &self, txn: &mut TransactionMut<'_>, index: u32, content: V ) -> V::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.

source

fn insert_embed_with_attributes<V>( &self, txn: &mut TransactionMut<'_>, index: u32, embed: V, attributes: Attrs ) -> V::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.

source

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

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

source

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.

source

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

Wraps an existing piece of text within a range described by 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>>
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))),
]);
source

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.

Object Safety§

This trait is not object safe.

Implementors§