libyrs.h
1/**
2 * The MIT License (MIT)
3 *
4 * Copyright (c) 2020
5 * - Bartosz Sypytkowski <[email protected]>
6 * - Kevin Jahns <[email protected]>.
7 *
8 * Permission is hereby granted, free of charge, to any person obtaining a copy
9 * of this software and associated documentation files (the "Software"), to deal
10 * in the Software without restriction, including without limitation the rights
11 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12 * copies of the Software, and to permit persons to whom the Software is
13 * furnished to do so, subject to the following conditions:
14 *
15 * The above copyright notice and this permission notice shall be included in all
16 * copies or substantial portions of the Software.
17 *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24 * SOFTWARE.
25 */
26
27#ifndef YRS_FFI_H
28#define YRS_FFI_H
29
30/**
31 * A Yrs document type. Documents are most important units of collaborative resources management.
32 * All shared collections live within a scope of their corresponding documents. All updates are
33 * generated on per document basis (rather than individual shared type). All operations on shared
34 * collections happen via `YTransaction`, which lifetime is also bound to a document.
35 *
36 * Document manages so called root types, which are top-level shared types definitions (as opposed
37 * to recursively nested types).
38 */
39typedef struct YDoc {} YDoc;
40
41/**
42 * A common shared data type. All Yrs instances can be refered to using this data type (use
43 * `ytype_kind` function if a specific type needs to be determined). Branch pointers are passed
44 * over type-specific functions like `ytext_insert`, `yarray_insert` or `ymap_insert` to perform
45 * a specific shared type operations.
46 *
47 * Using write methods of different shared types (eg. `ytext_insert` and `yarray_insert`) over
48 * the same branch may result in undefined behavior.
49 */
50typedef struct Branch {} Branch;
51
52typedef struct Transaction {} Transaction;
53typedef struct TransactionMut {} TransactionMut;
54
55/**
56 * Iterator structure used by weak link unquote.
57 */
58typedef struct YWeakIter {} YWeakIter;
59
60/**
61 * Iterator structure used by shared array data type.
62 */
63typedef struct YArrayIter {} YArrayIter;
64
65/**
66 * Iterator structure used by shared map data type. Map iterators are unordered - there's no
67 * specific order in which map entries will be returned during consecutive iterator calls.
68 */
69typedef struct YMapIter {} YMapIter;
70
71/**
72 * Iterator structure used by shared JSON Path expressions over document content.
73 */
74typedef struct YJsonPathIter {} YJsonPathIter;
75
76/**
77 * Iterator structure used by XML nodes (elements and text) to iterate over node's attributes.
78 * Attribute iterators are unordered - there's no specific order in which map entries will be
79 * returned during consecutive iterator calls.
80 */
81typedef struct YXmlAttrIter {} YXmlAttrIter;
82
83/**
84 * Iterator used to traverse over the complex nested tree structure of a XML node. XML node
85 * iterator walks only over `YXmlElement` and `YXmlText` nodes. It does so in ordered manner (using
86 * the order in which children are ordered within their parent nodes) and using **depth-first**
87 * traverse.
88 */
89typedef struct YXmlTreeWalker {} YXmlTreeWalker;
90
91typedef struct YUndoManager {} YUndoManager;
92typedef struct LinkSource {} LinkSource;
93typedef struct Unquote {} Unquote;
94typedef struct StickyIndex {} StickyIndex;
95typedef struct YSubscription {} YSubscription;
96
97
98#include <stdarg.h>
99#include <stdbool.h>
100#include <stdint.h>
101#include <stdlib.h>
102
103/**
104 * Flag used by `YInput` to pass JSON string for an object that should be deserialized and
105 * stored internally as fully fledged scalar type.
106 */
107#define Y_JSON -9
108
109/**
110 * Flag used by `YInput` and `YOutput` to tag boolean values.
111 */
112#define Y_JSON_BOOL -8
113
114/**
115 * Flag used by `YInput` and `YOutput` to tag floating point numbers.
116 */
117#define Y_JSON_NUM -7
118
119/**
120 * Flag used by `YInput` and `YOutput` to tag 64-bit integer numbers.
121 */
122#define Y_JSON_INT -6
123
124/**
125 * Flag used by `YInput` and `YOutput` to tag strings.
126 */
127#define Y_JSON_STR -5
128
129/**
130 * Flag used by `YInput` and `YOutput` to tag binary content.
131 */
132#define Y_JSON_BUF -4
133
134/**
135 * Flag used by `YInput` and `YOutput` to tag embedded JSON-like arrays of values,
136 * which themselves are `YInput` and `YOutput` instances respectively.
137 */
138#define Y_JSON_ARR -3
139
140/**
141 * Flag used by `YInput` and `YOutput` to tag embedded JSON-like maps of key-value pairs,
142 * where keys are strings and v
143 */
144#define Y_JSON_MAP -2
145
146/**
147 * Flag used by `YInput` and `YOutput` to tag JSON-like null values.
148 */
149#define Y_JSON_NULL -1
150
151/**
152 * Flag used by `YInput` and `YOutput` to tag JSON-like undefined values.
153 */
154#define Y_JSON_UNDEF 0
155
156/**
157 * Flag used by `YInput` and `YOutput` to tag content, which is an `YArray` shared type.
158 */
159#define Y_ARRAY 1
160
161/**
162 * Flag used by `YInput` and `YOutput` to tag content, which is an `YMap` shared type.
163 */
164#define Y_MAP 2
165
166/**
167 * Flag used by `YInput` and `YOutput` to tag content, which is an `YText` shared type.
168 */
169#define Y_TEXT 3
170
171/**
172 * Flag used by `YInput` and `YOutput` to tag content, which is an `YXmlElement` shared type.
173 */
174#define Y_XML_ELEM 4
175
176/**
177 * Flag used by `YInput` and `YOutput` to tag content, which is an `YXmlText` shared type.
178 */
179#define Y_XML_TEXT 5
180
181/**
182 * Flag used by `YInput` and `YOutput` to tag content, which is an `YXmlFragment` shared type.
183 */
184#define Y_XML_FRAG 6
185
186/**
187 * Flag used by `YInput` and `YOutput` to tag content, which is an `YDoc` shared type.
188 */
189#define Y_DOC 7
190
191/**
192 * Flag used by `YInput` and `YOutput` to tag content, which is an `YWeakLink` shared type.
193 */
194#define Y_WEAK_LINK 8
195
196/**
197 * Flag used by `YOutput` to tag content, which is an undefined shared type. This usually happens
198 * when it's referencing a root type that has not been initalized localy.
199 */
200#define Y_UNDEFINED 9
201
202/**
203 * Flag used to mark a truthy boolean numbers.
204 */
205#define Y_TRUE 1
206
207/**
208 * Flag used to mark a falsy boolean numbers.
209 */
210#define Y_FALSE 0
211
212/**
213 * Flag used by `YOptions` to determine, that text operations offsets and length will be counted by
214 * the byte number of UTF8-encoded string.
215 */
216#define Y_OFFSET_BYTES 0
217
218/**
219 * Flag used by `YOptions` to determine, that text operations offsets and length will be counted by
220 * UTF-16 chars of encoded string.
221 */
222#define Y_OFFSET_UTF16 1
223
224/**
225 * Boolean flag used to determine if deleted blocks should be garbage collected or not
226 * during the transaction commits. Setting this value to 0 means GC will be performed.
227 */
228#define Y_SKIP_GC (1 << 1)
229
230/**
231 * Boolean flag used to determine if subdocument should be loaded automatically.
232 * If this is a subdocument, remote peers will load the document as well automatically.
233 */
234#define Y_AUTO_LOAD (1 << 2)
235
236/**
237 * Boolean flag used to determine whether the document should be synced by the provider now.
238 */
239#define Y_SHOULD_LOAD (1 << 3)
240
241/**
242 * Whenever we receive an update that might remove piece of text, it might turn out that it was
243 * surrounded by the formatting attributes, that now are effectively dead and unrenderable, but
244 * still are considered alive blocks.
245 *
246 * This flag orders cleanup of dangling formatting attributes.
247 */
248#define Y_CLEANUP_FMT (1 << 4)
249
250/**
251 * Error code: couldn't read data from input stream.
252 */
253#define ERR_CODE_IO 1
254
255/**
256 * Error code: decoded variable integer outside of the expected integer size bounds.
257 */
258#define ERR_CODE_VAR_INT 2
259
260/**
261 * Error code: end of stream found when more data was expected.
262 */
263#define ERR_CODE_EOS 3
264
265/**
266 * Error code: decoded enum tag value was not among known cases.
267 */
268#define ERR_CODE_UNEXPECTED_VALUE 4
269
270/**
271 * Error code: failure when trying to decode JSON content.
272 */
273#define ERR_CODE_INVALID_JSON 5
274
275/**
276 * Error code: other error type than the one specified.
277 */
278#define ERR_CODE_OTHER 6
279
280/**
281 * Error code: not enough memory to perform an operation.
282 */
283#define ERR_NOT_ENOUGH_MEMORY 7
284
285/**
286 * Error code: conversion attempt to specific Rust type was not possible.
287 */
288#define ERR_TYPE_MISMATCH 8
289
290/**
291 * Error code: miscellaneous error coming from serde, not covered by other error codes.
292 */
293#define ERR_CUSTOM 9
294
295/**
296 * Error code: update block assigned to parent that is not a valid shared ref of deleted block.
297 */
298#define ERR_INVALID_PARENT 9
299
300#define YCHANGE_ADD 1
301
302#define YCHANGE_RETAIN 0
303
304#define YCHANGE_REMOVE -1
305
306#define Y_KIND_UNDO 0
307
308#define Y_KIND_REDO 1
309
310/**
311 * Tag used to identify `YPathSegment` storing a *char parameter.
312 */
313#define Y_EVENT_PATH_KEY 1
314
315/**
316 * Tag used to identify `YPathSegment` storing an int parameter.
317 */
318#define Y_EVENT_PATH_INDEX 2
319
320/**
321 * Tag used to identify `YEventChange` (see: `yevent_delta` function) case, when a new element
322 * has been added to an observed collection.
323 */
324#define Y_EVENT_CHANGE_ADD 1
325
326/**
327 * Tag used to identify `YEventChange` (see: `yevent_delta` function) case, when an existing
328 * element has been removed from an observed collection.
329 */
330#define Y_EVENT_CHANGE_DELETE 2
331
332/**
333 * Tag used to identify `YEventChange` (see: `yevent_delta` function) case, when no changes have
334 * been detected for a particular range of observed collection.
335 */
336#define Y_EVENT_CHANGE_RETAIN 3
337
338/**
339 * Tag used to identify `YEventKeyChange` (see: `yevent_keys` function) case, when a new entry has
340 * been inserted into a map component of shared collection.
341 */
342#define Y_EVENT_KEY_CHANGE_ADD 4
343
344/**
345 * Tag used to identify `YEventKeyChange` (see: `yevent_keys` function) case, when an existing
346 * entry has been removed from a map component of shared collection.
347 */
348#define Y_EVENT_KEY_CHANGE_DELETE 5
349
350/**
351 * Tag used to identify `YEventKeyChange` (see: `yevent_keys` function) case, when an existing
352 * entry has been overridden with a new value within a map component of shared collection.
353 */
354#define Y_EVENT_KEY_CHANGE_UPDATE 6
355
356typedef struct TransactionInner TransactionInner;
357
358/**
359 * Configuration object used by `YDoc`.
360 */
361typedef struct YOptions {
362 /**
363 * Globally unique 53-bit integer assigned to corresponding document replica as its identifier.
364 *
365 * If two clients share the same `id` and will perform any updates, it will result in
366 * unrecoverable document state corruption. The same thing may happen if the client restored
367 * document state from snapshot, that didn't contain all of that clients updates that were sent
368 * to other peers.
369 */
370 uint64_t id;
371 /**
372 * A NULL-able globally unique Uuid v4 compatible null-terminated string identifier
373 * of this document. If passed as NULL, a random Uuid will be generated instead.
374 */
375 const char *guid;
376 /**
377 * A NULL-able, UTF-8 encoded, null-terminated string of a collection that this document
378 * belongs to. It's used only by providers.
379 */
380 const char *collection_id;
381 /**
382 * Boolean flags used to configure document options:
383 * - `Y_OFFSET_BYTES`: use UTF-8 byte length for text indexes and offsets.
384 * - `Y_OFFSET_UTF16`: use UTF-16 code points for text indexes and offsets.
385 * - `Y_SKIP_GC`: skip automatic garbage collection at transaction commit (useful for snapshots and keeping historical traces).
386 * - `Y_AUTO_LOAD`: all subdocuments should be loaded automatically.
387 * - `Y_SHOULD_LOAD`: should current document be synced with its provider immediatelly?
388 * - `Y_CLEANUP_TEXT_FMT`: automatically remove dangling formatting attributes.
389 */
390 uint8_t flags;
391} YOptions;
392
393/**
394 * A Yrs document type. Documents are the most important units of collaborative resources management.
395 * All shared collections live within a scope of their corresponding documents. All updates are
396 * generated on per-document basis (rather than individual shared type). All operations on shared
397 * collections happen via `YTransaction`, which lifetime is also bound to a document.
398 *
399 * Document manages so-called root types, which are top-level shared types definitions (as opposed
400 * to recursively nested types).
401 */
402typedef YDoc YDoc;
403
404/**
405 * A common shared data type. All Yrs instances can be refered to using this data type (use
406 * `ytype_kind` function if a specific type needs to be determined). Branch pointers are passed
407 * over type-specific functions like `ytext_insert`, `yarray_insert` or `ymap_insert` to perform
408 * a specific shared type operations.
409 *
410 * Using write methods of different shared types (eg. `ytext_insert` and `yarray_insert`) over
411 * the same branch may result in undefined behavior.
412 */
413typedef Branch Branch;
414
415typedef union YOutputContent {
416 uint8_t flag;
417 double num;
418 int64_t integer;
419 char *str;
420 const char *buf;
421 struct YOutput *array;
422 struct YMapEntry *map;
423 Branch *y_type;
424 YDoc *y_doc;
425} YOutputContent;
426
427/**
428 * An output value cell returned from yrs API methods. It describes a various types of data
429 * supported by yrs shared data types.
430 *
431 * Since `YOutput` instances are always created by calling the corresponding yrs API functions,
432 * they eventually should be deallocated using [youtput_destroy] function.
433 */
434typedef struct YOutput {
435 /**
436 * Tag describing, which `value` type is being stored by this input cell. Can be one of:
437 *
438 * - [Y_JSON_BOOL] for boolean flags.
439 * - [Y_JSON_NUM] for 64-bit floating point numbers.
440 * - [Y_JSON_INT] for 64-bit signed integers.
441 * - [Y_JSON_STR] for null-terminated UTF-8 encoded strings.
442 * - [Y_JSON_BUF] for embedded binary data.
443 * - [Y_JSON_ARR] for arrays of JSON-like values.
444 * - [Y_JSON_MAP] for JSON-like objects build from key-value pairs.
445 * - [Y_JSON_NULL] for JSON-like null values.
446 * - [Y_JSON_UNDEF] for JSON-like undefined values.
447 * - [Y_TEXT] for pointers to `YText` data types.
448 * - [Y_ARRAY] for pointers to `YArray` data types.
449 * - [Y_MAP] for pointers to `YMap` data types.
450 * - [Y_XML_ELEM] for pointers to `YXmlElement` data types.
451 * - [Y_XML_TEXT] for pointers to `YXmlText` data types.
452 * - [Y_DOC] for pointers to nested `YDocRef` data types.
453 */
454 int8_t tag;
455 /**
456 * Length of the contents stored by a current `YOutput` cell.
457 *
458 * For [Y_JSON_NULL] and [Y_JSON_UNDEF] its equal to `0`.
459 *
460 * For [Y_JSON_ARR], [Y_JSON_MAP] it describes a number of passed elements.
461 *
462 * For other types it's always equal to `1`.
463 */
464 uint32_t len;
465 /**
466 * Union struct which contains a content corresponding to a provided `tag` field.
467 */
468 union YOutputContent value;
469} YOutput;
470
471/**
472 * A structure representing single key-value entry of a map output (used by either
473 * embedded JSON-like maps or YMaps).
474 */
475typedef struct YMapEntry {
476 /**
477 * Null-terminated string representing an entry's key component. Encoded as UTF-8.
478 */
479 const char *key;
480 /**
481 * A `YOutput` value representing containing variadic content that can be stored withing map's
482 * entry.
483 */
484 const struct YOutput *value;
485} YMapEntry;
486
487/**
488 * A structure representing single attribute of an either `YXmlElement` or `YXmlText` instance.
489 * It consists of attribute name and string, both of which are null-terminated UTF-8 strings.
490 */
491typedef struct YXmlAttr {
492 const char *name;
493 const struct YOutput *value;
494} YXmlAttr;
495
496/**
497 * Subscription to any kind of observable events, like `ymap_observe`, `ydoc_observe_updates_v1` etc.
498 * This subscription can be destroyed by calling `yunobserve` function, which will cause to unsubscribe
499 * correlated callback.
500 */
501typedef YSubscription YSubscription;
502
503/**
504 * Struct representing a state of a document. It contains the last seen clocks for blocks submitted
505 * per any of the clients collaborating on document updates.
506 */
507typedef struct YStateVector {
508 /**
509 * Number of clients. It describes a length of both `client_ids` and `clocks` arrays.
510 */
511 uint32_t entries_count;
512 /**
513 * Array of unique client identifiers (length is given in `entries_count` field). Each client
514 * ID has corresponding clock attached, which can be found in `clocks` field under the same
515 * index.
516 */
517 uint64_t *client_ids;
518 /**
519 * Array of clocks (length is given in `entries_count` field) known for each client. Each clock
520 * has a corresponding client identifier attached, which can be found in `client_ids` field
521 * under the same index.
522 */
523 uint32_t *clocks;
524} YStateVector;
525
526typedef struct YIdRange {
527 uint32_t start;
528 uint32_t end;
529} YIdRange;
530
531/**
532 * Fixed-length sequence of ID ranges. Each range is a pair of [start, end) values, describing the
533 * range of items identified by clock values, that this range refers to.
534 */
535typedef struct YIdRangeSeq {
536 /**
537 * Number of ranges stored in this sequence.
538 */
539 uint32_t len;
540 /**
541 * Array (length is stored in `len` field) or ranges. Each range is a pair of [start, end)
542 * values, describing continuous collection of items produced by the same client, identified
543 * by clock values, that this range refers to.
544 */
545 struct YIdRange *seq;
546} YIdRangeSeq;
547
548/**
549 * Delete set is a map of `(ClientID, Range[])` entries. Length of a map is stored in
550 * `entries_count` field. ClientIDs reside under `client_ids` and their corresponding range
551 * sequences can be found under the same index of `ranges` field.
552 */
553typedef struct YIdSet {
554 /**
555 * Number of client identifier entries.
556 */
557 uint32_t entries_count;
558 /**
559 * Array of unique client identifiers (length is given in `entries_count` field). Each client
560 * ID has corresponding sequence of ranges attached, which can be found in `ranges` field under
561 * the same index.
562 */
563 uint64_t *client_ids;
564 /**
565 * Array of range sequences (length is given in `entries_count` field). Each sequence has
566 * a corresponding client ID attached, which can be found in `client_ids` field under
567 * the same index.
568 */
569 struct YIdRangeSeq *ranges;
570} YIdSet;
571
572/**
573 * Event generated for callbacks subscribed using `ydoc_observe_after_transaction`. It contains
574 * snapshot of changes made within any committed transaction.
575 */
576typedef struct YAfterTransactionEvent {
577 /**
578 * Descriptor of a document state at the moment of creating the transaction.
579 */
580 struct YStateVector before_state;
581 /**
582 * Descriptor of a document state at the moment of committing the transaction.
583 */
584 struct YStateVector after_state;
585 /**
586 * Information about all items deleted within the scope of a transaction.
587 */
588 struct YIdSet delete_set;
589} YAfterTransactionEvent;
590
591typedef struct YSubdocsEvent {
592 uint32_t added_len;
593 uint32_t removed_len;
594 uint32_t loaded_len;
595 YDoc **added;
596 YDoc **removed;
597 YDoc **loaded;
598} YSubdocsEvent;
599
600/**
601 * Transaction is one of the core types in Yrs. All operations that need to touch or
602 * modify a document's contents (a.k.a. block store), need to be executed in scope of a
603 * transaction.
604 */
605typedef struct TransactionInner YTransaction;
606
607/**
608 * Structure containing unapplied update data.
609 * Created via `ytransaction_pending_update`.
610 * Released via `ypending_update_destroy`.
611 */
612typedef struct YPendingUpdate {
613 /**
614 * A state vector that informs about minimal client clock values that need to be satisfied
615 * in order to successfully apply current update.
616 */
617 struct YStateVector missing;
618 /**
619 * Update data stored in lib0 v1 format.
620 */
621 char *update_v1;
622 /**
623 * Length of `update_v1` payload.
624 */
625 uint32_t update_len;
626} YPendingUpdate;
627
628typedef struct YMapInputData {
629 char **keys;
630 struct YInput *values;
631} YMapInputData;
632
633typedef LinkSource Weak;
634
635typedef union YInputContent {
636 uint8_t flag;
637 double num;
638 int64_t integer;
639 char *str;
640 char *buf;
641 struct YInput *values;
642 struct YMapInputData map;
643 YDoc *doc;
644 const Weak *weak;
645} YInputContent;
646
647/**
648 * A data structure that is used to pass input values of various types supported by Yrs into a
649 * shared document store.
650 *
651 * `YInput` constructor function don't allocate any resources on their own, neither they take
652 * ownership by pointers to memory blocks allocated by user - for this reason once an input cell
653 * has been used, its content should be freed by the caller.
654 */
655typedef struct YInput {
656 /**
657 * Tag describing, which `value` type is being stored by this input cell. Can be one of:
658 *
659 * - [Y_JSON] for a UTF-8 encoded, NULL-terminated JSON string.
660 * - [Y_JSON_BOOL] for boolean flags.
661 * - [Y_JSON_NUM] for 64-bit floating point numbers.
662 * - [Y_JSON_INT] for 64-bit signed integers.
663 * - [Y_JSON_STR] for null-terminated UTF-8 encoded strings.
664 * - [Y_JSON_BUF] for embedded binary data.
665 * - [Y_JSON_ARR] for arrays of JSON-like values.
666 * - [Y_JSON_MAP] for JSON-like objects build from key-value pairs.
667 * - [Y_JSON_NULL] for JSON-like null values.
668 * - [Y_JSON_UNDEF] for JSON-like undefined values.
669 * - [Y_ARRAY] for cells which contents should be used to initialize a `YArray` shared type.
670 * - [Y_MAP] for cells which contents should be used to initialize a `YMap` shared type.
671 * - [Y_DOC] for cells which contents should be used to nest a `YDoc` sub-document.
672 * - [Y_WEAK_LINK] for cells which contents should be used to nest a `YWeakLink` sub-document.
673 */
674 int8_t tag;
675 /**
676 * Length of the contents stored by current `YInput` cell.
677 *
678 * For [Y_JSON_NULL] and [Y_JSON_UNDEF] its equal to `0`.
679 *
680 * For [Y_JSON_ARR], [Y_JSON_MAP], [Y_ARRAY] and [Y_MAP] it describes a number of passed
681 * elements.
682 *
683 * For other types it's always equal to `1`.
684 */
685 uint32_t len;
686 /**
687 * Union struct which contains a content corresponding to a provided `tag` field.
688 */
689 union YInputContent value;
690} YInput;
691
692/**
693 * A data type representing a single change to be performed in sequence of changes defined
694 * as parameter to a `ytext_insert_delta` function. A type of change can be detected using
695 * a `tag` field:
696 *
697 * 1. `Y_EVENT_CHANGE_ADD` marks a new characters added to a collection. In this case `insert`
698 * field contains a pointer to a list of newly inserted values, while `len` field informs about
699 * their count. Additionally `attributes_len` and `attributes` carry information about optional
700 * formatting attributes applied to edited blocks.
701 * 2. `Y_EVENT_CHANGE_DELETE` marks an existing elements removed from the collection. In this case
702 * `len` field informs about number of removed elements.
703 * 3. `Y_EVENT_CHANGE_RETAIN` marks a number of characters that have not been changed, counted from
704 * the previous element. `len` field informs about number of retained elements. Additionally
705 * `attributes_len` and `attributes` carry information about optional formatting attributes applied
706 * to edited blocks.
707 */
708typedef struct YDeltaIn {
709 /**
710 * Tag field used to identify particular type of change made:
711 *
712 * 1. `Y_EVENT_CHANGE_ADD` marks a new elements added to a collection. In this case `values`
713 * field contains a pointer to a list of newly inserted values, while `len` field informs about
714 * their count.
715 * 2. `Y_EVENT_CHANGE_DELETE` marks an existing elements removed from the collection. In this
716 * case `len` field informs about number of removed elements.
717 * 3. `Y_EVENT_CHANGE_RETAIN` marks a number of elements that have not been changed, counted
718 * from the previous element. `len` field informs about number of retained elements.
719 */
720 uint8_t tag;
721 /**
722 * Number of element affected by current type of change. It can refer to a number of
723 * inserted `values`, number of deleted element or a number of retained (unchanged) values.
724 */
725 uint32_t len;
726 /**
727 * A nullable pointer to a list of formatting attributes assigned to an edited area represented
728 * by this delta.
729 */
730 const struct YInput *attributes;
731 /**
732 * Used in case when current change is of `Y_EVENT_CHANGE_ADD` type. Contains a list (of
733 * length stored in `len` field) of newly inserted values.
734 */
735 const struct YInput *insert;
736} YDeltaIn;
737
738/**
739 * A chunk of text contents formatted with the same set of attributes.
740 */
741typedef struct YChunk {
742 /**
743 * Piece of YText formatted using the same `fmt` rules. It can be a string, embedded object
744 * or another y-type.
745 */
746 struct YOutput data;
747 /**
748 * Number of formatting attributes attached to current chunk of text.
749 */
750 uint32_t fmt_len;
751 /**
752 * The formatting attributes attached to the current chunk of text.
753 */
754 struct YMapEntry *fmt;
755} YChunk;
756
757/**
758 * Event pushed into callbacks registered with `ytext_observe` function. It contains delta of all
759 * text changes made within a scope of corresponding transaction (see: `ytext_event_delta`) as
760 * well as navigation data used to identify a `YText` instance which triggered this event.
761 */
762typedef struct YTextEvent {
763 const void *inner;
764 const TransactionMut *txn;
765} YTextEvent;
766
767/**
768 * Event pushed into callbacks registered with `ymap_observe` function. It contains all
769 * key-value changes made within a scope of corresponding transaction (see: `ymap_event_keys`) as
770 * well as navigation data used to identify a `YMap` instance which triggered this event.
771 */
772typedef struct YMapEvent {
773 const void *inner;
774 const TransactionMut *txn;
775} YMapEvent;
776
777/**
778 * Event pushed into callbacks registered with `yarray_observe` function. It contains delta of all
779 * content changes made within a scope of corresponding transaction (see: `yarray_event_delta`) as
780 * well as navigation data used to identify a `YArray` instance which triggered this event.
781 */
782typedef struct YArrayEvent {
783 const void *inner;
784 const TransactionMut *txn;
785} YArrayEvent;
786
787/**
788 * Event pushed into callbacks registered with `yxmlelem_observe` function. It contains
789 * all attribute changes made within a scope of corresponding transaction
790 * (see: `yxmlelem_event_keys`) as well as child XML nodes changes (see: `yxmlelem_event_delta`)
791 * and navigation data used to identify a `YXmlElement` instance which triggered this event.
792 */
793typedef struct YXmlEvent {
794 const void *inner;
795 const TransactionMut *txn;
796} YXmlEvent;
797
798/**
799 * Event pushed into callbacks registered with `yxmltext_observe` function. It contains
800 * all attribute changes made within a scope of corresponding transaction
801 * (see: `yxmltext_event_keys`) as well as text edits (see: `yxmltext_event_delta`)
802 * and navigation data used to identify a `YXmlText` instance which triggered this event.
803 */
804typedef struct YXmlTextEvent {
805 const void *inner;
806 const TransactionMut *txn;
807} YXmlTextEvent;
808
809/**
810 * Event pushed into callbacks registered with `yweak_observe` function. It contains
811 * all an event changes of the underlying transaction.
812 */
813typedef struct YWeakLinkEvent {
814 const void *inner;
815 const TransactionMut *txn;
816} YWeakLinkEvent;
817
818typedef union YEventContent {
819 struct YTextEvent text;
820 struct YMapEvent map;
821 struct YArrayEvent array;
822 struct YXmlEvent xml_elem;
823 struct YXmlTextEvent xml_text;
824 struct YWeakLinkEvent weak;
825} YEventContent;
826
827typedef struct YEvent {
828 /**
829 * Tag describing, which shared type emitted this event.
830 *
831 * - [Y_TEXT] for pointers to `YText` data types.
832 * - [Y_ARRAY] for pointers to `YArray` data types.
833 * - [Y_MAP] for pointers to `YMap` data types.
834 * - [Y_XML_ELEM] for pointers to `YXmlElement` data types.
835 * - [Y_XML_TEXT] for pointers to `YXmlText` data types.
836 */
837 int8_t tag;
838 /**
839 * A nested event type, specific for a shared data type that triggered it. Type of an
840 * event can be verified using `tag` field.
841 */
842 union YEventContent content;
843} YEvent;
844
845typedef union YPathSegmentCase {
846 const char *key;
847 uint32_t index;
848} YPathSegmentCase;
849
850/**
851 * A single segment of a path returned from `yevent_path` function. It can be one of two cases,
852 * recognized by it's `tag` field:
853 *
854 * 1. `Y_EVENT_PATH_KEY` means that segment value can be accessed by `segment.value.key` and is
855 * referring to a string key used by map component (eg. `YMap` entry).
856 * 2. `Y_EVENT_PATH_INDEX` means that segment value can be accessed by `segment.value.index` and is
857 * referring to an int index used by sequence component (eg. `YArray` item or `YXmlElement` child).
858 */
859typedef struct YPathSegment {
860 /**
861 * Tag used to identify which case current segment is referring to:
862 *
863 * 1. `Y_EVENT_PATH_KEY` means that segment value can be accessed by `segment.value.key` and is
864 * referring to a string key used by map component (eg. `YMap` entry).
865 * 2. `Y_EVENT_PATH_INDEX` means that segment value can be accessed by `segment.value.index`
866 * and is referring to an int index used by sequence component (eg. `YArray` item or
867 * `YXmlElement` child).
868 */
869 char tag;
870 /**
871 * Union field containing either `key` or `index`. A particular case can be recognized by using
872 * segment's `tag` field.
873 */
874 union YPathSegmentCase value;
875} YPathSegment;
876
877/**
878 * A single instance of formatting attribute stored as part of `YDelta` instance.
879 */
880typedef struct YDeltaAttr {
881 /**
882 * A null-terminated UTF-8 encoded string containing a unique formatting attribute name.
883 */
884 const char *key;
885 /**
886 * A value assigned to a formatting attribute.
887 */
888 struct YOutput value;
889} YDeltaAttr;
890
891/**
892 * A data type representing a single change detected over an observed `YText`/`YXmlText`. A type
893 * of change can be detected using a `tag` field:
894 *
895 * 1. `Y_EVENT_CHANGE_ADD` marks a new characters added to a collection. In this case `insert`
896 * field contains a pointer to a list of newly inserted values, while `len` field informs about
897 * their count. Additionally `attributes_len` and `attributes` carry information about optional
898 * formatting attributes applied to edited blocks.
899 * 2. `Y_EVENT_CHANGE_DELETE` marks an existing elements removed from the collection. In this case
900 * `len` field informs about number of removed elements.
901 * 3. `Y_EVENT_CHANGE_RETAIN` marks a number of characters that have not been changed, counted from
902 * the previous element. `len` field informs about number of retained elements. Additionally
903 * `attributes_len` and `attributes` carry information about optional formatting attributes applied
904 * to edited blocks.
905 *
906 * A list of changes returned by `ytext_event_delta`/`yxmltext_event_delta` enables to locate
907 * a position of all changes within an observed collection by using a combination of added/deleted
908 * change structs separated by retained changes (marking eg. number of elements that can be safely
909 * skipped, since they remained unchanged).
910 */
911typedef struct YDeltaOut {
912 /**
913 * Tag field used to identify particular type of change made:
914 *
915 * 1. `Y_EVENT_CHANGE_ADD` marks a new elements added to a collection. In this case `values`
916 * field contains a pointer to a list of newly inserted values, while `len` field informs about
917 * their count.
918 * 2. `Y_EVENT_CHANGE_DELETE` marks an existing elements removed from the collection. In this
919 * case `len` field informs about number of removed elements.
920 * 3. `Y_EVENT_CHANGE_RETAIN` marks a number of elements that have not been changed, counted
921 * from the previous element. `len` field informs about number of retained elements.
922 */
923 uint8_t tag;
924 /**
925 * Number of element affected by current type of change. It can refer to a number of
926 * inserted `values`, number of deleted element or a number of retained (unchanged) values.
927 */
928 uint32_t len;
929 /**
930 * A number of formatting attributes assigned to an edited area represented by this delta.
931 */
932 uint32_t attributes_len;
933 /**
934 * A nullable pointer to a list of formatting attributes assigned to an edited area represented
935 * by this delta.
936 */
937 struct YDeltaAttr *attributes;
938 /**
939 * Used in case when current change is of `Y_EVENT_CHANGE_ADD` type. Contains a list (of
940 * length stored in `len` field) of newly inserted values.
941 */
942 struct YOutput *insert;
943} YDeltaOut;
944
945/**
946 * A data type representing a single change detected over an observed shared collection. A type
947 * of change can be detected using a `tag` field:
948 *
949 * 1. `Y_EVENT_CHANGE_ADD` marks a new elements added to a collection. In this case `values` field
950 * contains a pointer to a list of newly inserted values, while `len` field informs about their
951 * count.
952 * 2. `Y_EVENT_CHANGE_DELETE` marks an existing elements removed from the collection. In this case
953 * `len` field informs about number of removed elements.
954 * 3. `Y_EVENT_CHANGE_RETAIN` marks a number of elements that have not been changed, counted from
955 * the previous element. `len` field informs about number of retained elements.
956 *
957 * A list of changes returned by `yarray_event_delta`/`yxml_event_delta` enables to locate a
958 * position of all changes within an observed collection by using a combination of added/deleted
959 * change structs separated by retained changes (marking eg. number of elements that can be safely
960 * skipped, since they remained unchanged).
961 */
962typedef struct YEventChange {
963 /**
964 * Tag field used to identify particular type of change made:
965 *
966 * 1. `Y_EVENT_CHANGE_ADD` marks a new elements added to a collection. In this case `values`
967 * field contains a pointer to a list of newly inserted values, while `len` field informs about
968 * their count.
969 * 2. `Y_EVENT_CHANGE_DELETE` marks an existing elements removed from the collection. In this
970 * case `len` field informs about number of removed elements.
971 * 3. `Y_EVENT_CHANGE_RETAIN` marks a number of elements that have not been changed, counted
972 * from the previous element. `len` field informs about number of retained elements.
973 */
974 uint8_t tag;
975 /**
976 * Number of element affected by current type of a change. It can refer to a number of
977 * inserted `values`, number of deleted element or a number of retained (unchanged) values.
978 */
979 uint32_t len;
980 /**
981 * Used in case when current change is of `Y_EVENT_CHANGE_ADD` type. Contains a list (of
982 * length stored in `len` field) of newly inserted values.
983 */
984 const struct YOutput *values;
985} YEventChange;
986
987/**
988 * A data type representing a single change made over a map component of shared collection types,
989 * such as `YMap` entries or `YXmlText`/`YXmlElement` attributes. A `key` field provides a
990 * corresponding unique key string of a changed entry, while `tag` field informs about specific
991 * type of change being done:
992 *
993 * 1. `Y_EVENT_KEY_CHANGE_ADD` used to identify a newly added entry. In this case an `old_value`
994 * field is NULL, while `new_value` field contains an inserted value.
995 * 1. `Y_EVENT_KEY_CHANGE_DELETE` used to identify an existing entry being removed. In this case
996 * an `old_value` field contains the removed value.
997 * 1. `Y_EVENT_KEY_CHANGE_UPDATE` used to identify an existing entry, which value has been changed.
998 * In this case `old_value` field contains replaced value, while `new_value` contains a newly
999 * inserted one.
1000 */
1001typedef struct YEventKeyChange {
1002 /**
1003 * A UTF8-encoded null-terminated string containing a key of a changed entry.
1004 */
1005 const char *key;
1006 /**
1007 * Tag field informing about type of change current struct refers to:
1008 *
1009 * 1. `Y_EVENT_KEY_CHANGE_ADD` used to identify a newly added entry. In this case an
1010 * `old_value` field is NULL, while `new_value` field contains an inserted value.
1011 * 1. `Y_EVENT_KEY_CHANGE_DELETE` used to identify an existing entry being removed. In this
1012 * case an `old_value` field contains the removed value.
1013 * 1. `Y_EVENT_KEY_CHANGE_UPDATE` used to identify an existing entry, which value has been
1014 * changed. In this case `old_value` field contains replaced value, while `new_value` contains
1015 * a newly inserted one.
1016 */
1017 char tag;
1018 /**
1019 * Contains a removed entry's value or replaced value of an updated entry.
1020 */
1021 const struct YOutput *old_value;
1022 /**
1023 * Contains a value of newly inserted entry or an updated entry's new value.
1024 */
1025 const struct YOutput *new_value;
1026} YEventKeyChange;
1027
1028typedef struct YUndoManagerOptions {
1029 int32_t capture_timeout_millis;
1030} YUndoManagerOptions;
1031
1032/**
1033 * Event type related to `UndoManager` observer operations, such as `yundo_manager_observe_popped`
1034 * and `yundo_manager_observe_added`. It contains various informations about the context in which
1035 * undo/redo operations are executed.
1036 */
1037typedef struct YUndoEvent {
1038 /**
1039 * Informs if current event is related to executed undo (`Y_KIND_UNDO`) or redo (`Y_KIND_REDO`)
1040 * operation.
1041 */
1042 char kind;
1043 /**
1044 * Origin assigned to a transaction, in context of which this event is being executed.
1045 * Transaction origin is specified via `ydoc_write_transaction(doc, origin_len, origin)`.
1046 */
1047 const char *origin;
1048 /**
1049 * Length of an `origin` field assigned to a transaction, in context of which this event is
1050 * being executed.
1051 * Transaction origin is specified via `ydoc_write_transaction(doc, origin_len, origin)`.
1052 */
1053 uint32_t origin_len;
1054 /**
1055 * Pointer to a custom metadata object that can be passed between
1056 * `yundo_manager_observe_popped` and `yundo_manager_observe_added`. It's useful for passing
1057 * around custom user data ie. cursor position, that needs to be remembered and restored as
1058 * part of undo/redo operations.
1059 *
1060 * This field always starts with no value (`NULL`) assigned to it and can be set/unset in
1061 * corresponding callback calls. In such cases it's up to a programmer to handle allocation
1062 * and deallocation of memory that this pointer will point to. Not releasing it properly may
1063 * lead to memory leaks.
1064 */
1065 void *meta;
1066} YUndoEvent;
1067
1068/**
1069 * A sticky index is based on the Yjs model and is not affected by document changes.
1070 * E.g. If you place a sticky index before a certain character, it will always point to this character.
1071 * If you place a sticky index at the end of a type, it will always point to the end of the type.
1072 *
1073 * A numeric position is often unsuited for user selections, because it does not change when content is inserted
1074 * before or after.
1075 *
1076 * ```Insert(0, 'x')('a.bc') = 'xa.bc'``` Where `.` is the sticky index position.
1077 *
1078 * Instances of `YStickyIndex` can be freed using `ysticky_index_destroy`.
1079 */
1080typedef StickyIndex YStickyIndex;
1081
1082typedef union YBranchIdVariant {
1083 /**
1084 * Clock number timestamp when the creator of a nested shared type created it.
1085 */
1086 uint32_t clock;
1087 /**
1088 * Pointer to UTF-8 encoded string representing root-level type name. This pointer is valid
1089 * as long as document - in which scope it was created in - was not destroyed. As usually
1090 * root-level type names are statically allocated strings, it can also be supplied manually
1091 * from the outside.
1092 */
1093 const uint8_t *name;
1094} YBranchIdVariant;
1095
1096/**
1097 * A structure representing logical identifier of a specific shared collection.
1098 * Can be obtained by `ybranch_id` executed over alive `Branch`.
1099 *
1100 * Use `ybranch_get` to resolve a `Branch` pointer from this branch ID.
1101 *
1102 * This structure doesn't need to be destroyed. It's internal pointer reference is valid through
1103 * a lifetime of a document, which collection this branch ID has been created from.
1104 */
1105typedef struct YBranchId {
1106 /**
1107 * If positive: Client ID of a creator of a nested shared type, this identifier points to.
1108 * If negative: a negated Length of a root-level shared collection name.
1109 */
1110 int64_t client_or_len;
1111 union YBranchIdVariant variant;
1112} YBranchId;
1113
1114/**
1115 * Returns default ceonfiguration for `YOptions`.
1116 */
1117struct YOptions yoptions(void);
1118
1119/**
1120 * Releases all memory-allocated resources bound to given document.
1121 */
1122void ydoc_destroy(YDoc *value);
1123
1124/**
1125 * Frees all memory-allocated resources bound to a given [YMapEntry].
1126 */
1127void ymap_entry_destroy(struct YMapEntry *value);
1128
1129/**
1130 * Frees all memory-allocated resources bound to a given [YXmlAttr].
1131 */
1132void yxmlattr_destroy(struct YXmlAttr *attr);
1133
1134/**
1135 * Frees all memory-allocated resources bound to a given UTF-8 null-terminated string returned from
1136 * Yrs document API. Yrs strings don't use libc malloc, so calling `free()` on them will fault.
1137 */
1138void ystring_destroy(char *str);
1139
1140/**
1141 * Frees all memory-allocated resources bound to a given binary returned from Yrs document API.
1142 * Unlike strings binaries are not null-terminated and can contain null characters inside,
1143 * therefore a size of memory to be released must be explicitly provided.
1144 * Yrs binaries don't use libc malloc, so calling `free()` on them will fault.
1145 */
1146void ybinary_destroy(char *ptr, uint32_t len);
1147
1148/**
1149 * Creates a new [Doc] instance with a randomized unique client identifier.
1150 *
1151 * Use [ydoc_destroy] in order to release created [Doc] resources.
1152 */
1153YDoc *ydoc_new(void);
1154
1155/**
1156 * Creates a shallow clone of a provided `doc` - it's realized by increasing the ref-count
1157 * value of the document. In result both input and output documents point to the same instance.
1158 *
1159 * Documents created this way can be destroyed via [ydoc_destroy] - keep in mind, that the memory
1160 * will still be persisted until all strong references are dropped.
1161 */
1162YDoc *ydoc_clone(YDoc *doc);
1163
1164/**
1165 * Creates a new [Doc] instance with a specified `options`.
1166 *
1167 * Use [ydoc_destroy] in order to release created [Doc] resources.
1168 */
1169YDoc *ydoc_new_with_options(struct YOptions options);
1170
1171/**
1172 * Returns a unique client identifier of this [Doc] instance.
1173 */
1174uint64_t ydoc_id(YDoc *doc);
1175
1176/**
1177 * Returns a unique document identifier of this [Doc] instance.
1178 *
1179 * Generated string resources should be released using [ystring_destroy] function.
1180 */
1181char *ydoc_guid(YDoc *doc);
1182
1183/**
1184 * Returns a collection identifier of this [Doc] instance.
1185 * If none was defined, a `NULL` will be returned.
1186 *
1187 * Generated string resources should be released using [ystring_destroy] function.
1188 */
1189char *ydoc_collection_id(YDoc *doc);
1190
1191/**
1192 * Returns status of should_load flag of this [Doc] instance, informing parent [Doc] if this
1193 * document instance requested a data load.
1194 */
1195uint8_t ydoc_should_load(YDoc *doc);
1196
1197/**
1198 * Returns status of auto_load flag of this [Doc] instance. Auto loaded sub-documents automatically
1199 * send a load request to their parent documents.
1200 */
1201uint8_t ydoc_auto_load(YDoc *doc);
1202
1203YSubscription *ydoc_observe_updates_v1(YDoc *doc, void *state, void (*cb)(void*,
1204 uint32_t,
1205 const char*));
1206
1207YSubscription *ydoc_observe_updates_v2(YDoc *doc, void *state, void (*cb)(void*,
1208 uint32_t,
1209 const char*));
1210
1211YSubscription *ydoc_observe_after_transaction(YDoc *doc,
1212 void *state,
1213 void (*cb)(void*, struct YAfterTransactionEvent*));
1214
1215YSubscription *ydoc_observe_subdocs(YDoc *doc,
1216 void *state,
1217 void (*cb)(void*, struct YSubdocsEvent*));
1218
1219YSubscription *ydoc_observe_clear(YDoc *doc, void *state, void (*cb)(void*, YDoc*));
1220
1221/**
1222 * Manually send a load request to a parent document of this subdoc.
1223 */
1224void ydoc_load(YDoc *doc, YTransaction *parent_txn);
1225
1226/**
1227 * Destroys current document, sending a 'destroy' event and clearing up all the event callbacks
1228 * registered.
1229 */
1230void ydoc_clear(YDoc *doc, YTransaction *parent_txn);
1231
1232/**
1233 * Starts a new read-only transaction on a given document. All other operations happen in context
1234 * of a transaction. Yrs transactions do not follow ACID rules. Once a set of operations is
1235 * complete, a transaction can be finished using `ytransaction_commit` function.
1236 *
1237 * Returns `NULL` if read-only transaction couldn't be created, i.e. when another read-write
1238 * transaction is already opened.
1239 */
1240YTransaction *ydoc_read_transaction(YDoc *doc);
1241
1242/**
1243 * Starts a new read-write transaction on a given document. All other operations happen in context
1244 * of a transaction. Yrs transactions do not follow ACID rules. Once a set of operations is
1245 * complete, a transaction can be finished using `ytransaction_commit` function.
1246 *
1247 * `origin_len` and `origin` are optional parameters to specify a byte sequence used to mark
1248 * the origin of this transaction (eg. you may decide to give different origins for transaction
1249 * applying remote updates). These can be used by event handlers or `YUndoManager` to perform
1250 * specific actions. If origin should not be set, call `ydoc_write_transaction(doc, 0, NULL)`.
1251 *
1252 * Returns `NULL` if read-write transaction couldn't be created, i.e. when another transaction is
1253 * already opened.
1254 */
1255YTransaction *ydoc_write_transaction(YDoc *doc, uint32_t origin_len, const char *origin);
1256
1257/**
1258 * Returns a list of subdocs existing within current document.
1259 */
1260YDoc **ytransaction_subdocs(YTransaction *txn, uint32_t *len);
1261
1262/**
1263 * Commit and dispose provided read-write transaction. This operation releases allocated resources,
1264 * triggers update events and performs a storage compression over all operations executed in scope
1265 * of a current transaction.
1266 */
1267void ytransaction_commit(YTransaction *txn);
1268
1269/**
1270 * Perform garbage collection of deleted blocks, even if a document was created with `skip_gc`
1271 * option. This operation will scan over ALL deleted elements, NOT ONLY the ones that have been
1272 * changed as part of this transaction scope.
1273 */
1274void ytransaction_force_gc(YTransaction *txn);
1275
1276/**
1277 * Returns `1` if current transaction is of read-write type.
1278 * Returns `0` if transaction is read-only.
1279 */
1280uint8_t ytransaction_writeable(YTransaction *txn);
1281
1282/**
1283 * Evaluates a JSON path expression (see: https://en.wikipedia.org/wiki/JSONPath) on
1284 * the transaction's document and returns an iterator over values matching that query.
1285 *
1286 * Currently, this method supports the following syntax:
1287 * - `$` - root object
1288 * - `@` - current object
1289 * - `.field` or `['field']` - member accessor
1290 * - `[1]` - array index (also supports negative indices)
1291 * - `.*` or `[*]` - wildcard (matches all members of an object or array)
1292 * - `..` - recursive descent (matches all descendants not only direct children)
1293 * - `[start:end:step]` - array slice operator (requires positive integer arguments)
1294 * - `['a', 'b', 'c']` - union operator (returns an array of values for each query)
1295 * - `[1, -1, 3]` - multiple indices operator (returns an array of values for each index)
1296 *
1297 * At the moment, JSON Path does not support filter predicates.
1298 *
1299 * Returns `NULL` if the json_path expression is invalid and couldn't be parsed.
1300 *
1301 * Use ``yjson_path_iter_next` function in order to retrieve a consecutive array elements.
1302 * Use ``yjson_path_iter_destroy` function in order to close the iterator and release its resources.
1303 */
1304YJsonPathIter *ytransaction_json_path(YTransaction *txn, const char *json_path);
1305
1306/**
1307 * Returns the next element of a JSON path iterator. If there are no more elements, `NULL` is returned.
1308 */
1309struct YOutput *yjson_path_iter_next(YJsonPathIter *iter);
1310
1311/**
1312 * Closes the JSON path iterator created via `ytransaction_json_path` and releases its resources.
1313 */
1314void yjson_path_iter_destroy(YJsonPathIter *iter);
1315
1316/**
1317 * Gets a reference to shared data type instance at the document root-level,
1318 * identified by its `name`, which must be a null-terminated UTF-8 compatible string.
1319 *
1320 * Returns `NULL` if no such structure was defined in the document before.
1321 */
1322Branch *ytype_get(YTransaction *txn, const char *name);
1323
1324/**
1325 * Gets or creates a new shared `YText` data type instance as a root-level type of a given document.
1326 * This structure can later be accessed using its `name`, which must be a null-terminated UTF-8
1327 * compatible string.
1328 */
1329Branch *ytext(YDoc *doc, const char *name);
1330
1331/**
1332 * Gets or creates a new shared `YArray` data type instance as a root-level type of a given document.
1333 * This structure can later be accessed using its `name`, which must be a null-terminated UTF-8
1334 * compatible string.
1335 *
1336 * Once created, a `YArray` instance will last for the entire lifecycle of a document.
1337 */
1338Branch *yarray(YDoc *doc,
1339 const char *name);
1340
1341/**
1342 * Gets or creates a new shared `YMap` data type instance as a root-level type of a given document.
1343 * This structure can later be accessed using its `name`, which must be a null-terminated UTF-8
1344 * compatible string.
1345 *
1346 * Once created, a `YMap` instance will last for the entire lifecycle of a document.
1347 */
1348Branch *ymap(YDoc *doc, const char *name);
1349
1350/**
1351 * Gets or creates a new shared `YXmlElement` data type instance as a root-level type of a given
1352 * document. This structure can later be accessed using its `name`, which must be a null-terminated
1353 * UTF-8 compatible string.
1354 */
1355Branch *yxmlfragment(YDoc *doc, const char *name);
1356
1357/**
1358 * Returns a state vector of a current transaction's document, serialized using lib0 version 1
1359 * encoding. Payload created by this function can then be send over the network to a remote peer,
1360 * where it can be used as a parameter of [ytransaction_state_diff_v1] in order to produce a delta
1361 * update payload, that can be send back and applied locally in order to efficiently propagate
1362 * updates from one peer to another.
1363 *
1364 * The length of a generated binary will be passed within a `len` out parameter.
1365 *
1366 * Once no longer needed, a returned binary can be disposed using [ybinary_destroy] function.
1367 */
1368char *ytransaction_state_vector_v1(const YTransaction *txn, uint32_t *len);
1369
1370/**
1371 * Returns a delta difference between current state of a transaction's document and a state vector
1372 * `sv` encoded as a binary payload using lib0 version 1 encoding (which could be generated using
1373 * [ytransaction_state_vector_v1]). Such delta can be send back to the state vector's sender in
1374 * order to propagate and apply (using [ytransaction_apply]) all updates known to a current
1375 * document, which remote peer was not aware of.
1376 *
1377 * If passed `sv` pointer is null, the generated diff will be a snapshot containing entire state of
1378 * the document.
1379 *
1380 * A length of an encoded state vector payload must be passed as `sv_len` parameter.
1381 *
1382 * A length of generated delta diff binary will be passed within a `len` out parameter.
1383 *
1384 * Once no longer needed, a returned binary can be disposed using [ybinary_destroy] function.
1385 */
1386char *ytransaction_state_diff_v1(const YTransaction *txn,
1387 const char *sv,
1388 uint32_t sv_len,
1389 uint32_t *len);
1390
1391/**
1392 * Returns a delta difference between current state of a transaction's document and a state vector
1393 * `sv` encoded as a binary payload using lib0 version 1 encoding (which could be generated using
1394 * [ytransaction_state_vector_v1]). Such delta can be send back to the state vector's sender in
1395 * order to propagate and apply (using [ytransaction_apply_v2]) all updates known to a current
1396 * document, which remote peer was not aware of.
1397 *
1398 * If passed `sv` pointer is null, the generated diff will be a snapshot containing entire state of
1399 * the document.
1400 *
1401 * A length of an encoded state vector payload must be passed as `sv_len` parameter.
1402 *
1403 * A length of generated delta diff binary will be passed within a `len` out parameter.
1404 *
1405 * Once no longer needed, a returned binary can be disposed using [ybinary_destroy] function.
1406 */
1407char *ytransaction_state_diff_v2(const YTransaction *txn,
1408 const char *sv,
1409 uint32_t sv_len,
1410 uint32_t *len);
1411
1412/**
1413 * Returns a snapshot descriptor of a current state of the document. This snapshot information
1414 * can be then used to encode document data at a particular point in time
1415 * (see: `ytransaction_encode_state_from_snapshot`).
1416 */
1417char *ytransaction_snapshot(const YTransaction *txn, uint32_t *len);
1418
1419/**
1420 * Encodes a state of the document at a point in time specified by the provided `snapshot`
1421 * (generated by: `ytransaction_snapshot`). This is useful to generate a past view of the document.
1422 *
1423 * The returned update is binary compatible with Yrs update lib0 v1 encoding, and can be processed
1424 * with functions dedicated to work on it, like `ytransaction_apply`.
1425 *
1426 * This function requires document with a GC option flag turned off (otherwise "time travel" would
1427 * not be a safe operation). If this is not a case, the NULL pointer will be returned.
1428 */
1429char *ytransaction_encode_state_from_snapshot_v1(const YTransaction *txn,
1430 const char *snapshot,
1431 uint32_t snapshot_len,
1432 uint32_t *len);
1433
1434/**
1435 * Encodes a state of the document at a point in time specified by the provided `snapshot`
1436 * (generated by: `ytransaction_snapshot`). This is useful to generate a past view of the document.
1437 *
1438 * The returned update is binary compatible with Yrs update lib0 v2 encoding, and can be processed
1439 * with functions dedicated to work on it, like `ytransaction_apply_v2`.
1440 *
1441 * This function requires document with a GC option flag turned off (otherwise "time travel" would
1442 * not be a safe operation). If this is not a case, the NULL pointer will be returned.
1443 */
1444char *ytransaction_encode_state_from_snapshot_v2(const YTransaction *txn,
1445 const char *snapshot,
1446 uint32_t snapshot_len,
1447 uint32_t *len);
1448
1449/**
1450 * Returns an unapplied Delete Set for the current document, waiting for missing updates in order
1451 * to be integrated into document store.
1452 *
1453 * Return `NULL` if there's no missing delete set and all deletions have been applied.
1454 * See also: `ytransaction_pending_update`
1455 */
1456struct YIdSet *ytransaction_pending_ds(const YTransaction *txn);
1457
1458void ydelete_set_destroy(struct YIdSet *ds);
1459
1460/**
1461 * Returns a pending update associated with an underlying `YDoc`. Pending update contains update
1462 * data waiting for being integrated into main document store. Usually reason for that is that
1463 * there were missing updates required for integration. In such cases they need to arrive and be
1464 * integrated first.
1465 *
1466 * Returns `NULL` if there is not update pending. Returned value can be released by calling
1467 * `ypending_update_destroy`.
1468 * See also: `ytransaction_pending_ds`
1469 */
1470struct YPendingUpdate *ytransaction_pending_update(const YTransaction *txn);
1471
1472void ypending_update_destroy(struct YPendingUpdate *update);
1473
1474/**
1475 * Returns a null-terminated UTF-8 encoded string representation of an `update` binary payload,
1476 * encoded using lib0 v1 encoding.
1477 * Returns null if update couldn't be parsed into a lib0 v1 formatting.
1478 */
1479char *yupdate_debug_v1(const char *update, uint32_t update_len);
1480
1481/**
1482 * Returns a null-terminated UTF-8 encoded string representation of an `update` binary payload,
1483 * encoded using lib0 v2 encoding.
1484 * Returns null if update couldn't be parsed into a lib0 v2 formatting.
1485 */
1486char *yupdate_debug_v2(const char *update, uint32_t update_len);
1487
1488/**
1489 * Applies an diff update (generated by `ytransaction_state_diff_v1`) to a local transaction's
1490 * document.
1491 *
1492 * A length of generated `diff` binary must be passed within a `diff_len` out parameter.
1493 *
1494 * Returns an error code in case if transaction succeeded failed:
1495 * - **0**: success
1496 * - `ERR_CODE_IO` (**1**): couldn't read data from input stream.
1497 * - `ERR_CODE_VAR_INT` (**2**): decoded variable integer outside of the expected integer size bounds.
1498 * - `ERR_CODE_EOS` (**3**): end of stream found when more data was expected.
1499 * - `ERR_CODE_UNEXPECTED_VALUE` (**4**): decoded enum tag value was not among known cases.
1500 * - `ERR_CODE_INVALID_JSON` (**5**): failure when trying to decode JSON content.
1501 * - `ERR_CODE_OTHER` (**6**): other error type than the one specified.
1502 */
1503uint8_t ytransaction_apply(YTransaction *txn,
1504 const char *diff,
1505 uint32_t diff_len);
1506
1507/**
1508 * Applies an diff update (generated by [ytransaction_state_diff_v2]) to a local transaction's
1509 * document.
1510 *
1511 * A length of generated `diff` binary must be passed within a `diff_len` out parameter.
1512 *
1513 * Returns an error code in case if transaction succeeded failed:
1514 * - **0**: success
1515 * - `ERR_CODE_IO` (**1**): couldn't read data from input stream.
1516 * - `ERR_CODE_VAR_INT` (**2**): decoded variable integer outside of the expected integer size bounds.
1517 * - `ERR_CODE_EOS` (**3**): end of stream found when more data was expected.
1518 * - `ERR_CODE_UNEXPECTED_VALUE` (**4**): decoded enum tag value was not among known cases.
1519 * - `ERR_CODE_INVALID_JSON` (**5**): failure when trying to decode JSON content.
1520 * - `ERR_CODE_OTHER` (**6**): other error type than the one specified.
1521 */
1522uint8_t ytransaction_apply_v2(YTransaction *txn,
1523 const char *diff,
1524 uint32_t diff_len);
1525
1526/**
1527 * Returns the length of the `YText` string content in bytes (without the null terminator character)
1528 */
1529uint32_t ytext_len(const Branch *txt, const YTransaction *txn);
1530
1531/**
1532 * Returns a null-terminated UTF-8 encoded string content of a current `YText` shared data type.
1533 *
1534 * Generated string resources should be released using [ystring_destroy] function.
1535 */
1536char *ytext_string(const Branch *txt, const YTransaction *txn);
1537
1538/**
1539 * Inserts a null-terminated UTF-8 encoded string a given `index`. `index` value must be between
1540 * 0 and a length of a `YText` (inclusive, accordingly to [ytext_len] return value), otherwise this
1541 * function will panic.
1542 *
1543 * A `str` parameter must be a null-terminated UTF-8 encoded string. This function doesn't take
1544 * ownership over a passed value - it will be copied and therefore a string parameter must be
1545 * released by the caller.
1546 *
1547 * A nullable pointer with defined `attrs` will be used to wrap provided text with
1548 * a formatting blocks. `attrs` must be a map-like type.
1549 */
1550void ytext_insert(const Branch *txt,
1551 YTransaction *txn,
1552 uint32_t index,
1553 const char *value,
1554 const struct YInput *attrs);
1555
1556/**
1557 * Wraps an existing piece of text within a range described by `index`-`len` parameters with
1558 * formatting blocks containing provided `attrs` metadata. `attrs` must be a map-like type.
1559 */
1560void ytext_format(const Branch *txt,
1561 YTransaction *txn,
1562 uint32_t index,
1563 uint32_t len,
1564 const struct YInput *attrs);
1565
1566/**
1567 * Inserts an embed content given `index`. `index` value must be between 0 and a length of a
1568 * `YText` (inclusive, accordingly to [ytext_len] return value), otherwise this
1569 * function will panic.
1570 *
1571 * A `str` parameter must be a null-terminated UTF-8 encoded string. This function doesn't take
1572 * ownership over a passed value - it will be copied and therefore a string parameter must be
1573 * released by the caller.
1574 *
1575 * A nullable pointer with defined `attrs` will be used to wrap provided text with
1576 * a formatting blocks. `attrs` must be a map-like type.
1577 */
1578void ytext_insert_embed(const Branch *txt,
1579 YTransaction *txn,
1580 uint32_t index,
1581 const struct YInput *content,
1582 const struct YInput *attrs);
1583
1584/**
1585 * Performs a series of changes over the given `YText` shared ref type, described by the `delta`
1586 * parameter:
1587 *
1588 * - Deltas constructed with `ydelta_input_retain` will move cursor position by the given number
1589 * of elements. If formatting attributes were defined, all elements skipped over this way will be
1590 * wrapped by given formatting attributes.
1591 * - Deltas constructed with `ydelta_input_delete` will tell cursor to remove a corresponding
1592 * number of elements.
1593 * - Deltas constructed with `ydelta_input_insert` will tell cursor to insert given elements into
1594 * current cursor position. While these elements can be of any type (used for embedding ie.
1595 * shared types or binary payload like images), for the text insertion a `yinput_string`
1596 * is expected. If formatting attributes were specified, inserted elements will be wrapped by
1597 * given formatting attributes.
1598 */
1599void ytext_insert_delta(const Branch *txt,
1600 YTransaction *txn,
1601 struct YDeltaIn *delta,
1602 uint32_t delta_len);
1603
1604/**
1605 * Creates a parameter for `ytext_insert_delta` function. This parameter will move cursor position
1606 * by the `len` of elements. If formatting `attrs` were defined, all elements skipped over this
1607 * way will be wrapped by given formatting attributes.
1608 */
1609struct YDeltaIn ydelta_input_retain(uint32_t len, const struct YInput *attrs);
1610
1611/**
1612 * Creates a parameter for `ytext_insert_delta` function. This parameter will tell cursor to remove
1613 * a corresponding number of elements, starting from current cursor position.
1614 */
1615struct YDeltaIn ydelta_input_delete(uint32_t len);
1616
1617/**
1618 * Creates a parameter for `ytext_insert_delta` function. This parameter will tell cursor to insert
1619 * given elements into current cursor position. While these elements can be of any type (used for
1620 * embedding ie. shared types or binary payload like images), for the text insertion a `yinput_string`
1621 * is expected. If formatting attributes were specified, inserted elements will be wrapped by
1622 * given formatting attributes.
1623 */
1624struct YDeltaIn ydelta_input_insert(const struct YInput *data,
1625 const struct YInput *attrs);
1626
1627/**
1628 * Removes a range of characters, starting a a given `index`. This range must fit within the bounds
1629 * of a current `YText`, otherwise this function call will fail.
1630 *
1631 * An `index` value must be between 0 and the length of a `YText` (exclusive, accordingly to
1632 * [ytext_len] return value).
1633 *
1634 * A `length` must be lower or equal number of characters (counted as UTF chars depending on the
1635 * encoding configured by `YDoc`) from `index` position to the end of of the string.
1636 */
1637void ytext_remove_range(const Branch *txt, YTransaction *txn, uint32_t index, uint32_t length);
1638
1639/**
1640 * Returns a number of elements stored within current instance of `YArray`.
1641 */
1642uint32_t yarray_len(const Branch *array);
1643
1644/**
1645 * Returns a pointer to a `YOutput` value stored at a given `index` of a current `YArray`.
1646 * If `index` is outside the bounds of an array, a null pointer will be returned.
1647 *
1648 * A value returned should be eventually released using [youtput_destroy] function.
1649 */
1650struct YOutput *yarray_get(const Branch *array, const YTransaction *txn, uint32_t index);
1651
1652/**
1653 * Returns a UTF-8 encoded, NULL-terminated JSON string representing a value stored in a current
1654 * YArray under a given index.
1655 *
1656 * This method will return `NULL` pointer if value was outside the bound of an array or couldn't be
1657 * serialized into JSON string.
1658 *
1659 * This method will also try to serialize complex types that don't have native JSON representation
1660 * like YMap, YArray, YText etc. in such cases their contents will be materialized into JSON values.
1661 *
1662 * A string returned should be eventually released using [ystring_destroy] function.
1663 */
1664char *yarray_get_json(const Branch *array, const YTransaction *txn, uint32_t index);
1665
1666/**
1667 * Inserts a range of `items` into current `YArray`, starting at given `index`. An `items_len`
1668 * parameter is used to determine the size of `items` array - it can also be used to insert
1669 * a single element given its pointer.
1670 *
1671 * An `index` value must be between 0 and (inclusive) length of a current array (use [yarray_len]
1672 * to determine its length), otherwise it will panic at runtime.
1673 *
1674 * `YArray` doesn't take ownership over the inserted `items` data - their contents are being copied
1675 * into array structure - therefore caller is responsible for freeing all memory associated with
1676 * input params.
1677 */
1678void yarray_insert_range(const Branch *array,
1679 YTransaction *txn,
1680 uint32_t index,
1681 const struct YInput *items,
1682 uint32_t items_len);
1683
1684/**
1685 * Removes a `len` of consecutive range of elements from current `array` instance, starting at
1686 * a given `index`. Range determined by `index` and `len` must fit into boundaries of an array,
1687 * otherwise it will panic at runtime.
1688 */
1689void yarray_remove_range(const Branch *array, YTransaction *txn, uint32_t index, uint32_t len);
1690
1691/**
1692 * Returns an iterator, which can be used to traverse over all elements of an `array` (`array`'s
1693 * length can be determined using [yarray_len] function).
1694 *
1695 * Use [yarray_iter_next] function in order to retrieve a consecutive array elements.
1696 * Use [yarray_iter_destroy] function in order to close the iterator and release its resources.
1697 */
1698YArrayIter *yarray_iter(const Branch *array, YTransaction *txn);
1699
1700/**
1701 * Releases all of an `YArray` iterator resources created by calling [yarray_iter].
1702 */
1703void yarray_iter_destroy(YArrayIter *iter);
1704
1705/**
1706 * Moves current `YArray` iterator over to a next element, returning a pointer to it. If an iterator
1707 * comes to an end of an array, a null pointer will be returned.
1708 *
1709 * Returned values should be eventually released using [youtput_destroy] function.
1710 */
1711struct YOutput *yarray_iter_next(YArrayIter *iterator);
1712
1713/**
1714 * Returns an iterator, which can be used to traverse over all key-value pairs of a `map`.
1715 *
1716 * Use [ymap_iter_next] function in order to retrieve a consecutive (**unordered**) map entries.
1717 * Use [ymap_iter_destroy] function in order to close the iterator and release its resources.
1718 */
1719YMapIter *ymap_iter(const Branch *map, const YTransaction *txn);
1720
1721/**
1722 * Releases all of an `YMap` iterator resources created by calling [ymap_iter].
1723 */
1724void ymap_iter_destroy(YMapIter *iter);
1725
1726/**
1727 * Moves current `YMap` iterator over to a next entry, returning a pointer to it. If an iterator
1728 * comes to an end of a map, a null pointer will be returned. Yrs maps are unordered and so are
1729 * their iterators.
1730 *
1731 * Returned values should be eventually released using [ymap_entry_destroy] function.
1732 */
1733struct YMapEntry *ymap_iter_next(YMapIter *iter);
1734
1735/**
1736 * Returns a number of entries stored within a `map`.
1737 */
1738uint32_t ymap_len(const Branch *map, const YTransaction *txn);
1739
1740/**
1741 * Inserts a new entry (specified as `key`-`value` pair) into a current `map`. If entry under such
1742 * given `key` already existed, its corresponding value will be replaced.
1743 *
1744 * A `key` must be a null-terminated UTF-8 encoded string, which contents will be copied into
1745 * a `map` (therefore it must be freed by the function caller).
1746 *
1747 * A `value` content is being copied into a `map`, therefore any of its content must be freed by
1748 * the function caller.
1749 */
1750void ymap_insert(const Branch *map, YTransaction *txn, const char *key, const struct YInput *value);
1751
1752/**
1753 * Removes a `map` entry, given its `key`. Returns `1` if the corresponding entry was successfully
1754 * removed or `0` if no entry with a provided `key` has been found inside of a `map`.
1755 *
1756 * A `key` must be a null-terminated UTF-8 encoded string.
1757 */
1758uint8_t ymap_remove(const Branch *map, YTransaction *txn, const char *key);
1759
1760/**
1761 * Returns a value stored under the provided `key`, or a null pointer if no entry with such `key`
1762 * has been found in a current `map`. A returned value is allocated by this function and therefore
1763 * should be eventually released using [youtput_destroy] function.
1764 *
1765 * A `key` must be a null-terminated UTF-8 encoded string.
1766 */
1767struct YOutput *ymap_get(const Branch *map, const YTransaction *txn, const char *key);
1768
1769/**
1770 * Returns a value stored under the provided `key` as UTF-8 encoded, NULL-terminated JSON string.
1771 * Once not needed that string should be deallocated using `ystring_destroy`.
1772 *
1773 * This method will return `NULL` pointer if value was not found or value couldn't be serialized
1774 * into JSON string.
1775 *
1776 * This method will also try to serialize complex types that don't have native JSON representation
1777 * like YMap, YArray, YText etc. in such cases their contents will be materialized into JSON values.
1778 */
1779char *ymap_get_json(const Branch *map, const YTransaction *txn, const char *key);
1780
1781/**
1782 * Removes all entries from a current `map`.
1783 */
1784void ymap_remove_all(const Branch *map, YTransaction *txn);
1785
1786/**
1787 * Return a name (or an XML tag) of a current `YXmlElement`. Root-level XML nodes use "UNDEFINED" as
1788 * their tag names.
1789 *
1790 * Returned value is a null-terminated UTF-8 string, which must be released using [ystring_destroy]
1791 * function.
1792 */
1793char *yxmlelem_tag(const Branch *xml);
1794
1795/**
1796 * Converts current `YXmlElement` together with its children and attributes into a flat string
1797 * representation (no padding) eg. `<UNDEFINED><title key="value">sample text</title></UNDEFINED>`.
1798 *
1799 * Returned value is a null-terminated UTF-8 string, which must be released using [ystring_destroy]
1800 * function.
1801 */
1802char *yxmlelem_string(const Branch *xml, const YTransaction *txn);
1803
1804/**
1805 * Inserts an XML attribute described using `attr_name` and `attr_value`. If another attribute with
1806 * the same name already existed, its value will be replaced with a provided one.
1807 *
1808 * Both `attr_name` and `attr_value` must be a null-terminated UTF-8 encoded strings. Their
1809 * contents are being copied, therefore it's up to a function caller to properly release them.
1810 */
1811void yxmlelem_insert_attr(const Branch *xml,
1812 YTransaction *txn,
1813 const char *attr_name,
1814 const struct YInput *attr_value);
1815
1816/**
1817 * Removes an attribute from a current `YXmlElement`, given its name.
1818 *
1819 * An `attr_name`must be a null-terminated UTF-8 encoded string.
1820 */
1821void yxmlelem_remove_attr(const Branch *xml, YTransaction *txn, const char *attr_name);
1822
1823/**
1824 * Returns the value of a current `YXmlElement`, given its name, or a null pointer if not attribute
1825 * with such name has been found. Returned pointer is a null-terminated UTF-8 encoded string, which
1826 * should be released using [ystring_destroy] function.
1827 *
1828 * An `attr_name` must be a null-terminated UTF-8 encoded string.
1829 */
1830struct YOutput *yxmlelem_get_attr(const Branch *xml,
1831 const YTransaction *txn,
1832 const char *attr_name);
1833
1834/**
1835 * Returns an iterator over the `YXmlElement` attributes.
1836 *
1837 * Use [yxmlattr_iter_next] function in order to retrieve a consecutive (**unordered**) attributes.
1838 * Use [yxmlattr_iter_destroy] function in order to close the iterator and release its resources.
1839 */
1840YXmlAttrIter *yxmlelem_attr_iter(const Branch *xml, const YTransaction *txn);
1841
1842/**
1843 * Returns an iterator over the `YXmlText` attributes.
1844 *
1845 * Use [yxmlattr_iter_next] function in order to retrieve a consecutive (**unordered**) attributes.
1846 * Use [yxmlattr_iter_destroy] function in order to close the iterator and release its resources.
1847 */
1848YXmlAttrIter *yxmltext_attr_iter(const Branch *xml, const YTransaction *txn);
1849
1850/**
1851 * Releases all of attributes iterator resources created by calling [yxmlelem_attr_iter]
1852 * or [yxmltext_attr_iter].
1853 */
1854void yxmlattr_iter_destroy(YXmlAttrIter *iterator);
1855
1856/**
1857 * Returns a next XML attribute from an `iterator`. Attributes are returned in an unordered
1858 * manner. Once `iterator` reaches the end of attributes collection, a null pointer will be
1859 * returned.
1860 *
1861 * Returned value should be eventually released using [yxmlattr_destroy].
1862 */
1863struct YXmlAttr *yxmlattr_iter_next(YXmlAttrIter *iterator);
1864
1865/**
1866 * Returns a next sibling of a current XML node, which can be either another `YXmlElement`
1867 * or a `YXmlText`. Together with [yxmlelem_first_child] it may be used to iterate over the direct
1868 * children of an XML node (in order to iterate over the nested XML structure use
1869 * [yxmlelem_tree_walker]).
1870 *
1871 * If current `YXmlElement` is the last child, this function returns a null pointer.
1872 * A returned value should be eventually released using [youtput_destroy] function.
1873 */
1874struct YOutput *yxml_next_sibling(const Branch *xml, const YTransaction *txn);
1875
1876/**
1877 * Returns a previous sibling of a current XML node, which can be either another `YXmlElement`
1878 * or a `YXmlText`.
1879 *
1880 * If current `YXmlElement` is the first child, this function returns a null pointer.
1881 * A returned value should be eventually released using [youtput_destroy] function.
1882 */
1883struct YOutput *yxml_prev_sibling(const Branch *xml, const YTransaction *txn);
1884
1885/**
1886 * Returns a parent `YXmlElement` of a current node, or null pointer when current `YXmlElement` is
1887 * a root-level shared data type.
1888 */
1889Branch *yxmlelem_parent(const Branch *xml);
1890
1891/**
1892 * Returns a number of child nodes (both `YXmlElement` and `YXmlText`) living under a current XML
1893 * element. This function doesn't count a recursive nodes, only direct children of a current node.
1894 */
1895uint32_t yxmlelem_child_len(const Branch *xml, const YTransaction *txn);
1896
1897/**
1898 * Returns a first child node of a current `YXmlElement`, or null pointer if current XML node is
1899 * empty. Returned value could be either another `YXmlElement` or `YXmlText`.
1900 *
1901 * A returned value should be eventually released using [youtput_destroy] function.
1902 */
1903struct YOutput *yxmlelem_first_child(const Branch *xml);
1904
1905/**
1906 * Returns an iterator over a nested recursive structure of a current `YXmlElement`, starting from
1907 * first of its children. Returned values can be either `YXmlElement` or `YXmlText` nodes.
1908 *
1909 * Use [yxmlelem_tree_walker_next] function in order to iterate over to a next node.
1910 * Use [yxmlelem_tree_walker_destroy] function to release resources used by the iterator.
1911 */
1912YXmlTreeWalker *yxmlelem_tree_walker(const Branch *xml, const YTransaction *txn);
1913
1914/**
1915 * Releases resources associated with a current XML tree walker iterator.
1916 */
1917void yxmlelem_tree_walker_destroy(YXmlTreeWalker *iter);
1918
1919/**
1920 * Moves current `iterator` to a next value (either `YXmlElement` or `YXmlText`), returning its
1921 * pointer or a null, if an `iterator` already reached the last successor node.
1922 *
1923 * Values returned by this function should be eventually released using [youtput_destroy].
1924 */
1925struct YOutput *yxmlelem_tree_walker_next(YXmlTreeWalker *iterator);
1926
1927/**
1928 * Inserts an `YXmlElement` as a child of a current node at the given `index` and returns its
1929 * pointer. Node created this way will have a given `name` as its tag (eg. `p` for `<p></p>` node).
1930 *
1931 * An `index` value must be between 0 and (inclusive) length of a current XML element (use
1932 * [yxmlelem_child_len] function to determine its length).
1933 *
1934 * A `name` must be a null-terminated UTF-8 encoded string, which will be copied into current
1935 * document. Therefore `name` should be freed by the function caller.
1936 */
1937Branch *yxmlelem_insert_elem(const Branch *xml,
1938 YTransaction *txn,
1939 uint32_t index,
1940 const char *name);
1941
1942/**
1943 * Inserts an `YXmlText` as a child of a current node at the given `index` and returns its
1944 * pointer.
1945 *
1946 * An `index` value must be between 0 and (inclusive) length of a current XML element (use
1947 * [yxmlelem_child_len] function to determine its length).
1948 */
1949Branch *yxmlelem_insert_text(const Branch *xml, YTransaction *txn, uint32_t index);
1950
1951/**
1952 * Removes a consecutive range of child elements (of specified length) from the current
1953 * `YXmlElement`, starting at the given `index`. Specified range must fit into boundaries of current
1954 * XML node children, otherwise this function will panic at runtime.
1955 */
1956void yxmlelem_remove_range(const Branch *xml, YTransaction *txn, uint32_t index, uint32_t len);
1957
1958/**
1959 * Returns an XML child node (either a `YXmlElement` or `YXmlText`) stored at a given `index` of
1960 * a current `YXmlElement`. Returns null pointer if `index` was outside of the bound of current XML
1961 * node children.
1962 *
1963 * Returned value should be eventually released using [youtput_destroy].
1964 */
1965const struct YOutput *yxmlelem_get(const Branch *xml, const YTransaction *txn, uint32_t index);
1966
1967/**
1968 * Returns the length of the `YXmlText` string content in bytes (without the null terminator
1969 * character)
1970 */
1971uint32_t yxmltext_len(const Branch *txt, const YTransaction *txn);
1972
1973/**
1974 * Returns a null-terminated UTF-8 encoded string content of a current `YXmlText` shared data type.
1975 *
1976 * Generated string resources should be released using [ystring_destroy] function.
1977 */
1978char *yxmltext_string(const Branch *txt, const YTransaction *txn);
1979
1980/**
1981 * Inserts a null-terminated UTF-8 encoded string a a given `index`. `index` value must be between
1982 * 0 and a length of a `YXmlText` (inclusive, accordingly to [yxmltext_len] return value), otherwise
1983 * this function will panic.
1984 *
1985 * A `str` parameter must be a null-terminated UTF-8 encoded string. This function doesn't take
1986 * ownership over a passed value - it will be copied and therefore a string parameter must be
1987 * released by the caller.
1988 *
1989 * A nullable pointer with defined `attrs` will be used to wrap provided text with
1990 * a formatting blocks. `attrs` must be a map-like type.
1991 */
1992void yxmltext_insert(const Branch *txt,
1993 YTransaction *txn,
1994 uint32_t index,
1995 const char *str,
1996 const struct YInput *attrs);
1997
1998/**
1999 * Inserts an embed content given `index`. `index` value must be between 0 and a length of a
2000 * `YXmlText` (inclusive, accordingly to [ytext_len] return value), otherwise this
2001 * function will panic.
2002 *
2003 * A `str` parameter must be a null-terminated UTF-8 encoded string. This function doesn't take
2004 * ownership over a passed value - it will be copied and therefore a string parameter must be
2005 * released by the caller.
2006 *
2007 * A nullable pointer with defined `attrs` will be used to wrap provided text with
2008 * a formatting blocks. `attrs` must be a map-like type.
2009 */
2010void yxmltext_insert_embed(const Branch *txt,
2011 YTransaction *txn,
2012 uint32_t index,
2013 const struct YInput *content,
2014 const struct YInput *attrs);
2015
2016/**
2017 * Wraps an existing piece of text within a range described by `index`-`len` parameters with
2018 * formatting blocks containing provided `attrs` metadata. `attrs` must be a map-like type.
2019 */
2020void yxmltext_format(const Branch *txt,
2021 YTransaction *txn,
2022 uint32_t index,
2023 uint32_t len,
2024 const struct YInput *attrs);
2025
2026/**
2027 * Removes a range of characters, starting a a given `index`. This range must fit within the bounds
2028 * of a current `YXmlText`, otherwise this function call will fail.
2029 *
2030 * An `index` value must be between 0 and the length of a `YXmlText` (exclusive, accordingly to
2031 * [yxmltext_len] return value).
2032 *
2033 * A `length` must be lower or equal number of characters (counted as UTF chars depending on the
2034 * encoding configured by `YDoc`) from `index` position to the end of of the string.
2035 */
2036void yxmltext_remove_range(const Branch *txt, YTransaction *txn, uint32_t idx, uint32_t len);
2037
2038/**
2039 * Inserts an XML attribute described using `attr_name` and `attr_value`. If another attribute with
2040 * the same name already existed, its value will be replaced with a provided one.
2041 *
2042 * Both `attr_name` and `attr_value` must be a null-terminated UTF-8 encoded strings. Their
2043 * contents are being copied, therefore it's up to a function caller to properly release them.
2044 */
2045void yxmltext_insert_attr(const Branch *txt,
2046 YTransaction *txn,
2047 const char *attr_name,
2048 const struct YInput *attr_value);
2049
2050/**
2051 * Removes an attribute from a current `YXmlText`, given its name.
2052 *
2053 * An `attr_name`must be a null-terminated UTF-8 encoded string.
2054 */
2055void yxmltext_remove_attr(const Branch *txt, YTransaction *txn, const char *attr_name);
2056
2057/**
2058 * Returns the value of a current `YXmlText`, given its name, or a null pointer if not attribute
2059 * with such name has been found. Returned pointer is a null-terminated UTF-8 encoded string, which
2060 * should be released using [ystring_destroy] function.
2061 *
2062 * An `attr_name` must be a null-terminated UTF-8 encoded string.
2063 */
2064struct YOutput *yxmltext_get_attr(const Branch *txt,
2065 const YTransaction *txn,
2066 const char *attr_name);
2067
2068/**
2069 * Returns a collection of chunks representing pieces of `YText` rich text string grouped together
2070 * by the same formatting rules and type. `chunks_len` is used to inform about a number of chunks
2071 * generated this way.
2072 *
2073 * Returned array needs to be eventually deallocated using `ychunks_destroy`.
2074 */
2075struct YChunk *ytext_chunks(const Branch *txt, const YTransaction *txn, uint32_t *chunks_len);
2076
2077/**
2078 * Deallocates result of `ytext_chunks` method.
2079 */
2080void ychunks_destroy(struct YChunk *chunks, uint32_t len);
2081
2082/**
2083 * Releases all resources related to a corresponding `YOutput` cell.
2084 */
2085void youtput_destroy(struct YOutput *val);
2086
2087/**
2088 * Function constructor used to create JSON-like NULL `YInput` cell.
2089 * This function doesn't allocate any heap resources.
2090 */
2091struct YInput yinput_null(void);
2092
2093/**
2094 * Function constructor used to create JSON-like undefined `YInput` cell.
2095 * This function doesn't allocate any heap resources.
2096 */
2097struct YInput yinput_undefined(void);
2098
2099/**
2100 * Function constructor used to create JSON-like boolean `YInput` cell.
2101 * This function doesn't allocate any heap resources.
2102 */
2103struct YInput yinput_bool(uint8_t flag);
2104
2105/**
2106 * Function constructor used to create JSON-like 64-bit floating point number `YInput` cell.
2107 * This function doesn't allocate any heap resources.
2108 */
2109struct YInput yinput_float(double num);
2110
2111/**
2112 * Function constructor used to create JSON-like 64-bit signed integer `YInput` cell.
2113 * This function doesn't allocate any heap resources.
2114 */
2115struct YInput yinput_long(int64_t integer);
2116
2117/**
2118 * Function constructor used to create a string `YInput` cell. Provided parameter must be
2119 * a null-terminated UTF-8 encoded string. This function doesn't allocate any heap resources,
2120 * and doesn't release any on its own, therefore its up to a caller to free resources once
2121 * a structure is no longer needed.
2122 */
2123struct YInput yinput_string(const char *str);
2124
2125/**
2126 * Function constructor used to create aa `YInput` cell representing any JSON-like object.
2127 * Provided parameter must be a null-terminated UTF-8 encoded JSON string.
2128 *
2129 * This function doesn't allocate any heap resources and doesn't release any on its own, therefore
2130 * its up to a caller to free resources once a structure is no longer needed.
2131 */
2132struct YInput yinput_json(const char *str);
2133
2134/**
2135 * Function constructor used to create a binary `YInput` cell of a specified length.
2136 * This function doesn't allocate any heap resources and doesn't release any on its own, therefore
2137 * its up to a caller to free resources once a structure is no longer needed.
2138 */
2139struct YInput yinput_binary(const char *buf, uint32_t len);
2140
2141/**
2142 * Function constructor used to create a JSON-like array `YInput` cell of other JSON-like values of
2143 * a given length. This function doesn't allocate any heap resources and doesn't release any on its
2144 * own, therefore its up to a caller to free resources once a structure is no longer needed.
2145 */
2146struct YInput yinput_json_array(struct YInput *values, uint32_t len);
2147
2148/**
2149 * Function constructor used to create a JSON-like map `YInput` cell of other JSON-like key-value
2150 * pairs. These pairs are build from corresponding indexes of `keys` and `values`, which must have
2151 * the same specified length.
2152 *
2153 * This function doesn't allocate any heap resources and doesn't release any on its own, therefore
2154 * its up to a caller to free resources once a structure is no longer needed.
2155 */
2156struct YInput yinput_json_map(char **keys, struct YInput *values, uint32_t len);
2157
2158/**
2159 * Function constructor used to create a nested `YArray` `YInput` cell prefilled with other
2160 * values of a given length. This function doesn't allocate any heap resources and doesn't release
2161 * any on its own, therefore its up to a caller to free resources once a structure is no longer
2162 * needed.
2163 */
2164struct YInput yinput_yarray(struct YInput *values, uint32_t len);
2165
2166/**
2167 * Function constructor used to create a nested `YMap` `YInput` cell prefilled with other key-value
2168 * pairs. These pairs are build from corresponding indexes of `keys` and `values`, which must have
2169 * the same specified length.
2170 *
2171 * This function doesn't allocate any heap resources and doesn't release any on its own, therefore
2172 * its up to a caller to free resources once a structure is no longer needed.
2173 */
2174struct YInput yinput_ymap(char **keys, struct YInput *values, uint32_t len);
2175
2176/**
2177 * Function constructor used to create a nested `YText` `YInput` cell prefilled with a specified
2178 * string, which must be a null-terminated UTF-8 character pointer.
2179 *
2180 * This function doesn't allocate any heap resources and doesn't release any on its own, therefore
2181 * its up to a caller to free resources once a structure is no longer needed.
2182 */
2183struct YInput yinput_ytext(char *str);
2184
2185/**
2186 * Function constructor used to create a nested `YXmlElement` `YInput` cell with a specified
2187 * tag name, which must be a null-terminated UTF-8 character pointer.
2188 *
2189 * This function doesn't allocate any heap resources and doesn't release any on its own, therefore
2190 * its up to a caller to free resources once a structure is no longer needed.
2191 */
2192struct YInput yinput_yxmlelem(char *name);
2193
2194/**
2195 * Function constructor used to create a nested `YXmlText` `YInput` cell prefilled with a specified
2196 * string, which must be a null-terminated UTF-8 character pointer.
2197 *
2198 * This function doesn't allocate any heap resources and doesn't release any on its own, therefore
2199 * its up to a caller to free resources once a structure is no longer needed.
2200 */
2201struct YInput yinput_yxmltext(char *str);
2202
2203/**
2204 * Function constructor used to create a nested `YDoc` `YInput` cell.
2205 *
2206 * This function doesn't allocate any heap resources and doesn't release any on its own, therefore
2207 * its up to a caller to free resources once a structure is no longer needed.
2208 */
2209struct YInput yinput_ydoc(YDoc *doc);
2210
2211/**
2212 * Function constructor used to create a string `YInput` cell with weak reference to another
2213 * element(s) living inside of the same document.
2214 */
2215struct YInput yinput_weak(const Weak *weak);
2216
2217/**
2218 * Attempts to read the value for a given `YOutput` pointer as a `YDocRef` reference to a nested
2219 * document.
2220 */
2221YDoc *youtput_read_ydoc(const struct YOutput *val);
2222
2223/**
2224 * Attempts to read the value for a given `YOutput` pointer as a boolean flag, which can be either
2225 * `1` for truthy case and `0` otherwise. Returns a null pointer in case when a value stored under
2226 * current `YOutput` cell is not of a boolean type.
2227 */
2228const uint8_t *youtput_read_bool(const struct YOutput *val);
2229
2230/**
2231 * Attempts to read the value for a given `YOutput` pointer as a 64-bit floating point number.
2232 *
2233 * Returns a null pointer in case when a value stored under current `YOutput` cell
2234 * is not a floating point number.
2235 */
2236const double *youtput_read_float(const struct YOutput *val);
2237
2238/**
2239 * Attempts to read the value for a given `YOutput` pointer as a 64-bit signed integer.
2240 *
2241 * Returns a null pointer in case when a value stored under current `YOutput` cell
2242 * is not a signed integer.
2243 */
2244const int64_t *youtput_read_long(const struct YOutput *val);
2245
2246/**
2247 * Attempts to read the value for a given `YOutput` pointer as a null-terminated UTF-8 encoded
2248 * string.
2249 *
2250 * Returns a null pointer in case when a value stored under current `YOutput` cell
2251 * is not a string. Underlying string is released automatically as part of [youtput_destroy]
2252 * destructor.
2253 */
2254char *youtput_read_string(const struct YOutput *val);
2255
2256/**
2257 * Attempts to read the value for a given `YOutput` pointer as a binary payload (which length is
2258 * stored within `len` filed of a cell itself).
2259 *
2260 * Returns a null pointer in case when a value stored under current `YOutput` cell
2261 * is not a binary type. Underlying binary is released automatically as part of [youtput_destroy]
2262 * destructor.
2263 */
2264const char *youtput_read_binary(const struct YOutput *val);
2265
2266/**
2267 * Attempts to read the value for a given `YOutput` pointer as a JSON-like array of `YOutput`
2268 * values (which length is stored within `len` filed of a cell itself).
2269 *
2270 * Returns a null pointer in case when a value stored under current `YOutput` cell
2271 * is not a JSON-like array. Underlying heap resources are released automatically as part of
2272 * [youtput_destroy] destructor.
2273 */
2274struct YOutput *youtput_read_json_array(const struct YOutput *val);
2275
2276/**
2277 * Attempts to read the value for a given `YOutput` pointer as a JSON-like map of key-value entries
2278 * (which length is stored within `len` filed of a cell itself).
2279 *
2280 * Returns a null pointer in case when a value stored under current `YOutput` cell
2281 * is not a JSON-like map. Underlying heap resources are released automatically as part of
2282 * [youtput_destroy] destructor.
2283 */
2284struct YMapEntry *youtput_read_json_map(const struct YOutput *val);
2285
2286/**
2287 * Attempts to read the value for a given `YOutput` pointer as an `YArray`.
2288 *
2289 * Returns a null pointer in case when a value stored under current `YOutput` cell
2290 * is not an `YArray`. Underlying heap resources are released automatically as part of
2291 * [youtput_destroy] destructor.
2292 */
2293Branch *youtput_read_yarray(const struct YOutput *val);
2294
2295/**
2296 * Attempts to read the value for a given `YOutput` pointer as an `YXmlElement`.
2297 *
2298 * Returns a null pointer in case when a value stored under current `YOutput` cell
2299 * is not an `YXmlElement`. Underlying heap resources are released automatically as part of
2300 * [youtput_destroy] destructor.
2301 */
2302Branch *youtput_read_yxmlelem(const struct YOutput *val);
2303
2304/**
2305 * Attempts to read the value for a given `YOutput` pointer as an `YMap`.
2306 *
2307 * Returns a null pointer in case when a value stored under current `YOutput` cell
2308 * is not an `YMap`. Underlying heap resources are released automatically as part of
2309 * [youtput_destroy] destructor.
2310 */
2311Branch *youtput_read_ymap(const struct YOutput *val);
2312
2313/**
2314 * Attempts to read the value for a given `YOutput` pointer as an `YText`.
2315 *
2316 * Returns a null pointer in case when a value stored under current `YOutput` cell
2317 * is not an `YText`. Underlying heap resources are released automatically as part of
2318 * [youtput_destroy] destructor.
2319 */
2320Branch *youtput_read_ytext(const struct YOutput *val);
2321
2322/**
2323 * Attempts to read the value for a given `YOutput` pointer as an `YXmlText`.
2324 *
2325 * Returns a null pointer in case when a value stored under current `YOutput` cell
2326 * is not an `YXmlText`. Underlying heap resources are released automatically as part of
2327 * [youtput_destroy] destructor.
2328 */
2329Branch *youtput_read_yxmltext(const struct YOutput *val);
2330
2331/**
2332 * Attempts to read the value for a given `YOutput` pointer as an `YWeakRef`.
2333 *
2334 * Returns a null pointer in case when a value stored under current `YOutput` cell
2335 * is not an `YWeakRef`. Underlying heap resources are released automatically as part of
2336 * [youtput_destroy] destructor.
2337 */
2338Branch *youtput_read_yweak(const struct YOutput *val);
2339
2340/**
2341 * Unsubscribe callback from the oberver event it was previously subscribed to.
2342 */
2343void yunobserve(YSubscription *subscription);
2344
2345/**
2346 * Subscribes a given callback function `cb` to changes made by this `YText` instance. Callbacks
2347 * are triggered whenever a `ytransaction_commit` is called.
2348 * Returns a subscription ID which can be then used to unsubscribe this callback by using
2349 * `yunobserve` function.
2350 */
2351YSubscription *ytext_observe(const Branch *txt, void *state, void (*cb)(void*,
2352 const struct YTextEvent*));
2353
2354/**
2355 * Subscribes a given callback function `cb` to changes made by this `YMap` instance. Callbacks
2356 * are triggered whenever a `ytransaction_commit` is called.
2357 * Returns a subscription ID which can be then used to unsubscribe this callback by using
2358 * `yunobserve` function.
2359 */
2360YSubscription *ymap_observe(const Branch *map, void *state, void (*cb)(void*,
2361 const struct YMapEvent*));
2362
2363/**
2364 * Subscribes a given callback function `cb` to changes made by this `YArray` instance. Callbacks
2365 * are triggered whenever a `ytransaction_commit` is called.
2366 * Returns a subscription ID which can be then used to unsubscribe this callback by using
2367 * `yunobserve` function.
2368 */
2369YSubscription *yarray_observe(const Branch *array,
2370 void *state,
2371 void (*cb)(void*, const struct YArrayEvent*));
2372
2373/**
2374 * Subscribes a given callback function `cb` to changes made by this `YXmlElement` instance.
2375 * Callbacks are triggered whenever a `ytransaction_commit` is called.
2376 * Returns a subscription ID which can be then used to unsubscribe this callback by using
2377 * `yunobserve` function.
2378 */
2379YSubscription *yxmlelem_observe(const Branch *xml,
2380 void *state,
2381 void (*cb)(void*, const struct YXmlEvent*));
2382
2383/**
2384 * Subscribes a given callback function `cb` to changes made by this `YXmlText` instance. Callbacks
2385 * are triggered whenever a `ytransaction_commit` is called.
2386 * Returns a subscription ID which can be then used to unsubscribe this callback by using
2387 * `yunobserve` function.
2388 */
2389YSubscription *yxmltext_observe(const Branch *xml,
2390 void *state,
2391 void (*cb)(void*, const struct YXmlTextEvent*));
2392
2393/**
2394 * Subscribes a given callback function `cb` to changes made by this shared type instance as well
2395 * as all nested shared types living within it. Callbacks are triggered whenever a
2396 * `ytransaction_commit` is called.
2397 *
2398 * Returns a subscription ID which can be then used to unsubscribe this callback by using
2399 * `yunobserve` function.
2400 */
2401YSubscription *yobserve_deep(Branch *ytype, void *state, void (*cb)(void*,
2402 uint32_t,
2403 const struct YEvent*));
2404
2405/**
2406 * Returns a pointer to a shared collection, which triggered passed event `e`.
2407 */
2408Branch *ytext_event_target(const struct YTextEvent *e);
2409
2410/**
2411 * Returns a pointer to a shared collection, which triggered passed event `e`.
2412 */
2413Branch *yarray_event_target(const struct YArrayEvent *e);
2414
2415/**
2416 * Returns a pointer to a shared collection, which triggered passed event `e`.
2417 */
2418Branch *ymap_event_target(const struct YMapEvent *e);
2419
2420/**
2421 * Returns a pointer to a shared collection, which triggered passed event `e`.
2422 */
2423Branch *yxmlelem_event_target(const struct YXmlEvent *e);
2424
2425/**
2426 * Returns a pointer to a shared collection, which triggered passed event `e`.
2427 */
2428Branch *yxmltext_event_target(const struct YXmlTextEvent *e);
2429
2430/**
2431 * Returns a path from a root type down to a current shared collection (which can be obtained using
2432 * `ytext_event_target` function). It can consist of either integer indexes (used by sequence
2433 * components) or *char keys (used by map components). `len` output parameter is used to provide
2434 * information about length of the path.
2435 *
2436 * Path returned this way should be eventually released using `ypath_destroy`.
2437 */
2438struct YPathSegment *ytext_event_path(const struct YTextEvent *e, uint32_t *len);
2439
2440/**
2441 * Returns a path from a root type down to a current shared collection (which can be obtained using
2442 * `ymap_event_target` function). It can consist of either integer indexes (used by sequence
2443 * components) or *char keys (used by map components). `len` output parameter is used to provide
2444 * information about length of the path.
2445 *
2446 * Path returned this way should be eventually released using `ypath_destroy`.
2447 */
2448struct YPathSegment *ymap_event_path(const struct YMapEvent *e, uint32_t *len);
2449
2450/**
2451 * Returns a path from a root type down to a current shared collection (which can be obtained using
2452 * `yxmlelem_event_path` function). It can consist of either integer indexes (used by sequence
2453 * components) or *char keys (used by map components). `len` output parameter is used to provide
2454 * information about length of the path.
2455 *
2456 * Path returned this way should be eventually released using `ypath_destroy`.
2457 */
2458struct YPathSegment *yxmlelem_event_path(const struct YXmlEvent *e, uint32_t *len);
2459
2460/**
2461 * Returns a path from a root type down to a current shared collection (which can be obtained using
2462 * `yxmltext_event_path` function). It can consist of either integer indexes (used by sequence
2463 * components) or *char keys (used by map components). `len` output parameter is used to provide
2464 * information about length of the path.
2465 *
2466 * Path returned this way should be eventually released using `ypath_destroy`.
2467 */
2468struct YPathSegment *yxmltext_event_path(const struct YXmlTextEvent *e, uint32_t *len);
2469
2470/**
2471 * Returns a path from a root type down to a current shared collection (which can be obtained using
2472 * `yarray_event_target` function). It can consist of either integer indexes (used by sequence
2473 * components) or *char keys (used by map components). `len` output parameter is used to provide
2474 * information about length of the path.
2475 *
2476 * Path returned this way should be eventually released using `ypath_destroy`.
2477 */
2478struct YPathSegment *yarray_event_path(const struct YArrayEvent *e, uint32_t *len);
2479
2480/**
2481 * Releases allocated memory used by objects returned from path accessor functions of shared type
2482 * events.
2483 */
2484void ypath_destroy(struct YPathSegment *path, uint32_t len);
2485
2486/**
2487 * Returns a sequence of changes produced by sequence component of shared collections (such as
2488 * `YText`, `YXmlText` and XML nodes added to `YXmlElement`). `len` output parameter is used to
2489 * provide information about number of changes produced.
2490 *
2491 * Delta returned from this function should eventually be released using `ytext_delta_destroy`
2492 * function.
2493 */
2494struct YDeltaOut *ytext_event_delta(const struct YTextEvent *e, uint32_t *len);
2495
2496/**
2497 * Returns a sequence of changes produced by sequence component of shared collections (such as
2498 * `YText`, `YXmlText` and XML nodes added to `YXmlElement`). `len` output parameter is used to
2499 * provide information about number of changes produced.
2500 *
2501 * Delta returned from this function should eventually be released using `ytext_delta_destroy`
2502 * function.
2503 */
2504struct YDeltaOut *yxmltext_event_delta(const struct YXmlTextEvent *e, uint32_t *len);
2505
2506/**
2507 * Returns a sequence of changes produced by sequence component of shared collections (such as
2508 * `YText`, `YXmlText` and XML nodes added to `YXmlElement`). `len` output parameter is used to
2509 * provide information about number of changes produced.
2510 *
2511 * Delta returned from this function should eventually be released using `yevent_delta_destroy`
2512 * function.
2513 */
2514struct YEventChange *yarray_event_delta(const struct YArrayEvent *e, uint32_t *len);
2515
2516/**
2517 * Returns a sequence of changes produced by sequence component of shared collections (such as
2518 * `YText`, `YXmlText` and XML nodes added to `YXmlElement`). `len` output parameter is used to
2519 * provide information about number of changes produced.
2520 *
2521 * Delta returned from this function should eventually be released using `yevent_delta_destroy`
2522 * function.
2523 */
2524struct YEventChange *yxmlelem_event_delta(const struct YXmlEvent *e, uint32_t *len);
2525
2526/**
2527 * Releases memory allocated by the object returned from `ytext_delta` function.
2528 */
2529void ytext_delta_destroy(struct YDeltaOut *delta, uint32_t len);
2530
2531/**
2532 * Releases memory allocated by the object returned from `yevent_delta` function.
2533 */
2534void yevent_delta_destroy(struct YEventChange *delta, uint32_t len);
2535
2536/**
2537 * Returns a sequence of changes produced by map component of shared collections (such as
2538 * `YMap` and `YXmlText`/`YXmlElement` attribute changes). `len` output parameter is used to
2539 * provide information about number of changes produced.
2540 *
2541 * Delta returned from this function should eventually be released using `yevent_keys_destroy`
2542 * function.
2543 */
2544struct YEventKeyChange *ymap_event_keys(const struct YMapEvent *e, uint32_t *len);
2545
2546/**
2547 * Returns a sequence of changes produced by map component of shared collections.
2548 * `len` output parameter is used to provide information about number of changes produced.
2549 *
2550 * Delta returned from this function should eventually be released using `yevent_keys_destroy`
2551 * function.
2552 */
2553struct YEventKeyChange *yxmlelem_event_keys(const struct YXmlEvent *e, uint32_t *len);
2554
2555/**
2556 * Returns a sequence of changes produced by map component of shared collections.
2557 * `len` output parameter is used to provide information about number of changes produced.
2558 *
2559 * Delta returned from this function should eventually be released using `yevent_keys_destroy`
2560 * function.
2561 */
2562struct YEventKeyChange *yxmltext_event_keys(const struct YXmlTextEvent *e, uint32_t *len);
2563
2564/**
2565 * Releases memory allocated by the object returned from `yxml_event_keys` and `ymap_event_keys`
2566 * functions.
2567 */
2568void yevent_keys_destroy(struct YEventKeyChange *keys, uint32_t len);
2569
2570/**
2571 * Creates a new instance of undo manager bound to a current `doc`. It can be used to track
2572 * specific shared refs via `yundo_manager_add_scope` and updates coming from specific origin
2573 * - like ability to undo/redo operations originating only at the local peer - by using
2574 * `yundo_manager_add_origin`.
2575 *
2576 * This object can be deallocated via `yundo_manager_destroy`.
2577 */
2578YUndoManager *yundo_manager(const struct YUndoManagerOptions *options);
2579
2580/**
2581 * Deallocated undo manager instance created via `yundo_manager`.
2582 */
2583void yundo_manager_destroy(YUndoManager *mgr);
2584
2585/**
2586 * Adds an origin to be tracked by current undo manager. This way only changes made within context
2587 * of transactions created with specific origin will be subjects of undo/redo operations. This is
2588 * useful when you want to be able to revert changed done by specific user without reverting
2589 * changes made by other users that were applied in the meantime.
2590 */
2591void yundo_manager_add_origin(YUndoManager *mgr, uint32_t origin_len, const char *origin);
2592
2593/**
2594 * Removes an origin previously added to undo manager via `yundo_manager_add_origin`.
2595 */
2596void yundo_manager_remove_origin(YUndoManager *mgr, uint32_t origin_len, const char *origin);
2597
2598/**
2599 * Add specific shared type to be tracked by this instance of an undo manager.
2600 */
2601void yundo_manager_add_scope(YUndoManager *mgr, const YDoc *doc, const Branch *ytype);
2602
2603/**
2604 * Removes all the undo/redo stack changes tracked by current undo manager. This also cleans up
2605 * all the items that couldn't be deallocated / garbage collected for the sake of possible
2606 * undo/redo operations.
2607 *
2608 * Keep in mind that this function call requires that underlying document store is not concurrently
2609 * modified by other read-write transaction. This is done by acquiring the read-only transaction
2610 * itself. If such transaction could be acquired (because of another read-write transaction is in
2611 * progress, this function will hold current thread until acquisition is possible.
2612 */
2613void yundo_manager_clear(YUndoManager *mgr);
2614
2615/**
2616 * Cuts off tracked changes, producing a new stack item on undo stack.
2617 *
2618 * By default, undo manager gathers undergoing changes together into undo stack items on periodic
2619 * basis (defined by `YUndoManagerOptions.capture_timeout_millis`). By calling this function, we're
2620 * explicitly creating a new stack item will all the changes registered since last stack item was
2621 * created.
2622 */
2623void yundo_manager_stop(YUndoManager *mgr);
2624
2625/**
2626 * Performs an undo operations, reverting all the changes defined by the last undo stack item.
2627 * These changes can be then reapplied again by calling `yundo_manager_redo` function.
2628 *
2629 * Returns `Y_TRUE` if successfully managed to do an undo operation.
2630 * Returns `Y_FALSE` if undo stack was empty or if undo couldn't be performed (because another
2631 * transaction is in progress).
2632 */
2633uint8_t yundo_manager_undo(YUndoManager *mgr);
2634
2635/**
2636 * Performs a redo operations, reapplying changes undone by `yundo_manager_undo` operation.
2637 *
2638 * Returns `Y_TRUE` if successfully managed to do a redo operation.
2639 * Returns `Y_FALSE` if redo stack was empty or if redo couldn't be performed (because another
2640 * transaction is in progress).
2641 */
2642uint8_t yundo_manager_redo(YUndoManager *mgr);
2643
2644/**
2645 * Returns number of elements stored on undo stack.
2646 */
2647uint32_t yundo_manager_undo_stack_len(YUndoManager *mgr);
2648
2649/**
2650 * Returns number of elements stored on redo stack.
2651 */
2652uint32_t yundo_manager_redo_stack_len(YUndoManager *mgr);
2653
2654/**
2655 * Subscribes a `callback` function pointer to a given undo manager event. This event will be
2656 * triggered every time a new undo/redo stack item is added.
2657 *
2658 * Returns a subscription pointer that can be used to cancel current callback registration via
2659 * `yunobserve`.
2660 */
2661YSubscription *yundo_manager_observe_added(YUndoManager *mgr,
2662 void *state,
2663 void (*callback)(void*, const struct YUndoEvent*));
2664
2665/**
2666 * Subscribes a `callback` function pointer to a given undo manager event. This event will be
2667 * triggered every time a undo/redo operation was called.
2668 *
2669 * Returns a subscription pointer that can be used to cancel current callback registration via
2670 * `yunobserve`.
2671 */
2672YSubscription *yundo_manager_observe_popped(YUndoManager *mgr,
2673 void *state,
2674 void (*callback)(void*, const struct YUndoEvent*));
2675
2676/**
2677 * Returns a value informing what kind of Yrs shared collection given `branch` represents.
2678 * Returns either 0 when `branch` is null or one of values: `Y_ARRAY`, `Y_TEXT`, `Y_MAP`,
2679 * `Y_XML_ELEM`, `Y_XML_TEXT`.
2680 */
2681int8_t ytype_kind(const Branch *branch);
2682
2683/**
2684 * Releases resources allocated by `YStickyIndex` pointers.
2685 */
2686void ysticky_index_destroy(YStickyIndex *pos);
2687
2688/**
2689 * Returns association of current `YStickyIndex`.
2690 * If association is **after** the referenced inserted character, returned number will be >= 0.
2691 * If association is **before** the referenced inserted character, returned number will be < 0.
2692 */
2693int8_t ysticky_index_assoc(const YStickyIndex *pos);
2694
2695/**
2696 * Retrieves a `YStickyIndex` corresponding to a given human-readable `index` pointing into
2697 * the shared y-type `branch`. Unlike standard indexes sticky one enables to track
2698 * the location inside of a shared y-types, even in the face of concurrent updates.
2699 *
2700 * If association is >= 0, the resulting position will point to location **after** the referenced index.
2701 * If association is < 0, the resulting position will point to location **before** the referenced index.
2702 */
2703YStickyIndex *ysticky_index_from_index(const Branch *branch,
2704 YTransaction *txn,
2705 uint32_t index,
2706 int8_t assoc);
2707
2708/**
2709 * Serializes `YStickyIndex` into binary representation. `len` parameter is updated with byte
2710 * length of the generated binary. Returned binary can be free'd using `ybinary_destroy`.
2711 */
2712char *ysticky_index_encode(const YStickyIndex *pos, uint32_t *len);
2713
2714/**
2715 * Serializes `YStickyIndex` into JSON representation. `len` parameter is updated with byte
2716 * length of the generated binary. Returned binary can be free'd using `ybinary_destroy`.
2717 */
2718YStickyIndex *ysticky_index_decode(const char *binary, uint32_t len);
2719
2720/**
2721 * Serialize `YStickyIndex` into null-terminated UTF-8 encoded JSON string, that's compatible with
2722 * Yjs RelativePosition serialization format. The `len` parameter is updated with byte length of
2723 * of the output JSON string. This string can be freed using `ystring_destroy`.
2724 */
2725char *ysticky_index_to_json(const YStickyIndex *pos);
2726
2727/**
2728 * Deserializes `YStickyIndex` from the payload previously serialized using `ysticky_index_to_json`.
2729 * The input `json` parameter is a NULL-terminated UTF-8 encoded string containing a JSON
2730 * compatible with Yjs RelativePosition serialization format.
2731 *
2732 * Returns null pointer if deserialization failed.
2733 *
2734 * This function DOESN'T release the `json` parameter: it needs to be done manually - if JSON
2735 * string was created using `ysticky_index_to_json` function, it can be freed using `ystring_destroy`.
2736 */
2737YStickyIndex *ysticky_index_from_json(const char *json);
2738
2739/**
2740 * Given `YStickyIndex` and transaction reference, if computes a human-readable index in a
2741 * context of the referenced shared y-type.
2742 *
2743 * `out_branch` is getting assigned with a corresponding shared y-type reference.
2744 * `out_index` will be used to store computed human-readable index.
2745 */
2746void ysticky_index_read(const YStickyIndex *pos,
2747 const YTransaction *txn,
2748 Branch **out_branch,
2749 uint32_t *out_index);
2750
2751void yweak_destroy(const Weak *weak);
2752
2753struct YOutput *yweak_deref(const Branch *map_link, const YTransaction *txn);
2754
2755void yweak_read(const Branch *text_link,
2756 const YTransaction *txn,
2757 Branch **out_branch,
2758 uint32_t *out_start_index,
2759 uint32_t *out_end_index);
2760
2761YWeakIter *yweak_iter(const Branch *array_link, const YTransaction *txn);
2762
2763void yweak_iter_destroy(YWeakIter *iter);
2764
2765struct YOutput *yweak_iter_next(YWeakIter *iter);
2766
2767char *yweak_string(const Branch *text_link, const YTransaction *txn);
2768
2769char *yweak_xml_string(const Branch *xml_text_link, const YTransaction *txn);
2770
2771/**
2772 * Subscribes a given callback function `cb` to changes made by this `YText` instance. Callbacks
2773 * are triggered whenever a `ytransaction_commit` is called.
2774 * Returns a subscription ID which can be then used to unsubscribe this callback by using
2775 * `yunobserve` function.
2776 */
2777YSubscription *yweak_observe(const Branch *weak,
2778 void *state,
2779 void (*cb)(void*, const struct YWeakLinkEvent*));
2780
2781const Weak *ymap_link(const Branch *map, const YTransaction *txn, const char *key);
2782
2783const Weak *ytext_quote(const Branch *text,
2784 YTransaction *txn,
2785 uint32_t *start_index,
2786 uint32_t *end_index,
2787 int8_t start_exclusive,
2788 int8_t end_exclusive);
2789
2790const Weak *yarray_quote(const Branch *array,
2791 YTransaction *txn,
2792 uint32_t *start_index,
2793 uint32_t *end_index,
2794 int8_t start_exclusive,
2795 int8_t end_exclusive);
2796
2797/**
2798 * Returns a logical identifier for a given shared collection. That collection must be alive at
2799 * the moment of function call.
2800 */
2801struct YBranchId ybranch_id(const Branch *branch);
2802
2803/**
2804 * Given a logical identifier, returns a physical pointer to a shared collection.
2805 * Returns null if collection was not found - either because it was not defined or not synchronized
2806 * yet.
2807 * Returned pointer may still point to deleted collection. In such case a subsequent `ybranch_alive`
2808 * function call is required.
2809 */
2810Branch *ybranch_get(const struct YBranchId *branch_id, YTransaction *txn);
2811
2812/**
2813 * Check if current branch is still alive (returns `Y_TRUE`, otherwise `Y_FALSE`).
2814 * If it was deleted, this branch pointer is no longer a valid pointer and cannot be used to
2815 * execute any functions using it.
2816 */
2817uint8_t ybranch_alive(Branch *branch);
2818
2819/**
2820 * Returns a UTF-8 encoded, NULL-terminated JSON string representation of the current branch
2821 * contents. Once no longer needed, this string must be explicitly deallocated by user using
2822 * `ystring_destroy`.
2823 *
2824 * If branch type couldn't be resolved (which usually happens for root-level types that were not
2825 * initialized locally) or doesn't have JSON representation a NULL pointer can be returned.
2826 */
2827char *ybranch_json(Branch *branch, YTransaction *txn);
2828
2829#endif
