Structs
Event pushed into callbacks registered with yarray_observe
function. It contains delta of all
content changes made within a scope of corresponding transaction (see: yarray_event_delta
) as
well as navigation data used to identify a YArray
instance which triggered this event.
A data type representing a single change detected over an observed YText
/YXmlText
. A type
of change can be detected using a tag
field:
A single instance of formatting attribute stored as part of YDelta
instance.
A data type representing a single change detected over an observed shared collection. A type
of change can be detected using a tag
field:
A data type representing a single change made over a map component of shared collection types,
such as YMap
entries or YXmlText
/YXmlElement
attributes. A key
field provides a
corresponding unique key string of a changed entry, while tag
field informs about specific
type of change being done:
A data structure that is used to pass input values of various types supported by Yrs into a shared document store.
A structure representing single key-value entry of a map output (used by either embedded JSON-like maps or YMaps).
Event pushed into callbacks registered with ymap_observe
function. It contains all
key-value changes made within a scope of corresponding transaction (see: ymap_event_keys
) as
well as navigation data used to identify a YMap
instance which triggered this event.
Configuration object used by YDoc
.
An output value cell returned from yrs API methods. It describes a various types of data supported by yrs shared data types.
A single segment of a path returned from yevent_path
function. It can be one of two cases,
recognized by it’s tag
field:
Event pushed into callbacks registered with ytext_observe
function. It contains delta of all
text changes made within a scope of corresponding transaction (see: ytext_event_delta
) as
well as navigation data used to identify a YText
instance which triggered this event.
A structure representing single attribute of an either YXmlElement
or YXmlText
instance.
It consists of attribute name and string, both of which are null-terminated UTF-8 strings.
Event pushed into callbacks registered with yxmlelem_observe
function. It contains
all attribute changes made within a scope of corresponding transaction
(see: yxmlelem_event_keys
) as well as child XML nodes changes (see: yxmlelem_event_delta
)
and navigation data used to identify a YXmlElement
instance which triggered this event.
Event pushed into callbacks registered with yxmltext_observe
function. It contains
all attribute changes made within a scope of corresponding transaction
(see: yxmltext_event_keys
) as well as text edits (see: yxmltext_event_delta
)
and navigation data used to identify a YXmlText
instance which triggered this event.
Constants
Flag used by YInput
and YOutput
to tag content, which is an YArray
shared type.
Tag used to identify YEventChange
(see: yevent_delta
function) case, when a new element
has been added to an observed collection.
Tag used to identify YEventChange
(see: yevent_delta
function) case, when an existing
element has been removed from an observed collection.
Tag used to identify YEventChange
(see: yevent_delta
function) case, when no changes have
been detected for a particular range of observed collection.
Tag used to identify YEventKeyChange
(see: yevent_keys
function) case, when a new entry has
been inserted into a map component of shared collection.
Tag used to identify YEventKeyChange
(see: yevent_keys
function) case, when an existing
entry has been removed from a map component of shared collection.
Tag used to identify YEventKeyChange
(see: yevent_keys
function) case, when an existing
entry has been overridden with a new value within a map component of shared collection.
Tag used to identify YPathSegment
storing an int parameter.
Tag used to identify YPathSegment
storing a *char parameter.
Flag used to mark a falsy boolean numbers.
Flag used by YInput
and YOutput
to tag embedded JSON-like arrays of values,
which themselves are YInput
and YOutput
instances respectively.
Flag used by YInput
and YOutput
to tag boolean values.
Flag used by YInput
and YOutput
to tag binary content.
Flag used by YInput
and YOutput
to tag 64-bit integer numbers.
Flag used by YInput
and YOutput
to tag embedded JSON-like maps of key-value pairs,
where keys are strings and v
Flag used by YInput
and YOutput
to tag JSON-like null values.
Flag used by YInput
and YOutput
to tag floating point numbers.
Flag used by YInput
and YOutput
to tag strings.
Flag used by YInput
and YOutput
to tag JSON-like undefined values.
Flag used by YInput
and YOutput
to tag content, which is an YMap
shared type.
Flag used by YOptions
to determine, that text operations offsets and length will be counted by
the byte number of UTF8-encoded string.
Flag used by YOptions
to determine, that text operations offsets and length will be counted by
UTF-16 chars of encoded string.
Flag used by YOptions
to determine, that text operations offsets and length will be counted by
by UTF-32 chars of encoded string.
Flag used by YInput
and YOutput
to tag content, which is an YText
shared type.
Flag used to mark a truthy boolean numbers.
Flag used by YInput
and YOutput
to tag content, which is an YXmlElement
shared type.
Flag used by YInput
and YOutput
to tag content, which is an YXmlText
shared type.
Functions
Gets or creates a new shared YArray
data type instance as a root-level type of a given document.
This structure can later be accessed using its name
, which must be a null-terminated UTF-8
compatible string.
Returns a sequence of changes produced by sequence component of shared collections (such as
YText
, YXmlText
and XML nodes added to YXmlElement
). len
output parameter is used to
provide information about number of changes produced.
Returns a path from a root type down to a current shared collection (which can be obtained using
yarray_event_target
function). It can consist of either integer indexes (used by sequence
components) of *char keys (used by map components). len
output parameter is used to provide
information about length of the path.
Returns a pointer to a shared collection, which triggered passed event e
.
Returns a pointer to a YOutput
value stored at a given index
of a current YArray
.
If index
is outside of the bounds of an array, a null pointer will be returned.
Inserts a range of items
into current YArray
, starting at given index
. An items_len
parameter is used to determine the size of items
array - it can also be used to insert
a single element given its pointer.
Returns an iterator, which can be used to traverse over all elements of an array
(array
’s
length can be determined using yarray_len function).
Releases all of an YArray
iterator resources created by calling yarray_iter.
Moves current YArray
iterator over to a next element, returning a pointer to it. If an iterator
comes to an end of an array, a null pointer will be returned.
Returns a number of elements stored within current instance of YArray
.
Subscribes a given callback function cb
to changes made by this YArray
instance. Callbacks
are triggered whenever a ytransaction_commit
is called.
Returns a subscription ID which can be then used to unsubscribe this callback by using
yarray_unobserve
function.
Removes a len
of consecutive range of elements from current array
instance, starting at
a given index
. Range determined by index
and len
must fit into boundaries of an array,
otherwise it will panic at runtime.
Releases a callback subscribed via yarray_observe
function represented by passed
observer parameter.
Frees all memory-allocated resources bound to a given binary returned from Yrs document API.
Unlike strings binaries are not null-terminated and can contain null characters inside,
therefore a size of memory to be released must be explicitly provided.
Yrs binaries don’t use libc malloc, so calling free()
on them will fault.
Releases all memory-allocated resources bound to given document.
Creates a new Doc instance with a specified options
.
Releases memory allocated by the object returned from yevent_delta
function.
Releases memory allocated by the object returned from yxml_event_keys
and ymap_event_keys
functions.
Function constructor used to create a binary YInput
cell of a specified length.
This function doesn’t allocate any heap resources and doesn’t release any on its own, therefore
its up to a caller to free resources once a structure is no longer needed.
Function constructor used to create JSON-like boolean YInput
cell.
This function doesn’t allocate any heap resources.
Function constructor used to create JSON-like 64-bit floating point number YInput
cell.
This function doesn’t allocate any heap resources.
Function constructor used to create a JSON-like array YInput
cell of other JSON-like values of
a given length. This function doesn’t allocate any heap resources and doesn’t release any on its
own, therefore its up to a caller to free resources once a structure is no longer needed.
Function constructor used to create a JSON-like map YInput
cell of other JSON-like key-value
pairs. These pairs are build from corresponding indexes of keys
and values
, which must have
the same specified length.
Function constructor used to create JSON-like 64-bit signed integer YInput
cell.
This function doesn’t allocate any heap resources.
Function constructor used to create JSON-like NULL YInput
cell.
This function doesn’t allocate any heap resources.
Function constructor used to create a string YInput
cell. Provided parameter must be
a null-terminated UTF-8 encoded string. This function doesn’t allocate any heap resources,
and doesn’t release any on its own, therefore its up to a caller to free resources once
a structure is no longer needed.
Function constructor used to create JSON-like undefined YInput
cell.
This function doesn’t allocate any heap resources.
Function constructor used to create a nested YArray
YInput
cell prefilled with other
values of a given length. This function doesn’t allocate any heap resources and doesn’t release
any on its own, therefore its up to a caller to free resources once a structure is no longer
needed.
Function constructor used to create a nested YMap
YInput
cell prefilled with other key-value
pairs. These pairs are build from corresponding indexes of keys
and values
, which must have
the same specified length.
Function constructor used to create a nested YText
YInput
cell prefilled with a specified
string, which must be a null-terminated UTF-8 character pointer.
Function constructor used to create a nested YXmlElement
YInput
cell with a specified
tag name, which must be a null-terminated UTF-8 character pointer.
Function constructor used to create a nested YXmlText
YInput
cell prefilled with a specified
string, which must be a null-terminated UTF-8 character pointer.
Gets or creates a new shared YMap
data type instance as a root-level type of a given document.
This structure can later be accessed using its name
, which must be a null-terminated UTF-8
compatible string.
Frees all memory-allocated resources bound to a given YMapEntry.
Returns a sequence of changes produced by map component of shared collections (such as
YMap
and YXmlText
/YXmlElement
attribute changes). len
output parameter is used to
provide information about number of changes produced.
Returns a path from a root type down to a current shared collection (which can be obtained using
ymap_event_target
function). It can consist of either integer indexes (used by sequence
components) of *char keys (used by map components). len
output parameter is used to provide
information about length of the path.
Returns a pointer to a shared collection, which triggered passed event e
.
Returns a value stored under the provided key
, or a null pointer if no entry with such key
has been found in a current map
. A returned value is allocated by this function and therefore
should be eventually released using youtput_destroy function.
Inserts a new entry (specified as key
-value
pair) into a current map
. If entry under such
given key
already existed, its corresponding value will be replaced.
Releases all of an YMap
iterator resources created by calling ymap_iter.
Moves current YMap
iterator over to a next entry, returning a pointer to it. If an iterator
comes to an end of a map, a null pointer will be returned. Yrs maps are unordered and so are
their iterators.
Subscribes a given callback function cb
to changes made by this YMap
instance. Callbacks
are triggered whenever a ytransaction_commit
is called.
Returns a subscription ID which can be then used to unsubscribe this callback by using
ymap_unobserve
function.
Removes a map
entry, given its key
. Returns 1
if the corresponding entry was successfully
removed or 0
if no entry with a provided key
has been found inside of a map
.
Removes all entries from a current map
.
Releases a callback subscribed via ymap_observe
function represented by passed
observer parameter.
Subscribes a given callback function cb
to changes made by this shared type instance as well
as all nested shared types living within it. Callbacks are triggered whenever a
ytransaction_commit
is called.
Releases all resources related to a corresponding YOutput
cell.
Attempts to read the value for a given YOutput
pointer as a binary payload (which length is
stored within len
filed of a cell itself).
Attempts to read the value for a given YOutput
pointer as a boolean flag, which can be either
1
for truthy case and 0
otherwise. Returns a null pointer in case when a value stored under
current YOutput
cell is not of a boolean type.
Attempts to read the value for a given YOutput
pointer as a 64-bit floating point number.
Attempts to read the value for a given YOutput
pointer as a JSON-like array of YOutput
values (which length is stored within len
filed of a cell itself).
Attempts to read the value for a given YOutput
pointer as a JSON-like map of key-value entries
(which length is stored within len
filed of a cell itself).
Attempts to read the value for a given YOutput
pointer as a 64-bit signed integer.
Attempts to read the value for a given YOutput
pointer as a null-terminated UTF-8 encoded
string.
Attempts to read the value for a given YOutput
pointer as an YArray
.
Attempts to read the value for a given YOutput
pointer as an YMap
.
Attempts to read the value for a given YOutput
pointer as an YText
.
Attempts to read the value for a given YOutput
pointer as an YXmlElement
.
Attempts to read the value for a given YOutput
pointer as an YXmlText
.
Releases allocated memory used by objects returned from path accessor functions of shared type events.
Frees all memory-allocated resources bound to a given UTF-8 null-terminated string returned from
Yrs document API. Yrs strings don’t use libc malloc, so calling free()
on them will fault.
Gets or creates a new shared YText
data type instance as a root-level type of a given document.
This structure can later be accessed using its name
, which must be a null-terminated UTF-8
compatible string.
Releases memory allocated by the object returned from yevent_delta
function.
Returns a sequence of changes produced by sequence component of shared collections (such as
YText
, YXmlText
and XML nodes added to YXmlElement
). len
output parameter is used to
provide information about number of changes produced.
Returns a path from a root type down to a current shared collection (which can be obtained using
ytext_event_target
function). It can consist of either integer indexes (used by sequence
components) of *char keys (used by map components). len
output parameter is used to provide
information about length of the path.
Returns a pointer to a shared collection, which triggered passed event e
.
Wraps an existing piece of text within a range described by index
-len
parameters with
formatting blocks containing provided attrs
metadata. attrs
must be a map-like type.
Inserts a null-terminated UTF-8 encoded string a given index
. index
value must be between
0 and a length of a YText
(inclusive, accordingly to ytext_len return value), otherwise this
function will panic.
Inserts an embed content given index
. index
value must be between 0 and a length of a
YText
(inclusive, accordingly to ytext_len return value), otherwise this
function will panic.
Returns the length of the YText
string content in bytes (without the null terminator character)
Subscribes a given callback function cb
to changes made by this YText
instance. Callbacks
are triggered whenever a ytransaction_commit
is called.
Returns a subscription ID which can be then used to unsubscribe this callback by using
ytext_unobserve
function.
Removes a range of characters, starting a a given index
. This range must fit within the bounds
of a current YText
, otherwise this function call will fail.
Returns a null-terminated UTF-8 encoded string content of a current YText
shared data type.
Releases a callback subscribed via ytext_observe
function represented by passed
observer parameter.
Applies an diff update (generated by ytransaction_state_diff_v1) to a local transaction’s document.
Applies an diff update (generated by ytransaction_state_diff_v2) to a local transaction’s document.
Commit and dispose provided transaction. This operation releases allocated resources, triggers update events and performs a storage compression over all operations executed in scope of current transaction.
Starts a new read-write transaction on a given document. All other operations happen in context of a transaction. Yrs transactions do not follow ACID rules. Once a set of operations is complete, a transaction can be finished using ytransaction_commit function.
Returns a delta difference between current state of a transaction’s document and a state vector
sv
encoded as a binary payload using lib0 version 1 encoding (which could be generated using
ytransaction_state_vector_v1). Such delta can be send back to the state vector’s sender in
order to propagate and apply (using ytransaction_apply) all updates known to a current
document, which remote peer was not aware of.
Returns a delta difference between current state of a transaction’s document and a state vector
sv
encoded as a binary payload using lib0 version 1 encoding (which could be generated using
ytransaction_state_vector_v1). Such delta can be send back to the state vector’s sender in
order to propagate and apply (using ytransaction_apply_v2) all updates known to a current
document, which remote peer was not aware of.
Returns a state vector of a current transaction’s document, serialized using lib0 version 1 encoding. Payload created by this function can then be send over the network to a remote peer, where it can be used as a parameter of ytransaction_state_diff_v1 in order to produce a delta update payload, that can be send back and applied locally in order to efficiently propagate updates from one peer to another.
Returns a value informing what kind of Yrs shared collection given branch
represents.
Returns either 0 when branch
is null or one of values: Y_ARRAY
, Y_TEXT
, Y_MAP
,
Y_XML_ELEM
, Y_XML_TEXT
.
Releases a callback subscribed via yobserve_deep
function represented by passed
observer parameter.
Frees all memory-allocated resources bound to a given YXmlAttr.
Releases all of attributes iterator resources created by calling yxmlelem_attr_iter or yxmltext_attr_iter.
Returns a next XML attribute from an iterator
. Attributes are returned in an unordered
manner. Once iterator
reaches the end of attributes collection, a null pointer will be
returned.
Gets or creates a new shared YXmlElement
data type instance as a root-level type of a given
document. This structure can later be accessed using its name
, which must be a null-terminated
UTF-8 compatible string.
Returns an iterator over the YXmlElement
attributes.
Returns a number of child nodes (both YXmlElement
and YXmlText
) living under a current XML
element. This function doesn’t count a recursive nodes, only direct children of a current node.
Returns a sequence of changes produced by sequence component of shared collections (such as
YText
, YXmlText
and XML nodes added to YXmlElement
). len
output parameter is used to
provide information about number of changes produced.
Returns a sequence of changes produced by map component of shared collections.
len
output parameter is used to provide information about number of changes produced.
Returns a path from a root type down to a current shared collection (which can be obtained using
yxmlelem_event_path
function). It can consist of either integer indexes (used by sequence
components) of *char keys (used by map components). len
output parameter is used to provide
information about length of the path.
Returns a pointer to a shared collection, which triggered passed event e
.
Returns a first child node of a current YXmlElement
, or null pointer if current XML node is
empty. Returned value could be either another YXmlElement
or YXmlText
.
Returns an XML child node (either a YXmlElement
or YXmlText
) stored at a given index
of
a current YXmlElement
. Returns null pointer if index
was outside of the bound of current XML
node children.
Returns the value of a current YXmlElement
, given its name, or a null pointer if not attribute
with such name has been found. Returned pointer is a null-terminated UTF-8 encoded string, which
should be released using ystring_destroy function.
Inserts an XML attribute described using attr_name
and attr_value
. If another attribute with
the same name already existed, its value will be replaced with a provided one.
Inserts an YXmlElement
as a child of a current node at the given index
and returns its
pointer. Node created this way will have a given name
as its tag (eg. p
for <p></p>
node).
Inserts an YXmlText
as a child of a current node at the given index
and returns its
pointer.
Returns a next sibling of a current YXmlElement
, which can be either another YXmlElement
or a YXmlText
. Together with yxmlelem_first_child it may be used to iterate over the direct
children of an XML node (in order to iterate over the nested XML structure use
yxmlelem_tree_walker).
Subscribes a given callback function cb
to changes made by this YXmlElement
instance.
Callbacks are triggered whenever a ytransaction_commit
is called.
Returns a subscription ID which can be then used to unsubscribe this callback by using
yxmlelem_unobserve
function.
Returns a parent YXmlElement
of a current node, or null pointer when current YXmlElement
is
a root-level shared data type.
Returns a previous sibling of a current YXmlElement
, which can be either another YXmlElement
or a YXmlText
.
Removes an attribute from a current YXmlElement
, given its name.
Removes a consecutive range of child elements (of specified length) from the current
YXmlElement
, starting at the given index
. Specified range must fit into boundaries of current
XML node children, otherwise this function will panic at runtime.
Converts current YXmlElement
together with its children and attributes into a flat string
representation (no padding) eg. <UNDEFINED><title key="value">sample text</title></UNDEFINED>
.
Return a name (or an XML tag) of a current YXmlElement
. Root-level XML nodes use “UNDEFINED” as
their tag names.
Returns an iterator over a nested recursive structure of a current YXmlElement
, starting from
first of its children. Returned values can be either YXmlElement
or YXmlText
nodes.
Releases resources associated with a current XML tree walker iterator.
Moves current iterator
to a next value (either YXmlElement
or YXmlText
), returning its
pointer or a null, if an iterator
already reached the last successor node.
Releases a callback subscribed via yxmlelem_observe
function represented by passed
observer parameter.
Gets or creates a new shared YXmlText
data type instance as a root-level type of a given
document. This structure can later be accessed using its name
, which must be a null-terminated
UTF-8 compatible string.
Returns an iterator over the YXmlText
attributes.
Returns a sequence of changes produced by sequence component of shared collections (such as
YText
, YXmlText
and XML nodes added to YXmlElement
). len
output parameter is used to
provide information about number of changes produced.
Returns a sequence of changes produced by map component of shared collections.
len
output parameter is used to provide information about number of changes produced.
Returns a path from a root type down to a current shared collection (which can be obtained using
yxmltext_event_path
function). It can consist of either integer indexes (used by sequence
components) of *char keys (used by map components). len
output parameter is used to provide
information about length of the path.
Returns a pointer to a shared collection, which triggered passed event e
.
Wraps an existing piece of text within a range described by index
-len
parameters with
formatting blocks containing provided attrs
metadata. attrs
must be a map-like type.
Returns the value of a current YXmlText
, given its name, or a null pointer if not attribute
with such name has been found. Returned pointer is a null-terminated UTF-8 encoded string, which
should be released using ystring_destroy function.
Inserts a null-terminated UTF-8 encoded string a a given index
. index
value must be between
0 and a length of a YXmlText
(inclusive, accordingly to yxmltext_len return value), otherwise
this function will panic.
Inserts an XML attribute described using attr_name
and attr_value
. If another attribute with
the same name already existed, its value will be replaced with a provided one.
Inserts an embed content given index
. index
value must be between 0 and a length of a
YXmlText
(inclusive, accordingly to ytext_len return value), otherwise this
function will panic.
Returns the length of the YXmlText
string content in bytes (without the null terminator
character)
Returns a next sibling of a current YXmlText
, which can be either another YXmlText
or
an YXmlElement
. Together with yxmlelem_first_child it may be used to iterate over the direct
children of an XML node (in order to iterate over the nested XML structure use
yxmlelem_tree_walker).
Subscribes a given callback function cb
to changes made by this YXmlText
instance. Callbacks
are triggered whenever a ytransaction_commit
is called.
Returns a subscription ID which can be then used to unsubscribe this callback by using
yxmltext_unobserve
function.
Returns a previous sibling of a current YXmlText
, which can be either another YXmlText
or
an YXmlElement
.
Removes an attribute from a current YXmlText
, given its name.
Removes a range of characters, starting a a given index
. This range must fit within the bounds
of a current YXmlText
, otherwise this function call will fail.
Returns a null-terminated UTF-8 encoded string content of a current YXmlText
shared data type.
Releases a callback subscribed via yxmltext_observe
function represented by passed
observer parameter.
Type Definitions
Iterator structure used by shared array data type.
Iterator structure used by XML nodes (elements and text) to iterate over node’s attributes. Attribute iterators are unordered - there’s no specific order in which map entries will be returned during consecutive iterator calls.
A common shared data type. All Yrs instances can be refered to using this data type (use
ytype_kind
function if a specific type needs to be determined). Branch pointers are passed
over type-specific functions like ytext_insert
, yarray_insert
or ymap_insert
to perform
a specific shared type operations.
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 YTransaction
, which lifetime is also bound to a document.
Iterator structure used by shared map data type. Map iterators are unordered - there’s no specific order in which map entries will be returned during consecutive iterator calls.
Transaction is one of the core types in Yrs. All operations that need to touch a document’s contents (a.k.a. block store), need to be executed in scope of a transaction.
Iterator used to traverse over the complex nested tree structure of a XML node. XML node
iterator walks only over YXmlElement
and YXmlText
nodes. It does so in ordered manner (using
the order in which children are ordered within their parent nodes) and using depth-first
traverse.