Struct yrs::Doc

pub struct Doc {
    pub client_id: u64,
    /* 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;

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_doc.get_state_vector(&remote_txn);

// now compute a differential update based on remote document's state vector
let update = doc.encode_delta_as_update_v1(&txn, &state_vector);

// both update and state vector are serializable, we can pass the over the wire
// now apply update to a remote document
remote_doc.apply_update_v1(&mut remote_txn, update.as_slice());

Fields

client_id: u64

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: u64) -> 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 encode_state_as_update_v1(&self, txn: &Transaction) -> Vec<u8>

Encode entire state of a current block store using ver. 1 encoding. This state can be persisted so that later the entire document will be recovered. To apply state update use [Self::apply_update] method.

pub fn encode_state_vector_v1(&self, txn: &Transaction) -> Vec<u8>

Encode state vector of a current block store using ver. 1 encoding.

pub fn encode_delta_as_update_v1(
    &self,
    txn: &Transaction,
    remote_sv: &StateVector
) -> Vec<u8>

Encodes a difference between current block store and a remote one based on its state vector. Such update contains only blocks not observed by a remote peer together with a delete set.

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 apply_update_v1(&self, tr: &mut Transaction, update: &[u8])

Apply a document update assuming it’s encoded using lib0 ver.1 data format.

pub fn get_state_vector(&self, tr: &Transaction) -> StateVector

Retrieve document state vector in order to encode the document diff. This state vector contains compressed information about all inserted blocks observed by the current block store.

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

Subscribe callback function for incoming update events. Returns a subscription, which will unsubscribe function when dropped.

Trait Implementations

impl Default for Doc

fn default() -> Self

Returns the “default value” for a type.

impl Send for Doc