Struct LoroList 

pub struct LoroList { /* private fields */ }

LoroList container. It’s used to model arrays.

It can have sub containers.

Important: choose the right structure.

• Use LoroList for ordered collections where elements are appended/inserted/deleted.
• Use LoroMovableList when frequent reordering (drag-and-drop) is needed.
• Use LoroMap for keyed records and coordinates.

// Bad: coordinates in a list can diverge under concurrency
// let coord = doc.get_list("coord");
// coord.insert(0, 10).unwrap(); // x
// coord.insert(1, 20).unwrap(); // y

// Good: use a map for labeled fields
// let coord = doc.get_map("coord");
// coord.insert("x", 10).unwrap();
// coord.insert("y", 20).unwrap();

let doc = LoroDoc::new();
let list = doc.get_list("list");
list.insert(0, 123).unwrap();
list.insert(1, "h").unwrap();
assert_eq!(
    doc.get_deep_value().to_json_value(),
    json!({
        "list": [123, "h"]
    })
);

Implementations

impl LoroList

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 insert(&self, pos: usize, v: impl Into<LoroValue>) -> LoroResult<()>

Insert a value at the given position.

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

Delete values at the given position.

pub fn get(&self, index: usize) -> Option<ValueOrContainer>

Get the value at the given position.

pub fn get_deep_value(&self) -> LoroValue

Get the deep value of the container.

pub fn get_value(&self) -> LoroValue

Get the shallow value of the container.

This does not convert the state of sub-containers; instead, it represents them as LoroValue::Container.

pub fn pop(&self) -> LoroResult<Option<LoroValue>>

Pop the last element of the list.

pub fn push(&self, v: impl Into<LoroValue>) -> LoroResult<()>

Push a value to the list.

pub fn push_container<C: ContainerTrait>(&self, child: C) -> LoroResult<C>

Push a container to the list.

pub fn for_each<I>(&self, f: I)

where I: FnMut(ValueOrContainer),

Iterate over the elements of the list.

pub fn len(&self) -> usize

Get the length of the list.

pub fn is_empty(&self) -> bool

Whether the list is empty.

pub fn insert_container<C: ContainerTrait>( &self, pos: usize, child: C, ) -> LoroResult<C>

Insert a container with the given type at the given index.

Example

let doc = LoroDoc::new();
let list = doc.get_list("m");
let text = list.insert_container(0, LoroText::new()).unwrap();
text.insert(0, "12");
text.insert(0, "0");
assert_eq!(doc.get_deep_value().to_json_value(), json!({"m": ["012"]}));

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

use loro::LoroDoc;
use loro_internal::cursor::Side;

let doc = LoroDoc::new();
let list = doc.get_list("list");
list.insert(0, 0).unwrap();
let cursor = list.get_cursor(0, Side::Middle).unwrap();
assert_eq!(doc.get_cursor_pos(&cursor).unwrap().current.pos, 0);
list.insert(0, 0).unwrap();
assert_eq!(doc.get_cursor_pos(&cursor).unwrap().current.pos, 1);
list.insert(0, 0).unwrap();
list.insert(0, 0).unwrap();
assert_eq!(doc.get_cursor_pos(&cursor).unwrap().current.pos, 3);
list.insert(4, 0).unwrap();
assert_eq!(doc.get_cursor_pos(&cursor).unwrap().current.pos, 3);

pub fn to_vec(&self) -> Vec<LoroValue>

Converts the LoroList to a Vec of LoroValue.

This method unwraps the internal Arc and clones the data if necessary, returning a Vec containing all the elements of the LoroList as LoroValue.

Returns

A Vec containing all elements of the LoroList.

Example

use loro::{LoroDoc, LoroValue};

let doc = LoroDoc::new();
let list = doc.get_list("my_list");
list.insert(0, 1).unwrap();
list.insert(1, "hello").unwrap();
list.insert(2, true).unwrap();

let vec = list.to_vec();

pub fn clear(&self) -> LoroResult<()>

Delete all elements in the list.

pub fn get_id_at(&self, pos: usize) -> Option<ID>

Get the ID of the list item at the given position.

Trait Implementations

impl Clone for LoroList

fn clone(&self) -> LoroList

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ContainerTrait for LoroList

type Handler = ListHandler

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 LoroList

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

Formats the value using the given formatter.

impl Default for LoroList

fn default() -> Self

Returns the “default value” for a type.