Struct loro_internal::loro::LoroDoc

pub struct LoroDoc { /* private fields */ }

LoroApp serves as the library’s primary entry point. It’s constituted by an OpLog and an [AppState].

• OpLog encompasses all operations, signifying the document history.
• [AppState] signifies the current document state.

They will share a super::arena::SharedArena

Detached Mode

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

LoroApp::detach() separates [AppState] from OpLog. In this mode, updates to OpLog won’t affect [AppState], while updates to [AppState] will continue to affect OpLog.

Implementations

impl LoroDoc

pub fn new() -> Self

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 milliseconds.

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

pub fn set_fractional_index_jitter(&self, jitter: u8)

Set the jitter of the tree position(Fractional Index).

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.

pub fn config_text_style(&self, text_style: StyleConfigMap)

pub fn new_auto_commit() -> Self

Create a doc with auto commit enabled.

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.

pub fn peer_id(&self) -> PeerID

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

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 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 with_txn<F, R>(&self, f: F) -> LoroResult<R>

where F: FnOnce(&mut Transaction) -> LoroResult<R>,

pub fn start_auto_commit(&self)

pub fn commit_then_stop(&self)

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.

pub fn commit_then_renew(&self)

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

pub fn commit_with(&self, config: CommitOptions)

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

pub fn renew_txn_if_auto_commit(&self)

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 app_state(&self) -> &Arc<Mutex<DocState>>

pub fn get_state_deep_value(&self) -> LoroValue

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

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

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

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

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

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_handler(&self, id: ContainerID) -> 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 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 diff_and_apply(&self, target: &Frontiers) -> LoroResult<()>

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, container_remap: &mut FxHashMap<ContainerID, ContainerID>, skip_unreachable: bool ) -> LoroResult<()>

Apply a diff to the current state.

This method will not recreate containers with the same ContainerIDs. While this can be convenient in certain cases, it can break several internal invariants:

1. Each container should appear only once in the document. Allowing containers with the same ID would result in multiple instances of the same container in the document.
2. Unreachable containers should be removable from the state when necessary.

However, the diff may contain operations that depend on container IDs. Therefore, users need to provide a container_remap to record and retrieve the container ID remapping.

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

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

pub fn unsubscribe(&self, id: SubID)

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

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

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>

impl LoroDoc

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

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

Trait Implementations

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.