Struct LoroDoc

pub struct LoroDoc { /* private fields */ }

LoroDoc serves as the library’s primary entry point. It’s constituted by an OpLog and an DocState.

• OpLog encompasses all operations, signifying the document history.
• DocState signifies the current document state.

They will share a [super::arena::SharedArena]

Detached Mode

This mode enables separate usage of OpLog and DocState. It facilitates temporal navigation. DocState can be reverted to any version contained within the OpLog.

LoroDoc::detach() separates DocState from OpLog. In this mode, updates to OpLog won’t affect DocState, while updates to DocState will continue to affect OpLog.

Implementations

impl LoroDoc

pub fn decode_import_blob_meta( blob: &[u8], check_checksum: bool, ) -> LoroResult<ImportBlobMetadata>

Decodes the metadata for an imported blob from the provided bytes.

impl LoroDoc

pub fn fork_at(&self, frontiers: &Frontiers) -> Self

Creates a new LoroDoc at a specified version (Frontiers)

impl LoroDoc

pub fn new() -> Self

pub fn fork(&self) -> Self

pub fn set_detached_editing(&self, enable: bool)

Enables editing of the document in detached mode.

By default, the document cannot be edited in detached mode (after calling detach or checking out a version other than the latest). This method allows editing in detached mode.

Important Notes:

• After enabling this mode, the document will use a different PeerID. Each time you call checkout, a new PeerID will be used.
• If you set a custom PeerID while this mode is enabled, ensure that concurrent operations with the same PeerID are not possible.
• On detached mode, importing will not change the state of the document. It also doesn’t change the version of the DocState. The changes will be recorded into OpLog only. You need to call checkout to make it take effect.

pub fn new_auto_commit() -> Self

Create a doc with auto commit enabled.

pub fn set_peer_id(&self, peer: PeerID) -> LoroResult<()>

