Struct LoroTree

pub struct LoroTree { /* private fields */ }

LoroTree container. It’s used to model movable trees.

You may use it to model directories, outline or other movable hierarchical data.

Learn more at https://loro.dev/docs/tutorial/tree

Implementations

impl LoroTree

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 create<T: Into<TreeParentId>>(&self, parent: T) -> LoroResult<TreeID>

Create a new tree node and return the TreeID.

If the parent is None, the created node is the root of a tree. Otherwise, the created node is a child of the parent tree node.

Example

use loro::LoroDoc;

let doc = LoroDoc::new();
let tree = doc.get_tree("tree");
// create a root
let root = tree.create(None).unwrap();
// create a new child
let child = tree.create(root).unwrap();

pub fn roots(&self) -> Vec<TreeID>

Get the root nodes of the forest.

pub fn create_at<T: Into<TreeParentId>>( &self, parent: T, index: usize, ) -> LoroResult<TreeID>

Create a new tree node at the given index and return the TreeID.

If the parent is None, the created node is the root of a tree. If the index is greater than the number of children of the parent, error will be returned.

Example

use loro::LoroDoc;

let doc = LoroDoc::new();
let tree = doc.get_tree("tree");
// enable generate fractional index
tree.enable_fractional_index(0);
// create a root
let root = tree.create(None).unwrap();
// create a new child at index 0
let child = tree.create_at(root, 0).unwrap();

pub fn mov<T: Into<TreeParentId>>( &self, target: TreeID, parent: T, ) -> LoroResult<()>

Move the target node to be a child of the parent node.

If the parent is None, the target node will be a root.

Example

use loro::LoroDoc;

let doc = LoroDoc::new();
let tree = doc.get_tree("tree");
let root = tree.create(None).unwrap();
let root2 = tree.create(None).unwrap();
// move `root2` to be a child of `root`.
tree.mov(root2, root).unwrap();

pub fn mov_to<T: Into<TreeParentId>>( &self, target: TreeID, parent: T, to: usize, ) -> LoroResult<()>

Move the target node to be a child of the parent node at the given index. If the parent is None, the target node will be a root.

Example

use loro::LoroDoc;

let doc = LoroDoc::new();
let tree = doc.get_tree("tree");
// enable generate fractional index
tree.enable_fractional_index(0);
let root = tree.create(None).unwrap();
let root2 = tree.create(None).unwrap();
// move `root2` to be a child of `root` at index 0.
tree.mov_to(root2, root, 0).unwrap();

pub fn mov_after(&self, target: TreeID, after: TreeID) -> LoroResult<()>

Move the target node to be a child after the after node with the same parent.

Example

use loro::LoroDoc;

let doc = LoroDoc::new();
let tree = doc.get_tree("tree");
// enable generate fractional index
tree.enable_fractional_index(0);
let root = tree.create(None).unwrap();
let root2 = tree.create(None).unwrap();
// move `root` to be a child after `root2`.
tree.mov_after(root, root2).unwrap();

pub fn mov_before(&self, target: TreeID, before: TreeID) -> LoroResult<()>

Move the target node to be a child before the before node with the same parent.

Example

use loro::LoroDoc;

let doc = LoroDoc::new();
let tree = doc.get_tree("tree");
// enable generate fractional index
tree.enable_fractional_index(0);
let root = tree.create(None).unwrap();
let root2 = tree.create(None).unwrap();
// move `root` to be a child before `root2`.
tree.mov_before(root, root2).unwrap();

pub fn delete(&self, target: TreeID) -> LoroResult<()>

Delete a tree node.

Note: If the deleted node has children, the children do not appear in the state rather than actually being deleted.

Example

use loro::LoroDoc;

let doc = LoroDoc::new();
let tree = doc.get_tree("tree");
let root = tree.create(None).unwrap();
tree.delete(root).unwrap();

pub fn get_meta(&self, target: TreeID) -> LoroResult<LoroMap>

Get the associated metadata map handler of a tree node.

Example

use loro::LoroDoc;

let doc = LoroDoc::new();
let tree = doc.get_tree("tree");
let root = tree.create(None).unwrap();
let root_meta = tree.get_meta(root).unwrap();
root_meta.insert("color", "red");

pub fn parent(&self, target: TreeID) -> Option<TreeParentId>

Return the parent of target node.

• If the target node does not exist, return None.
• If the target node is a root node, return Some(None).

pub fn contains(&self, target: TreeID) -> bool

Return whether target node exists. including deleted node.

pub fn is_node_deleted(&self, target: &TreeID) -> LoroResult<bool>

Return whether target node is deleted.

Errors

• If the target node does not exist, return LoroTreeError::TreeNodeNotExist.

pub fn nodes(&self) -> Vec<TreeID>

Return all nodes, including deleted nodes

pub fn get_nodes(&self, with_deleted: bool) -> Vec<TreeNode>

Return all nodes, if with_deleted is true, the deleted nodes will be included.

pub fn children<T: Into<TreeParentId>>(&self, parent: T) -> Option<Vec<TreeID>>

Return all children of the target node.

If the parent node does not exist, return None.

pub fn children_num<T: Into<TreeParentId>>(&self, parent: T) -> Option<usize>

Return the number of children of the target node.

pub fn fractional_index(&self, target: TreeID) -> Option<String>

Return the fractional index of the target node with hex format.

pub fn get_value(&self) -> LoroValue

Return the hierarchy array of the forest.

Note: the metadata will be not resolved. So if you don’t only care about hierarchy but also the metadata, you should use [TreeHandler::get_value_with_meta()].

pub fn get_value_with_meta(&self) -> LoroValue

Return the hierarchy array of the forest, each node is with metadata.

pub fn is_fractional_index_enabled(&self) -> bool

Whether the fractional index is enabled.

pub fn enable_fractional_index(&self, jitter: u8)

Enable fractional index for Tree Position.

The jitter is used to avoid conflicts when multiple users are creating the node at the same position. value 0 is default, which means no jitter, any value larger than 0 will enable jitter.

Generally speaking, jitter will affect the growth rate of document size. Read more about it

pub fn disable_fractional_index(&self)

Disable the fractional index generation when you don’t need the Tree’s siblings to be sorted. The fractional index will always be set to the same default value 0.

After calling this, you cannot use tree.moveTo(), tree.moveBefore(), tree.moveAfter(), and tree.createAt().

pub fn is_empty(&self) -> bool

Whether the tree is empty.

pub fn get_last_move_id(&self, target: &TreeID) -> Option<ID>

Get the last move id of the target node.

Trait Implementations

impl Clone for LoroTree

fn clone(&self) -> LoroTree

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ContainerTrait for LoroTree

type Handler = TreeHandler

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 LoroTree

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

Formats the value using the given formatter.

impl Default for LoroTree

fn default() -> Self

Returns the “default value” for a type.