Struct LoroText

pub struct LoroText { /* private fields */ }

LoroText container. It’s used to model plaintext/richtext.

Implementations

impl LoroText

pub fn new() -> Self

Create a new container that is detached from the document.

The edits on a detached container will not be persisted. To attach the container to the document, please insert it into an attached container.

pub fn is_attached(&self) -> bool

Whether the container is attached to a document

The edits on a detached container will not be persisted. To attach the container to the document, please insert it into an attached container.

pub fn iter(&self, callback: impl FnMut(&str) -> bool)

Iterate each span(internal storage unit) of the text.

The callback function will be called for each character in the text. If the callback returns false, the iteration will stop.

Limitation: you cannot access or alter the doc state when iterating. If you need to access or alter the doc state, please use to_string instead.

pub fn insert(&self, pos: usize, s: &str) -> LoroResult<()>

Insert a string at the given unicode position.

pub fn insert_utf8(&self, pos: usize, s: &str) -> LoroResult<()>

Insert a string at the given utf-8 position.

pub fn delete(&self, pos: usize, len: usize) -> LoroResult<()>

Delete a range of text at the given unicode position with unicode length.

pub fn delete_utf8(&self, pos: usize, len: usize) -> LoroResult<()>

Delete a range of text at the given utf-8 position with utf-8 length.

pub fn slice(&self, start_index: usize, end_index: usize) -> LoroResult<String>

Get a string slice at the given Unicode range

pub fn char_at(&self, pos: usize) -> LoroResult<char>

Get the characters at given unicode position.

pub fn splice(&self, pos: usize, len: usize, s: &str) -> LoroResult<String>

Delete specified character and insert string at the same position at given unicode position.

pub fn is_empty(&self) -> bool

Whether the text container is empty.

pub fn len_utf8(&self) -> usize

Get the length of the text container in UTF-8.

pub fn len_unicode(&self) -> usize

Get the length of the text container in Unicode.

pub fn len_utf16(&self) -> usize

Get the length of the text container in UTF-16.

pub fn update( &self, text: &str, options: UpdateOptions, ) -> Result<(), UpdateTimeoutError>

Update the current text based on the provided text.

It will calculate the minimal difference and apply it to the current text. It uses Myers’ diff algorithm to compute the optimal difference.

This could take a long time for large texts (e.g. > 50_000 characters). In that case, you should use updateByLine instead.

Example

use loro::LoroDoc;

let doc = LoroDoc::new();
let text = doc.get_text("text");
text.insert(0, "Hello").unwrap();
text.update("Hello World", Default::default()).unwrap();
assert_eq!(text.to_string(), "Hello World");

pub fn update_by_line( &self, text: &str, options: UpdateOptions, ) -> Result<(), UpdateTimeoutError>

Update the current text based on the provided text.

This update calculation is line-based, which will be more efficient but less precise.

pub fn apply_delta(&self, delta: &[TextDelta]) -> LoroResult<()>

Apply a delta to the text container.

pub fn mark( &self, range: Range<usize>, key: &str, value: impl Into<LoroValue>, ) -> LoroResult<()>

Mark a range of text with a key-value pair.

You can use it to create a highlight, make a range of text bold, or add a link to a range of text.

You can specify the expand option to set the behavior when inserting text at the boundary of the range.

• after(default): when inserting text right after the given range, the mark will be expanded to include the inserted text
• before: when inserting text right before the given range, the mark will be expanded to include the inserted text
• none: the mark will not be expanded to include the inserted text at the boundaries
• both: when inserting text either right before or right after the given range, the mark will be expanded to include the inserted text

You should make sure that a key is always associated with the same expand type.

pub fn unmark(&self, range: Range<usize>, key: &str) -> LoroResult<()>

Unmark a range of text with a key and a value.

You can use it to remove highlights, bolds or links

You can specify the expand option to set the behavior when inserting text at the boundary of the range.

Note: You should specify the same expand type as when you mark the text.

• after(default): when inserting text right after the given range, the mark will be expanded to include the inserted text
• before: when inserting text right before the given range, the mark will be expanded to include the inserted text
• none: the mark will not be expanded to include the inserted text at the boundaries
• both: when inserting text either right before or right after the given range, the mark will be expanded to include the inserted text

You should make sure that a key is always associated with the same expand type.

Note: you cannot delete unmergeable annotations like comments by this method.

pub fn to_delta(&self) -> Vec<TextDelta>

Get the text in Delta format.

Example

