Struct LoroText 

pub struct LoroText { /* private fields */ }

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

Indexing and lengths:

• Rust APIs default to Unicode scalar positions for insert/delete and slice.
• For byte-based integration, use insert_utf8/delete_utf8.
• For UTF-16 code unit offsets (e.g., integrating with JavaScript), use insert_utf16/delete_utf16/slice_utf16 and related helpers.
• You can inspect len_unicode, len_utf8, and len_utf16 depending on your needs.

Example (emoji)

use loro::LoroDoc;
let doc = LoroDoc::new();
let text = doc.get_text("text");
text.insert(0, "Hello 😀 World").unwrap();
assert_eq!(text.len_unicode(), 13); // visible characters
assert!(text.len_utf16() >= text.len_unicode()); // emoji may count as 2 in UTF-16
// Delete the emoji safely by Unicode indices
let start = 6; // after "Hello "
text.delete(start, 1).unwrap();
assert_eq!(text.to_string(), "Hello  World");

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 over contiguous text chunks.

The callback function will be called for each contiguous text segment (internal span), not necessarily a single character. If you need per-character iteration, iterate the returned &str within the callback. 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 insert_utf16(&self, pos: usize, s: &str) -> LoroResult<()>

Insert a string at the given UTF-16 code unit position.

This is useful when working with JavaScript or other UTF-16-based index systems.

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 delete_utf16(&self, pos: usize, len: usize) -> LoroResult<()>

Delete a range of text at the given UTF-16 code unit position with UTF-16 length.

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

Get a string slice at the given Unicode range

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

Get a string slice using UTF-16 code unit offsets.

pub fn slice_delta( &self, start: usize, end: usize, pos_type: PosType, ) -> LoroResult<Vec<TextDelta>>

Get the rich-text delta within a range.

The range is expressed in the coordinate system selected by pos_type: Unicode scalar indices (PosType::Unicode), UTF-8 bytes, UTF-16 units, etc. The returned TextDelta segments contain only inserts and preserve the attributes active inside the slice.

Errors

Returns LoroError::OutOfBound when the range exceeds the current text length in the chosen coordinate system, or LoroError::EndIndexLessThanStartIndex if end < start.

Examples

use loro::{LoroDoc, TextDelta};
use loro::cursor::PosType;

let doc = LoroDoc::new();
let text = doc.get_text("text");
text.insert(0, "A😀BC").unwrap();
text.mark(0..2, "bold", true).unwrap(); // A and 😀

let delta = text.slice_delta(1, 3, PosType::Unicode).unwrap();
assert_eq!(delta.len(), 2);
if let TextDelta::Insert { insert, attributes } = &delta[0] {
    assert_eq!(insert, "😀");
    assert_eq!(attributes.as_ref().unwrap().get("bold").unwrap(), &true.into());
} else {
    unreachable!();
}
if let TextDelta::Insert { insert, attributes } = &delta[1] {
    assert_eq!(insert, "B");
    assert!(attributes.is_none());
} else {
    unreachable!();
}

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 splice_utf16(&self, pos: usize, len: usize, s: &str) -> LoroResult<()>

Delete specified range and insert a string at the same UTF-16 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.

The range uses Unicode scalar indices; use [mark_utf8] for UTF-8 byte offsets.

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 mark_utf8( &self, range: Range<usize>, key: &str, value: impl Into<LoroValue>, ) -> LoroResult<()>

Mark a range of text with a key-value pair using UTF-8 byte offsets.

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

Mark a range of text with a key-value pair using UTF-16 code unit offsets.

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 unmark_utf16(&self, range: Range<usize>, key: &str) -> LoroResult<()>

Unmark a range of text with a key and a value using UTF-16 code unit offsets.

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 rustc_hash::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 convert_pos( &self, index: usize, from: PosType, to: PosType, ) -> Option<usize>

Convert a position between coordinate systems (Unicode, UTF-16, UTF-8 bytes, Event).

Returns None when the position is out of bounds or the conversion isn’t supported.

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.

Returns None if the position is out of bounds or attribution is unavailable.

Example

use loro::LoroDoc;
let doc = LoroDoc::new();
let t = doc.get_text("t");
t.insert(0, "hi").unwrap();
let who = t.get_editor_at_unicode_pos(0);
assert!(who.is_some());

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.