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.
Default: randomly generated.
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.
Default: randomly generated UUID v4.
Sourcepub fn collection_id(&self) -> Option<Arc<str>>
pub fn collection_id(&self) -> Option<Arc<str>>
Returns a unique collection identifier, if defined.
Default: None
.
Sourcepub fn skip_gc(&self) -> bool
pub fn skip_gc(&self) -> bool
Informs if current document is skipping garbage collection on deleted collections on transaction commit.
Default: false
.
Sourcepub fn auto_load(&self) -> bool
pub fn auto_load(&self) -> bool
If current document is subdocument, it will automatically for a document to load.
Default: false
.
Sourcepub fn should_load(&self) -> bool
pub fn should_load(&self) -> bool
Whether the document should be synced by the provider now. This is toggled to true when you call Doc::load
Default value: true
.
Sourcepub fn offset_kind(&self) -> OffsetKind
pub fn offset_kind(&self) -> OffsetKind
Returns encoding used to count offsets and lengths in text operations.
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, TransactionAcqError>
pub fn observe_update_v1<F>( &self, f: F, ) -> Result<Subscription, TransactionAcqError>
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_v1_with<K, F>(
&self,
key: K,
f: F,
) -> Result<(), TransactionAcqError>
pub fn observe_update_v1_with<K, F>( &self, key: K, f: F, ) -> Result<(), TransactionAcqError>
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.
Provided key
will be used to identify a subscription, which will be used to unsubscribe.
pub fn unobserve_update_v1<K>( &self, key: K, ) -> Result<bool, TransactionAcqError>
Sourcepub fn observe_update_v2<F>(
&self,
f: F,
) -> Result<Subscription, TransactionAcqError>
pub fn observe_update_v2<F>( &self, f: F, ) -> Result<Subscription, TransactionAcqError>
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_update_v2_with<K, F>(
&self,
key: K,
f: F,
) -> Result<(), TransactionAcqError>
pub fn observe_update_v2_with<K, F>( &self, key: K, f: F, ) -> Result<(), TransactionAcqError>
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.
Provided key
will be used to identify a subscription, which will be used to unsubscribe.
pub fn unobserve_update_v2<K>( &self, key: K, ) -> Result<bool, TransactionAcqError>
Sourcepub fn observe_transaction_cleanup<F>(
&self,
f: F,
) -> Result<Subscription, TransactionAcqError>
pub fn observe_transaction_cleanup<F>( &self, f: F, ) -> Result<Subscription, TransactionAcqError>
Subscribe callback function to updates on the Doc
. The callback will receive state updates and
deletions when a document transaction is committed.
Sourcepub fn observe_transaction_cleanup_with<K, F>(
&self,
key: K,
f: F,
) -> Result<(), TransactionAcqError>
pub fn observe_transaction_cleanup_with<K, F>( &self, key: K, f: F, ) -> Result<(), TransactionAcqError>
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<K>( &self, key: K, ) -> Result<bool, TransactionAcqError>
pub fn observe_after_transaction_with<K, F>( &self, key: K, f: F, ) -> Result<(), TransactionAcqError>
pub fn unobserve_after_transaction<K>( &self, key: K, ) -> Result<bool, TransactionAcqError>
Sourcepub fn observe_subdocs<F>(
&self,
f: F,
) -> Result<Subscription, TransactionAcqError>
pub fn observe_subdocs<F>( &self, f: F, ) -> Result<Subscription, TransactionAcqError>
Subscribe callback function, that will be called whenever a subdocuments inserted in this Doc will request a load.
Sourcepub fn observe_subdocs_with<K, F>(
&self,
key: K,
f: F,
) -> Result<(), TransactionAcqError>
pub fn observe_subdocs_with<K, F>( &self, key: K, f: F, ) -> Result<(), TransactionAcqError>
Subscribe callback function, that will be called whenever a subdocuments inserted in this Doc will request a load.
pub fn unobserve_subdocs<K>(&self, key: K) -> Result<bool, TransactionAcqError>
Sourcepub fn observe_destroy<F>(
&self,
f: F,
) -> Result<Subscription, TransactionAcqError>
pub fn observe_destroy<F>( &self, f: F, ) -> Result<Subscription, TransactionAcqError>
Subscribe callback function, that will be called whenever a [DocRef::destroy] has been called.
pub fn unobserve_destroy<K>(&self, key: K) -> Result<bool, TransactionAcqError>
Sourcepub fn observe_destroy_with<K, F>(
&self,
key: K,
f: F,
) -> Result<(), TransactionAcqError>
pub fn observe_destroy_with<K, F>( &self, key: K, f: F, ) -> Result<(), TransactionAcqError>
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 a 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<'doc> AsyncTransact<'doc> for Doc
impl<'doc> AsyncTransact<'doc> for Doc
type Read = AcquireTransaction<'doc>
type Write = AcquireTransactionMut<'doc>
fn transact(&'doc self) -> Self::Read
fn transact_mut(&'doc self) -> Self::Write
Source§fn transact_mut_with<T>(&'doc self, origin: T) -> Self::Write
fn transact_mut_with<T>(&'doc self, origin: T) -> Self::Write
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§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