Struct yrs::Doc

pub struct Doc {
    pub client_id: ClientID,
    /* private fields */
}

A Yrs document type. Documents are most important units of collaborative resources management. All shared collections live within a scope of their corresponding documents. All updates are generated on per document basis (rather than individual shared type). All operations on shared collections happen via Transaction, which lifetime is also bound to a document.

Document manages so called root types, which are top-level shared types definitions (as opposed to recursively nested types).

A basic workflow sample:

use yrs::{Doc, StateVector, Update};
use yrs::updates::decoder::Decode;
use yrs::updates::encoder::Encode;

let doc = Doc::new();
let mut txn = doc.transact(); // all Yrs operations happen in scope of a transaction
let root = txn.get_text("root-type-name");
root.push(&mut txn, "hello world"); // append text to our collaborative document

// in order to exchange data with other documents we first need to create a state vector
let remote_doc = Doc::new();
let mut remote_txn = remote_doc.transact();
let state_vector = remote_txn.state_vector().encode_v1();

// now compute a differential update based on remote document's state vector
let update = txn.encode_diff_v1(&StateVector::decode_v1(&state_vector));

// both update and state vector are serializable, we can pass the over the wire
// now apply update to a remote document
remote_txn.apply_update(Update::decode_v1(update.as_slice()));

Fields

client_id: ClientID

A unique client identifier, that’s also a unique identifier of current document replica.

Implementations

impl Doc

pub fn new() -> Self

Creates a new document with a randomized client identifier.

pub fn with_client_id(client_id: ClientID) -> Self

Creates a new document with a specified client_id. It’s up to a caller to guarantee that this identifier is unique across all communicating replicas of that document.

pub fn with_options(options: Options) -> Self

pub fn transact(&self) -> Transaction

Creates a transaction used for all kind of block store operations. Transaction cleanups & calling event handles happen when the transaction struct is dropped.

pub fn observe_update_v1<F>(&mut self, f: F) -> Subscription<UpdateEvent> where
    F: Fn(&Transaction, &UpdateEvent) + 'static, 

Subscribe callback function for any changes performed within transaction scope. These changes are encoded using lib0 v1 encoding and can be decoded using [Update::decode_v1] if necessary or passed to remote peers right away. This callback is triggered on function commit.

Returns a subscription, which will unsubscribe function when dropped.

pub fn unobserve_update_v1(&mut self, subscription_id: SubscriptionId)

Manually unsubscribes from a callback used in Doc::observe_update_v1 method.

pub fn observe_update_v2<F>(&mut self, f: F) -> Subscription<UpdateEvent> where
    F: Fn(&Transaction, &UpdateEvent) + 'static, 

Subscribe callback function for any changes performed within transaction scope. These changes are encoded using lib0 v1 encoding and can be decoded using [Update::decode_v2] if necessary or passed to remote peers right away. This callback is triggered on function commit.

Returns a subscription, which will unsubscribe function when dropped.

pub fn unobserve_update_v2(&mut self, subscription_id: SubscriptionId)

Manually unsubscribes from a callback used in Doc::observe_update_v1 method.

pub fn observe_transaction_cleanup<F>(
    &mut self,
    f: F
) -> Subscription<AfterTransactionEvent> where
    F: Fn(&Transaction, &AfterTransactionEvent) + 'static, 

Subscribe callback function to updates on the Doc. The callback will receive state updates and deletions when a document transaction is committed.

pub fn unobserve_transaction_cleanup(&mut self, subscription_id: SubscriptionId)

Cancels the transaction cleanup callback associated with the subscription_id

pub fn encode_state_as_update<E: Encoder>(
    &self,
    sv: &StateVector,
    encoder: &mut E
)

pub fn encode_state_as_update_v1(&self, sv: &StateVector) -> Vec<u8>

pub fn encode_state_as_update_v2(&self, sv: &StateVector) -> Vec<u8>

Trait Implementations

impl Default for Doc

fn default() -> Self

Returns the “default value” for a type.

impl Send for Doc