pub struct Doc { /* private fields */ }
Expand description
A Yrs document type. Documents are the 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).
§Example
use yrs::{Doc, ReadTxn, StateVector, Text, Transact, Update};
use yrs::updates::decoder::Decode;
use yrs::updates::encoder::Encode;
let doc = Doc::new();
let root = doc.get_or_insert_text("root-type-name");
let mut txn = doc.transact_mut(); // all Yrs operations happen in scope of a transaction
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_mut();
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).unwrap());
// 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()).unwrap());
Implementations§
source§impl Doc
impl Doc
sourcepub fn with_client_id(client_id: ClientID) -> Self
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.
sourcepub fn with_options(options: Options) -> Self
pub fn with_options(options: Options) -> Self
Creates a new document with a configured set of Options.
sourcepub fn client_id(&self) -> ClientID
pub fn client_id(&self) -> ClientID
A unique client identifier, that’s also a unique identifier of current document replica and it’s subdocuments.
sourcepub fn guid(&self) -> &Uuid
pub fn guid(&self) -> &Uuid
A globally unique identifier, that’s also a unique identifier of current document replica, and unlike Doc::client_id it’s not shared with its subdocuments.
sourcepub fn get_or_insert_text<N: Into<Arc<str>>>(&self, name: N) -> TextRef
pub fn get_or_insert_text<N: Into<Arc<str>>>(&self, name: N) -> TextRef
Returns a TextRef data structure stored under a given name
. Text structures are used for
collaborative text editing: they expose operations to append and remove chunks of text,
which are free to execute concurrently by multiple peers over remote boundaries.
If no structure under defined name
existed before, it will be created and returned
instead.
If a structure under defined name
already existed, but its type was different it will be
reinterpreted as a text (in such case a sequence component of complex data type will be
interpreted as a list of text chunks).
§Panics
This method requires exclusive access to an underlying document store. If there is another transaction in process, it will panic. It’s advised to define all root shared types during the document creation.
sourcepub fn get_or_insert_map<N: Into<Arc<str>>>(&self, name: N) -> MapRef
pub fn get_or_insert_map<N: Into<Arc<str>>>(&self, name: N) -> MapRef
Returns a MapRef data structure stored under a given name
. Maps are used to store key-value
pairs associated. These values can be primitive data (similar but not limited to
a JavaScript Object Notation) as well as other shared types (Yrs maps, arrays, text
structures etc.), enabling to construct a complex recursive tree structures.
If no structure under defined name
existed before, it will be created and returned
instead.
If a structure under defined name
already existed, but its type was different it will be
reinterpreted as a map (in such case a map component of complex data type will be
interpreted as native map).
§Panics
This method requires exclusive access to an underlying document store. If there is another transaction in process, it will panic. It’s advised to define all root shared types during the document creation.
sourcepub fn get_or_insert_array<N: Into<Arc<str>>>(&self, name: N) -> ArrayRef
pub fn get_or_insert_array<N: Into<Arc<str>>>(&self, name: N) -> ArrayRef
Returns an ArrayRef data structure stored under a given name
. Array structures are used for
storing a sequences of elements in ordered manner, positioning given element accordingly
to its index.
If no structure under defined name
existed before, it will be created and returned
instead.
If a structure under defined name
already existed, but its type was different it will be
reinterpreted as an array (in such case a sequence component of complex data type will be
interpreted as a list of inserted values).
§Panics
This method requires exclusive access to an underlying document store. If there is another transaction in process, it will panic. It’s advised to define all root shared types during the document creation.
sourcepub fn get_or_insert_xml_fragment<N: Into<Arc<str>>>(
&self,
name: N
) -> XmlFragmentRef
pub fn get_or_insert_xml_fragment<N: Into<Arc<str>>>( &self, name: N ) -> XmlFragmentRef
Returns a XmlFragmentRef data structure stored under a given name
. XML elements represent
nodes of XML document. They can contain attributes (key-value pairs, both of string type)
and other nested XML elements or text values, which are stored in their insertion
order.
If no structure under defined name
existed before, it will be created and returned
instead.
If a structure under defined name
already existed, but its type was different it will be
reinterpreted as a XML element (in such case a map component of complex data type will be
interpreted as map of its attributes, while a sequence component - as a list of its child
XML nodes).
§Panics
This method requires exclusive access to an underlying document store. If there is another transaction in process, it will panic. It’s advised to define all root shared types during the document creation.
sourcepub fn observe_update_v1<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
pub fn observe_update_v1<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
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.
sourcepub fn observe_update_v2<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
pub fn observe_update_v2<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
Subscribe callback function for any changes performed within transaction scope. These changes are encoded using lib0 v2 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.
sourcepub fn observe_transaction_cleanup<F>(
&self,
f: F
) -> Result<Subscription, BorrowMutError>
pub fn observe_transaction_cleanup<F>( &self, f: F ) -> Result<Subscription, BorrowMutError>
Subscribe callback function to updates on the Doc
. The callback will receive state updates and
deletions when a document transaction is committed.
pub fn observe_after_transaction<F>(
&self,
f: F
) -> Result<Subscription, BorrowMutError>where
F: Fn(&mut TransactionMut<'_>) + 'static,
sourcepub fn observe_subdocs<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
pub fn observe_subdocs<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
Subscribe callback function, that will be called whenever a subdocuments inserted in this Doc will request a load.
sourcepub fn observe_destroy<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
pub fn observe_destroy<F>(&self, f: F) -> Result<Subscription, BorrowMutError>
Subscribe callback function, that will be called whenever a [DocRef::destroy] has been called.
sourcepub fn load<T>(&self, parent_txn: &mut T)where
T: WriteTxn,
pub fn load<T>(&self, parent_txn: &mut T)where
T: WriteTxn,
Sends a load request to a parent document. Works only if current document is a sub-document of an another document.
sourcepub fn destroy<T>(&self, parent_txn: &mut T)where
T: WriteTxn,
pub fn destroy<T>(&self, parent_txn: &mut T)where
T: WriteTxn,
Starts destroy procedure for a current document, triggering an “destroy” callback and invalidating all event callback subscriptions.
sourcepub fn parent_doc(&self) -> Option<Doc>
pub fn parent_doc(&self) -> Option<Doc>
If current document has been inserted as a sub-document, returns a reference to a parent document, which contains it.
pub fn branch_id(&self) -> Option<BranchID>
pub fn ptr_eq(a: &Doc, b: &Doc) -> bool
Trait Implementations§
source§impl PartialEq for Doc
impl PartialEq for Doc
source§impl Prelim for Doc
impl Prelim for Doc
source§fn into_content(
self,
_txn: &mut TransactionMut<'_>
) -> (ItemContent, Option<Self>)
fn into_content( self, _txn: &mut TransactionMut<'_> ) -> (ItemContent, Option<Self>)
ptr
can be used to identify block that is about to be created to store
the returned content. Read moresource§fn integrate(self, _txn: &mut TransactionMut<'_>, _inner_ref: BranchPtr)
fn integrate(self, _txn: &mut TransactionMut<'_>, _inner_ref: BranchPtr)
source§impl Transact for Doc
impl Transact for Doc
source§fn try_transact(&self) -> Result<Transaction<'_>, TransactionAcqError>
fn try_transact(&self) -> Result<Transaction<'_>, TransactionAcqError>
source§fn try_transact_mut(&self) -> Result<TransactionMut<'_>, TransactionAcqError>
fn try_transact_mut(&self) -> Result<TransactionMut<'_>, TransactionAcqError>
source§fn try_transact_mut_with<T>(
&self,
origin: T
) -> Result<TransactionMut<'_>, TransactionAcqError>
fn try_transact_mut_with<T>( &self, origin: T ) -> Result<TransactionMut<'_>, TransactionAcqError>
origin
classifier attached.
This transaction can be used to mutate the contents of underlying document store and upon
dropping or committing it may subscription callbacks. Read moresource§fn transact_mut_with<T>(&self, origin: T) -> TransactionMut<'_>
fn transact_mut_with<T>(&self, origin: T) -> TransactionMut<'_>
origin
classifier attached.
This transaction can be used to mutate the contents of underlying document store and upon
dropping or committing it may subscription callbacks. Read more