pub fn commit_then_stop( &self, ) -> (Option<CommitOptions>, LoroMutexGuard<'_, Option<Transaction>>)

Commit the cumulative auto commit transaction. This method only has effect when auto_commit is true.

Afterwards, the users need to call self.renew_txn_after_commit() to resume the continuous transaction.

It only returns Some(options_of_the_empty_txn) when the txn is empty

pub fn commit_then_renew(&self) -> Option<CommitOptions>

Commit the cumulative auto commit transaction. It will start the next one immediately

It only returns Some(options_of_the_empty_txn) when the txn is empty

pub fn commit_with( &self, config: CommitOptions, ) -> (Option<CommitOptions>, Option<LoroMutexGuard<'_, Option<Transaction>>>)

Commit the cumulative auto commit transaction. This method only has effect when auto_commit is true. If immediate_renew is true, a new transaction will be created after the old one is committed

It only returns Some(options_of_the_empty_txn) when the txn is empty

pub fn set_next_commit_message(&self, message: &str)

Set the commit message of the next commit

pub fn set_next_commit_origin(&self, origin: &str)

Set the origin of the next commit

pub fn set_next_commit_timestamp(&self, timestamp: Timestamp)

Set the timestamp of the next commit

pub fn set_next_commit_options(&self, options: CommitOptions)

Set the options of the next commit

pub fn clear_next_commit_options(&self)

Clear the options of the next commit

pub fn set_record_timestamp(&self, record: bool)

Set whether to record the timestamp of each change. Default is false.

If enabled, the Unix timestamp will be recorded for each change automatically.

You can also set each timestamp manually when you commit a change. The timestamp manually set will override the automatic one.

NOTE: Timestamps are forced to be in ascending order. If you commit a new change with a timestamp that is less than the existing one, the largest existing timestamp will be used instead.

pub fn set_change_merge_interval(&self, interval: i64)

Set the interval of mergeable changes, in seconds.

If two continuous local changes are within the interval, they will be merged into one change. The default value is 1000 seconds.

pub fn can_edit(&self) -> bool

pub fn is_detached_editing_enabled(&self) -> bool

pub fn config_text_style(&self, text_style: StyleConfigMap)

pub fn config_default_text_style(&self, text_style: Option<StyleConfig>)

pub fn from_snapshot(bytes: &[u8]) -> LoroResult<Self>

pub fn can_reset_with_snapshot(&self) -> bool

Is the document empty? (no ops)

pub fn is_detached(&self) -> bool

Whether OpLog and DocState are detached.

If so, the document is in readonly mode by default and importing will not change the state of the document. It also doesn’t change the version of the DocState. The changes will be recorded into OpLog only. You need to call checkout to make it take effect.

pub fn peer_id(&self) -> PeerID

pub fn detach(&self)

pub fn attach(&self)

pub fn state_timestamp(&self) -> Timestamp

Get the timestamp of the current state. It’s the last edit time of the DocState.

pub fn app_state(&self) -> &Arc<LoroMutex<DocState>>

pub fn get_state_deep_value(&self) -> LoroValue

pub fn oplog(&self) -> &Arc<LoroMutex<OpLog>>

pub fn export_from(&self, vv: &VersionVector) -> Vec<u8>

pub fn import(&self, bytes: &[u8]) -> Result<ImportStatus, LoroError>

pub fn import_with( &self, bytes: &[u8], origin: InternalString, ) -> Result<ImportStatus, LoroError>

pub fn export_snapshot(&self) -> Result<Vec<u8>, LoroEncodeError>

pub fn import_json_updates<T: TryInto<JsonSchema>>( &self, json: T, ) -> LoroResult<ImportStatus>

Import the json schema updates.

only supports backward compatibility but not forward compatibility.

pub fn export_json_updates( &self, start_vv: &VersionVector, end_vv: &VersionVector, with_peer_compression: bool, ) -> JsonSchema

pub fn export_json_in_id_span(&self, id_span: IdSpan) -> Vec<JsonChange>

pub fn oplog_vv(&self) -> VersionVector

Get the version vector of the current OpLog

pub fn state_vv(&self) -> VersionVector

Get the version vector of the current DocState

pub fn get_by_path(&self, path: &[Index]) -> Option<ValueOrHandler>

pub fn get_by_str_path(&self, path: &str) -> Option<ValueOrHandler>

Get the handler by the string path.

pub fn get_uncommitted_ops_as_json(&self) -> Option<JsonSchema>

pub fn get_handler(&self, id: ContainerID) -> Option<Handler>

pub fn get_text<I: IntoContainerId>(&self, id: I) -> TextHandler

id can be a str, ContainerID, or ContainerIdRaw. if it’s str it will use Root container, which will not be None

pub fn get_list<I: IntoContainerId>(&self, id: I) -> ListHandler

id can be a str, ContainerID, or ContainerIdRaw. if it’s str it will use Root container, which will not be None

pub fn get_movable_list<I: IntoContainerId>(&self, id: I) -> MovableListHandler

id can be a str, ContainerID, or ContainerIdRaw. if it’s str it will use Root container, which will not be None

pub fn get_map<I: IntoContainerId>(&self, id: I) -> MapHandler

id can be a str, ContainerID, or ContainerIdRaw. if it’s str it will use Root container, which will not be None

pub fn get_tree<I: IntoContainerId>(&self, id: I) -> TreeHandler

id can be a str, ContainerID, or ContainerIdRaw. if it’s str it will use Root container, which will not be None

pub fn has_container(&self, id: &ContainerID) -> bool

pub fn undo_internal( &self, id_span: IdSpan, container_remap: &mut FxHashMap<ContainerID, ContainerID>, post_transform_base: Option<&DiffBatch>, before_diff: &mut dyn FnMut(&DiffBatch), ) -> LoroResult<CommitWhenDrop<'_>>

Undo the operations between the given id_span. It can be used even in a collaborative environment.

This is an internal API. You should NOT use it directly.

Internal

This method will use the diff calculator to calculate the diff required to time travel from the end of id_span to the beginning of the id_span. Then it will convert the diff to operations and apply them to the OpLog with a dep on the last id of the given id_span.

This implementation is kinda slow, but it’s simple and maintainable. We can optimize it further when it’s needed. The time complexity is O(n + m), n is the ops in the id_span, m is the distance from id_span to the current latest version.

pub fn revert_to(&self, target: &Frontiers) -> LoroResult<()>

Generate a series of local operations that can revert the current doc to the target version.

Internally, it will calculate the diff between the current state and the target state, and apply the diff to the current state.

pub fn diff(&self, a: &Frontiers, b: &Frontiers) -> LoroResult<DiffBatch>

Calculate the diff between two versions so that apply diff on a will make the state same as b.

NOTE: This method will make the doc enter the detached mode.

pub fn apply_diff(&self, diff: DiffBatch) -> LoroResult<()>

Apply a diff to the current state.

pub fn diagnose_size(&self)

This is for debugging purpose. It will travel the whole oplog

pub fn oplog_frontiers(&self) -> Frontiers

pub fn state_frontiers(&self) -> Frontiers

pub fn cmp_with_frontiers(&self, other: &Frontiers) -> Ordering

• Ordering::Less means self is less than target or parallel
• Ordering::Equal means versions equal
• Ordering::Greater means self’s version is greater than target

pub fn cmp_frontiers( &self, a: &Frontiers, b: &Frontiers, ) -> Result<Option<Ordering>, FrontiersNotIncluded>

Compare two Frontiers causally.

If one of the Frontiers are not included, it will return FrontiersNotIncluded.

pub fn subscribe_root(&self, callback: Subscriber) -> Subscription

pub fn subscribe( &self, container_id: &ContainerID, callback: Subscriber, ) -> Subscription

pub fn subscribe_local_update( &self, callback: LocalUpdateCallback, ) -> Subscription

pub fn import_batch(&self, bytes: &[Vec<u8>]) -> LoroResult<ImportStatus>

pub fn get_value(&self) -> LoroValue

Get shallow value of the document.

pub fn get_deep_value(&self) -> LoroValue

Get deep value of the document.

pub fn get_deep_value_with_id(&self) -> LoroValue

Get deep value of the document with container id

pub fn checkout_to_latest(&self)

pub fn checkout(&self, frontiers: &Frontiers) -> LoroResult<()>

Checkout DocState to a specific version.

This will make the current DocState detached from the latest version of OpLog. Any further import will not be reflected on the DocState, until user call LoroDoc::attach()

pub fn vv_to_frontiers(&self, vv: &VersionVector) -> Frontiers

pub fn frontiers_to_vv(&self, frontiers: &Frontiers) -> Option<VersionVector>

pub fn merge(&self, other: &Self) -> LoroResult<ImportStatus>

Import ops from other doc.

After a.merge(b) and b.merge(a), a and b will have the same content if they are in attached mode.

pub fn len_ops(&self) -> usize

pub fn len_changes(&self) -> usize

pub fn config(&self) -> &Configure

pub fn check_state_diff_calc_consistency_slow(&self)

This method compare the consistency between the current doc state and the state calculated by diff calculator from beginning.

Panic when it’s not consistent

pub fn log_estimated_size(&self)

pub fn query_pos( &self, pos: &Cursor, ) -> Result<PosQueryResult, CannotFindRelativePosition>

pub fn free_history_cache(&self)

Free the history cache that is used for making checkout faster.

If you use checkout that switching to an old/concurrent version, the history cache will be built. You can free it by calling this method.

pub fn free_diff_calculator(&self)

Free the cached diff calculator that is used for checkout.

pub fn has_history_cache(&self) -> bool

If you use checkout that switching to an old/concurrent version, the history cache will be built. You can free it by calling free_history_cache.

pub fn compact_change_store(&self)

Encoded all ops and history cache to bytes and store them in the kv store.

The parsed ops will be dropped

pub fn analyze(&self) -> DocAnalysis

Analyze the container info of the doc

This is used for development and debugging

pub fn get_path_to_container( &self, id: &ContainerID, ) -> Option<Vec<(ContainerID, Index)>>

Get the path from the root to the container

pub fn export(&self, mode: ExportMode<'_>) -> Result<Vec<u8>, LoroEncodeError>

pub fn shallow_since_vv(&self) -> ImVersionVector

The doc only contains the history since the shallow history start version vector.

This is empty if the doc is not shallow.

The ops included by the shallow history start version vector are not in the doc.

pub fn shallow_since_frontiers(&self) -> Frontiers

pub fn is_shallow(&self) -> bool

Check if the doc contains the full history.

pub fn get_pending_txn_len(&self) -> usize

Get the number of operations in the pending transaction.

The pending transaction is the one that is not committed yet. It will be committed after calling doc.commit(), doc.export(mode) or doc.checkout(version).

pub fn find_id_spans_between( &self, from: &Frontiers, to: &Frontiers, ) -> VersionVectorDiff

pub fn subscribe_first_commit_from_peer( &self, callback: FirstCommitFromPeerCallback, ) -> Subscription

Subscribe to the first commit from a peer. Operations performed on the LoroDoc within this callback will be merged into the current commit.

This is useful for managing the relationship between PeerID and user information. For example, you could store user names in a LoroMap using PeerID as the key and the UserID as the value.

pub fn subscribe_pre_commit(&self, callback: PreCommitCallback) -> Subscription

Subscribe to the pre-commit event.

The callback will be called when the changes are committed but not yet applied to the OpLog. You can modify the commit message and timestamp in the callback by [ChangeModifier].

impl LoroDoc

pub fn travel_change_ancestors( &self, ids: &[ID], f: &mut dyn FnMut(ChangeMeta) -> ControlFlow<()>, ) -> Result<(), ChangeTravelError>

pub fn get_changed_containers_in( &self, id: ID, len: usize, ) -> FxHashSet<ContainerID>

pub fn delete_root_container(&self, cid: ContainerID)

pub fn set_hide_empty_root_containers(&self, hide: bool)

impl LoroDoc

pub fn subscribe_peer_id_change( &self, callback: PeerIdUpdateCallback, ) -> Subscription

Subscribe to the changes of the peer id.

impl LoroDoc

pub fn txn(&self) -> Result<Transaction, LoroError>

Create a new transaction. Every ops created inside one transaction will be packed into a single Change.

There can only be one active transaction at a time for a LoroDoc.

pub fn txn_with_origin(&self, origin: &str) -> Result<Transaction, LoroError>

Create a new transaction with specified origin.

The origin will be propagated to the events. There can only be one active transaction at a time for a LoroDoc.

pub fn start_auto_commit(&self)

pub fn renew_txn_if_auto_commit(&self, options: Option<CommitOptions>)

Trait Implementations

impl Clone for LoroDoc

fn clone(&self) -> LoroDoc

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for LoroDoc

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

Formats the value using the given formatter.

impl Default for LoroDoc

fn default() -> Self

Returns the “default value” for a type.

impl Deref for LoroDoc

type Target = LoroDocInner

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Drop for LoroDoc

fn drop(&mut self)

Executes the destructor for this type.