Struct loro::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 id(&self) -> ContainerID

Get the ContainerID of the text container.

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

Insert a string at the given unicode 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 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 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.

Note: this is not suitable for unmergeable annotations like comments.

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) -> LoroValue

Get the text 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.to_delta().to_json_value(),
    json!([
        { "insert": "Hello", "attributes": {"bold": true} },
        { "insert": " world!" },
    ])
);
text.unmark(3..5, "bold").unwrap();
assert_eq!(
    text.to_delta().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.

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

Trait Implementations

impl Clone for LoroText

fn clone(&self) -> LoroText

Returns a copy 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 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.

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.