use loro::{LoroDoc, ToJson, ExpandType, TextDelta};
use serde_json::json;
use fxhash::FxHashMap;

let doc = LoroDoc::new();
let text = doc.get_text("text");
text.insert(0, "Hello world!").unwrap();
text.mark(0..5, "bold", true).unwrap();
assert_eq!(
    text.to_delta(),
    vec![
        TextDelta::Insert {
            insert: "Hello".to_string(),
            attributes: Some(FxHashMap::from_iter([("bold".to_string(), true.into())])),
        },
        TextDelta::Insert {
            insert: " world!".to_string(),
            attributes: None,
        },
    ]
);
text.unmark(3..5, "bold").unwrap();
assert_eq!(
    text.to_delta(),
    vec![
        TextDelta::Insert {
            insert: "Hel".to_string(),
            attributes: Some(FxHashMap::from_iter([("bold".to_string(), true.into())])),
        },
        TextDelta::Insert {
            insert: "lo world!".to_string(),
            attributes: None,
        },
    ]
);

pub fn get_richtext_value(&self) -> LoroValue

Get the rich text value in Delta format.

Example

let doc = LoroDoc::new();
let text = doc.get_text("text");
text.insert(0, "Hello world!").unwrap();
text.mark(0..5, "bold", true).unwrap();
assert_eq!(
    text.get_richtext_value().to_json_value(),
    json!([
        { "insert": "Hello", "attributes": {"bold": true} },
        { "insert": " world!" },
    ])
);
text.unmark(3..5, "bold").unwrap();
assert_eq!(
    text.get_richtext_value().to_json_value(),
    json!([
        { "insert": "Hel", "attributes": {"bold": true} },
        { "insert": "lo world!" },
   ])
);

pub fn to_string(&self) -> String

Get the text content of the text container.

pub fn get_cursor(&self, pos: usize, side: Side) -> Option<Cursor>

Get the cursor at the given position in the given Unicode position.

Using “index” to denote cursor positions can be unstable, as positions may shift with document edits. To reliably represent a position or range within a document, it is more effective to leverage the unique ID of each item/character in a List CRDT or Text CRDT.

Loro optimizes State metadata by not storing the IDs of deleted elements. This approach complicates tracking cursors since they rely on these IDs. The solution recalculates position by replaying relevant history to update stable positions accurately. To minimize the performance impact of history replay, the system updates cursor info to reference only the IDs of currently present elements, thereby reducing the need for replay.

Example

let doc = LoroDoc::new();
let text = &doc.get_text("text");
text.insert(0, "01234").unwrap();
let pos = text.get_cursor(5, Default::default()).unwrap();
assert_eq!(doc.get_cursor_pos(&pos).unwrap().current.pos, 5);
text.insert(0, "01234").unwrap();
assert_eq!(doc.get_cursor_pos(&pos).unwrap().current.pos, 10);
text.delete(0, 10).unwrap();
assert_eq!(doc.get_cursor_pos(&pos).unwrap().current.pos, 0);
text.insert(0, "01234").unwrap();
assert_eq!(doc.get_cursor_pos(&pos).unwrap().current.pos, 5);

pub fn is_deleted(&self) -> bool

Whether the text container is deleted.

pub fn push_str(&self, s: &str) -> LoroResult<()>

Push a string to the end of the text container.

pub fn get_editor_at_unicode_pos(&self, pos: usize) -> Option<PeerID>

Get the editor of the text at the given position.

Trait Implementations

impl Clone for LoroText

fn clone(&self) -> LoroText

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ContainerTrait for LoroText

type Handler = TextHandler

The handler of the container.

fn id(&self) -> ContainerID

Get the ID of the container.

fn to_container(&self) -> Container

Convert the container to a Container.

fn to_handler(&self) -> Self::Handler

Convert the container to a handler.

fn from_handler(handler: Self::Handler) -> Self

Convert the handler to a container.

fn is_attached(&self) -> bool

Whether the container is attached to a document.

fn get_attached(&self) -> Option<Self>

If a detached container is attached, this method will return its corresponding attached handler.

fn try_from_container(container: Container) -> Option<Self>

Try to convert the container to the handler.

fn is_deleted(&self) -> bool

Whether the container is deleted.

fn doc(&self) -> Option<LoroDoc>

Get the doc of the container.

fn subscribe(&self, callback: Subscriber) -> Option<Subscription>

Subscribe to the container.

impl Debug for LoroText

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

Formats the value using the given formatter.

impl Default for LoroText

fn default() -> Self

Returns the “default value” for a type.