Package net.carcdr.ycrdt.panama.ffi

Class Yrs

java.lang.Object

net.carcdr.ycrdt.panama.ffi.Yrs

public final class Yrs
extends Object

Panama FFM bindings for the yffi (Y-CRDT C FFI) library.

This class provides low-level access to the native yffi functions using Java's Foreign Function and Memory API (Project Panama).

Field Summary

Fields

Modifier and Type	Field	Description
static final FunctionDescriptor	UPDATE_CALLBACK_DESCRIPTOR	FunctionDescriptor for the update observer callback.
static final int	Y_EVENT_CHANGE_ADD	Change type: elements were added.
static final int	Y_EVENT_CHANGE_DELETE	Change type: elements were deleted.
static final int	Y_EVENT_CHANGE_RETAIN	Change type: elements were retained (no change).
static final int	Y_EVENT_KEY_CHANGE_ADD	Key change type: attribute was added.
static final int	Y_EVENT_KEY_CHANGE_DELETE	Key change type: attribute was deleted.
static final int	Y_EVENT_KEY_CHANGE_UPDATE	Key change type: attribute was updated.
static final byte	Y_JSON_BOOL	Tag constant for boolean values in YInput/YOutput.
static final int	Y_XML_ELEM	YOutput tag for YXmlElement.
static final int	Y_XML_FRAG	YOutput tag for YXmlFragment.
static final int	Y_XML_TEXT	YOutput tag for YXmlText.
static final StructLayout	YCHUNK_FMT_ENTRY_LAYOUT	Layout for YChunk formatting entry (embedded YOutput, not pointer).
static final StructLayout	YCHUNK_LAYOUT	Layout for the YChunk struct.
static final StructLayout	YDELTA_OUT_LAYOUT	Layout for YDeltaOut struct.
static final StructLayout	YEVENT_CHANGE_LAYOUT	Layout for YEventChange struct.
static final StructLayout	YEVENT_KEY_CHANGE_LAYOUT	Layout for YEventKeyChange struct.
static final StructLayout	YINPUT_LAYOUT	Layout for the YInput struct (24 bytes).
static final StructLayout	YMAP_ENTRY_LAYOUT	Layout for YMapEntry struct.
static final StructLayout	YOUTPUT_LAYOUT	Layout for the YOutput struct.
static final byte	YOUTPUT_TAG_BOOL	YOutput tag for boolean content.
static final byte	YOUTPUT_TAG_FLOAT	YOutput tag for 64-bit floating-point content.
static final byte	YOUTPUT_TAG_INT	YOutput tag for 64-bit integer content.
static final byte	YOUTPUT_TAG_NULL	YOutput tag for null content.
static final byte	YOUTPUT_TAG_STRING	YOutput tag for string content.
static final FunctionDescriptor	YXML_CALLBACK_DESCRIPTOR	FunctionDescriptor for XML element/fragment observer callback.
static final StructLayout	YXMLATTR_LAYOUT	Layout for YXmlAttr struct.
static final FunctionDescriptor	YXMLTEXT_CALLBACK_DESCRIPTOR	FunctionDescriptor for XML text observer callback.

Method Summary

Modifier and Type	Method	Description
static MemorySegment	createBinary(Arena arena, byte[] data)	Copies a byte array to native memory in the given arena.
static MemorySegment	createString(Arena arena, String str)	Creates a native string from a Java string in the given arena.
static MemorySegment	createYInputFromObject(Arena arena, Object value)	Creates a YInput from a Java Object based on its type.
static byte[]	readAndFreeBinary(MemorySegment ptr, int len)	Reads a native binary buffer and frees it.
static String	readAndFreeString(MemorySegment ptr)	Reads a native string and frees it.
static MemorySegment	yarray(MemorySegment doc, MemorySegment name)	Gets or creates a YArray with the given name.
static MemorySegment	yarrayGet(MemorySegment array, MemorySegment txn, int index)	Gets a value from an array at the given index.
static void	yarrayInsertRange(MemorySegment array, MemorySegment txn, int index, MemorySegment values, int valuesLen)	Inserts values into an array at the given index.
static int	yarrayLen(MemorySegment array)	Gets the length of a YArray.
static void	yarrayRemoveRange(MemorySegment array, MemorySegment txn, int index, int len)	Removes values from an array at the given range.
static void	ybinaryDestroy(MemorySegment ptr, int len)	Frees a binary buffer allocated by yffi.
static MemorySegment	ybranchJson(MemorySegment branch, MemorySegment txn)	Gets the JSON representation of a branch.
static MemorySegment	ychunkFmtEntryGetValue(MemorySegment entry)	Gets a slice of the embedded YOutput value from a YChunk formatting entry.
static String	ychunkFmtEntryReadKey(MemorySegment entry)	Reads the key from a YChunk formatting entry.
static MemorySegment	ychunkGetData(MemorySegment chunk)	Gets the embedded YOutput data from a YChunk.
static MemorySegment	ychunkGetFmt(MemorySegment chunk)	Gets the formatting entries pointer from a YChunk.
static int	ychunkGetFmtLen(MemorySegment chunk)	Gets the formatting entry count from a YChunk.
static void	ychunksDestroy(MemorySegment chunks, int len)	Frees a YChunk array returned by ytextChunks.
static void	ydocDestroy(MemorySegment doc)	Destroys a Y-CRDT document.
static MemorySegment	ydocGuid(MemorySegment doc)	Gets the GUID of a document.
static long	ydocId(MemorySegment doc)	Gets the client ID of a document.
static MemorySegment	ydocNew()	Creates a new Y-CRDT document.
static MemorySegment	ydocObserveUpdatesV1(MemorySegment doc, MemorySegment state, MemorySegment callback)	Registers an observer for document updates (v1 encoding).
static MemorySegment	ydocReadTransaction(MemorySegment doc)	Creates a read transaction on a document.
static MemorySegment	ydocWriteTransaction(MemorySegment doc, int originLen, MemorySegment origin)	Creates a write transaction on a document.
static void	yeventDeltaDestroy(MemorySegment delta, int len)	Destroys an array of YEventChange structs.
static void	yeventKeysDestroy(MemorySegment keys, int len)	Destroys an array of YEventKeyChange structs.
static MemorySegment	yinputBool(Arena arena, boolean value)	Creates a YInput containing a boolean value.
static MemorySegment	yinputFloat(Arena arena, double num)	Creates a YInput containing a double value.
static MemorySegment	yinputLong(Arena arena, long num)	Creates a YInput containing a long value.
static MemorySegment	yinputMap(Arena arena, Map<String,Object> attributes)	Creates a YInput containing a map of attributes (for text formatting).
static MemorySegment	yinputNull(Arena arena)	Creates a YInput containing null (used for removing formatting attributes).
static MemorySegment	yinputString(Arena arena, MemorySegment str)	Creates a YInput containing a string value.
static MemorySegment	yinputYdoc(Arena arena, MemorySegment docPtr)	Creates a YInput containing a subdocument.
static MemorySegment	ymap(MemorySegment doc, MemorySegment name)	Gets or creates a YMap with the given name.
static void	ymapEntryDestroy(MemorySegment entry)	Destroys a map entry.
static String	ymapEntryReadKey(MemorySegment entry)	Reads the key from a YMapEntry.
static MemorySegment	ymapGet(MemorySegment map, MemorySegment txn, MemorySegment key)	Gets a value from a map by key.
static void	ymapInsert(MemorySegment map, MemorySegment txn, MemorySegment key, MemorySegment value)	Inserts a value into a YMap.
static MemorySegment	ymapIter(MemorySegment map, MemorySegment txn)	Creates an iterator over map entries.
static void	ymapIterDestroy(MemorySegment iter)	Destroys a map iterator.
static MemorySegment	ymapIterNext(MemorySegment iter)	Gets the next entry from the iterator.
static int	ymapLen(MemorySegment map, MemorySegment txn)	Gets the number of entries in a YMap.
static void	ymapRemove(MemorySegment map, MemorySegment txn, MemorySegment key)	Removes a value from a YMap.
static void	youtputDestroy(MemorySegment val)	Frees a YOutput value.
static byte	youtputGetTag(MemorySegment output)	Reads the tag byte from a YOutput struct.
static MemorySegment	youtputReadBool(MemorySegment val)	Reads a boolean from a YOutput value.
static MemorySegment	youtputReadFloat(MemorySegment val)	Reads a double from a YOutput value.
static MemorySegment	youtputReadLong(MemorySegment val)	Reads a long from a YOutput value.
static MemorySegment	youtputReadString(MemorySegment val)	Reads a string from a YOutput value.
static MemorySegment	youtputReadYdoc(MemorySegment val)	Reads a subdocument from a YOutput value.
static MemorySegment	youtputReadYxmlelem(MemorySegment val)	Reads an XML element from a YOutput value.
static MemorySegment	youtputReadYxmltext(MemorySegment val)	Reads an XML text node from a YOutput value.
static void	ystringDestroy(MemorySegment str)	Frees a string allocated by yffi.
static MemorySegment	ytext(MemorySegment doc, MemorySegment name)	Gets or creates a YText with the given name.
static MemorySegment	ytextChunks(MemorySegment txt, MemorySegment txn, MemorySegment lenOut)	Gets formatted text chunks from a text node (YText or YXmlText).
static void	ytextDeltaDestroy(MemorySegment delta, int len)	Destroys an array of YDeltaOut structs.
static void	ytextInsert(MemorySegment txt, MemorySegment txn, int index, MemorySegment value, MemorySegment attrs)	Inserts text at the given index.
static int	ytextLen(MemorySegment txt, MemorySegment txn)	Gets the length of a YText.
static void	ytextRemoveRange(MemorySegment txt, MemorySegment txn, int index, int len)	Removes text from the given range.
static MemorySegment	ytextString(MemorySegment txt, MemorySegment txn)	Gets the string content of a YText.
static byte	ytransactionApply(MemorySegment txn, MemorySegment diff, int diffLen)	Applies an update diff to a transaction's document.
static void	ytransactionCommit(MemorySegment txn)	Commits and frees a transaction.
static MemorySegment	ytransactionStateDiffV1(MemorySegment txn, MemorySegment sv, int svLen, MemorySegment len)	Gets the state diff from a transaction.
static MemorySegment	ytransactionStateVectorV1(MemorySegment txn, MemorySegment len)	Gets the state vector from a transaction.
static int	ytypeKind(MemorySegment branch)	Gets the type kind of a branch.
static void	yunobserve(MemorySegment subscription)	Unsubscribes an observer.
static void	yxmlattrDestroy(MemorySegment attr)	Destroys an attribute.
static void	yxmlattrIterDestroy(MemorySegment iter)	Destroys an attribute iterator.
static MemorySegment	yxmlattrIterNext(MemorySegment iter)	Gets the next attribute from the iterator.
static String	yxmlattrReadName(MemorySegment attr)	Reads the name from a YXmlAttr.
static String	yxmlattrReadValue(MemorySegment attr)	Reads the value from a YXmlAttr.
static MemorySegment	yxmlelemAttrIter(MemorySegment xml, MemorySegment txn)	Creates an iterator over XML element attributes.
static int	yxmlelemChildLen(MemorySegment xml, MemorySegment txn)	Gets the number of children in an XML element or fragment.
static MemorySegment	yxmlelemEventDelta(MemorySegment event, MemorySegment lenOut)	Gets the delta (child changes) from an XML element event.
static MemorySegment	yxmlelemEventKeys(MemorySegment event, MemorySegment lenOut)	Gets the key changes (attribute changes) from an XML element event.
static MemorySegment	yxmlelemEventTarget(MemorySegment event)	Gets the target branch of an XML element event.
static MemorySegment	yxmlelemGet(MemorySegment xml, MemorySegment txn, int index)	Gets a child from an XML element/fragment at the given index.
static MemorySegment	yxmlelemGetAttr(MemorySegment xml, MemorySegment txn, MemorySegment name)	Gets an attribute value from an XML element.
static void	yxmlelemInsertAttr(MemorySegment xml, MemorySegment txn, MemorySegment name, MemorySegment value)	Sets an attribute on an XML element.
static MemorySegment	yxmlelemInsertElem(MemorySegment xml, MemorySegment txn, int index, MemorySegment name)	Inserts a new XML element as a child at the given index.
static MemorySegment	yxmlelemInsertText(MemorySegment xml, MemorySegment txn, int index)	Inserts a new XML text node as a child at the given index.
static MemorySegment	yxmlelemObserve(MemorySegment xml, MemorySegment state, MemorySegment callback)	Registers an observer for XML element/fragment changes.
static MemorySegment	yxmlelemParent(MemorySegment xml)	Gets the parent of an XML element or text node.
static void	yxmlelemRemoveAttr(MemorySegment xml, MemorySegment txn, MemorySegment name)	Removes an attribute from an XML element.
static void	yxmlelemRemoveRange(MemorySegment xml, MemorySegment txn, int index, int len)	Removes children from an XML element/fragment in a range.
static MemorySegment	yxmlelemString(MemorySegment xml, MemorySegment txn)	Gets the XML string representation of an element/fragment.
static MemorySegment	yxmlelemTag(MemorySegment xml)	Gets the tag name of an XML element.
static MemorySegment	yxmlfragment(MemorySegment doc, MemorySegment name)	Gets or creates a YXmlFragment with the given name.
static MemorySegment	yxmltextEventDelta(MemorySegment event, MemorySegment lenOut)	Gets the delta (text changes) from an XML text event.
static MemorySegment	yxmltextEventTarget(MemorySegment event)	Gets the target branch of an XML text event.
static void	yxmltextFormat(MemorySegment txt, MemorySegment txn, int index, int len, MemorySegment attrs)	Applies formatting to a range of text in an XML text node.
static void	yxmltextInsert(MemorySegment txt, MemorySegment txn, int index, MemorySegment str, MemorySegment attrs)	Inserts text into an XML text node at the given index.
static int	yxmltextLen(MemorySegment txt, MemorySegment txn)	Gets the length of an XML text node.
static MemorySegment	yxmltextObserve(MemorySegment xml, MemorySegment state, MemorySegment callback)	Registers an observer for XML text changes.
static void	yxmltextRemoveRange(MemorySegment txt, MemorySegment txn, int index, int len)	Removes text from an XML text node at the given range.
static MemorySegment	yxmltextString(MemorySegment txt, MemorySegment txn)	Gets the string content of an XML text node.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

Y_JSON_BOOL

public static final byte Y_JSON_BOOL

Tag constant for boolean values in YInput/YOutput.

See Also:

• Constant Field Values

YINPUT_LAYOUT

public static final StructLayout YINPUT_LAYOUT

Layout for the YInput struct (24 bytes). The struct is: tag (1) + padding (3) + len (4) + union value (16 for YMapInputData).

The native YInput struct is 24 bytes total. The union can hold various types including YMapInputData (two pointers = 16 bytes). We construct these structs manually to avoid ARM64 ABI issues with struct-by-value returns.

YMAP_ENTRY_LAYOUT

public static final StructLayout YMAP_ENTRY_LAYOUT

Layout for YMapEntry struct. The struct is: const char *key (8 bytes) + const struct YOutput *value (8 bytes)

Y_XML_ELEM

public static final int Y_XML_ELEM

YOutput tag for YXmlElement.

See Also:

• Constant Field Values

Y_XML_TEXT

public static final int Y_XML_TEXT

YOutput tag for YXmlText.

See Also:

• Constant Field Values

Y_XML_FRAG

public static final int Y_XML_FRAG

YOutput tag for YXmlFragment.

See Also:

• Constant Field Values

UPDATE_CALLBACK_DESCRIPTOR

public static final FunctionDescriptor UPDATE_CALLBACK_DESCRIPTOR

FunctionDescriptor for the update observer callback. Signature: void callback(void* state, uint32_t len, const char* data)

Y_EVENT_CHANGE_ADD

public static final int Y_EVENT_CHANGE_ADD

Change type: elements were added.

See Also:

• Constant Field Values

Y_EVENT_CHANGE_DELETE

public static final int Y_EVENT_CHANGE_DELETE

Change type: elements were deleted.

See Also:

• Constant Field Values

Y_EVENT_CHANGE_RETAIN

public static final int Y_EVENT_CHANGE_RETAIN

Change type: elements were retained (no change).

See Also:

• Constant Field Values

Y_EVENT_KEY_CHANGE_ADD

public static final int Y_EVENT_KEY_CHANGE_ADD

Key change type: attribute was added.

See Also:

• Constant Field Values

Y_EVENT_KEY_CHANGE_DELETE

public static final int Y_EVENT_KEY_CHANGE_DELETE

Key change type: attribute was deleted.

See Also:

• Constant Field Values

Y_EVENT_KEY_CHANGE_UPDATE

public static final int Y_EVENT_KEY_CHANGE_UPDATE

Key change type: attribute was updated.

See Also:

• Constant Field Values

YXML_CALLBACK_DESCRIPTOR

public static final FunctionDescriptor YXML_CALLBACK_DESCRIPTOR

FunctionDescriptor for XML element/fragment observer callback. Signature: void callback(void* state, const YXmlEvent* event)

YXMLTEXT_CALLBACK_DESCRIPTOR

public static final FunctionDescriptor YXMLTEXT_CALLBACK_DESCRIPTOR

FunctionDescriptor for XML text observer callback. Signature: void callback(void* state, const YXmlTextEvent* event)

YEVENT_CHANGE_LAYOUT

public static final StructLayout YEVENT_CHANGE_LAYOUT

Layout for YEventChange struct. struct YEventChange { uint8_t tag; uint32_t len; const YOutput *values; }

YEVENT_KEY_CHANGE_LAYOUT

public static final StructLayout YEVENT_KEY_CHANGE_LAYOUT

Layout for YEventKeyChange struct. struct YEventKeyChange { const char *key; char tag; const YOutput *old_value; const YOutput *new_value; }

YDELTA_OUT_LAYOUT

public static final StructLayout YDELTA_OUT_LAYOUT

Layout for YDeltaOut struct. struct YDeltaOut { uint8_t tag; uint32_t len; uint32_t attributes_len; YDeltaAttr *attributes; YOutput *insert; }

YXMLATTR_LAYOUT

public static final StructLayout YXMLATTR_LAYOUT

Layout for YXmlAttr struct. The struct is: const char *name (8 bytes) + const char *value (8 bytes)

YOUTPUT_LAYOUT

public static final StructLayout YOUTPUT_LAYOUT

Layout for the YOutput struct. struct YOutput { int8_t tag; uint32_t len; union value (16 bytes) }

YOUTPUT_TAG_STRING

public static final byte YOUTPUT_TAG_STRING

YOutput tag for string content.

See Also:

• Constant Field Values

YOUTPUT_TAG_INT

public static final byte YOUTPUT_TAG_INT

YOutput tag for 64-bit integer content.

See Also:

• Constant Field Values

YOUTPUT_TAG_FLOAT

public static final byte YOUTPUT_TAG_FLOAT

YOutput tag for 64-bit floating-point content.

See Also:

• Constant Field Values

YOUTPUT_TAG_BOOL

public static final byte YOUTPUT_TAG_BOOL

YOutput tag for boolean content.

See Also:

• Constant Field Values

YOUTPUT_TAG_NULL

public static final byte YOUTPUT_TAG_NULL

YOutput tag for null content.

See Also:

• Constant Field Values

YCHUNK_FMT_ENTRY_LAYOUT

public static final StructLayout YCHUNK_FMT_ENTRY_LAYOUT

Layout for YChunk formatting entry (embedded YOutput, not pointer). struct YChunkFmtEntry { const char *key; struct YOutput value; }

Note: Different from YMAP_ENTRY_LAYOUT which has pointer to YOutput. This layout has embedded YOutput, so total size is 8 + 24 = 32 bytes.

YCHUNK_LAYOUT

public static final StructLayout YCHUNK_LAYOUT

Layout for the YChunk struct. struct YChunk { YOutput data; uint32_t fmt_len; YMapEntry *fmt; }

Method Details

ydocNew

public static MemorySegment ydocNew()

Creates a new Y-CRDT document.

Returns:

pointer to the new document

ydocDestroy

public static void ydocDestroy(MemorySegment doc)

Destroys a Y-CRDT document.

Parameters:

doc - pointer to the document

ydocId

public static long ydocId(MemorySegment doc)

Gets the client ID of a document.

Parameters:

doc - pointer to the document

Returns:

the client ID

ydocGuid

public static MemorySegment ydocGuid(MemorySegment doc)

Gets the GUID of a document.

Parameters:

doc - pointer to the document

Returns:

pointer to the GUID string (must be freed with ystringDestroy)

ydocReadTransaction

public static MemorySegment ydocReadTransaction(MemorySegment doc)

Creates a read transaction on a document.

Parameters:

doc - pointer to the document

Returns:

pointer to the transaction

ydocWriteTransaction

public static MemorySegment ydocWriteTransaction(MemorySegment doc,
 int originLen,
 MemorySegment origin)

Creates a write transaction on a document.

Parameters:

doc - pointer to the document

originLen - length of the origin string

origin - pointer to the origin string (can be NULL)

Returns:

pointer to the transaction

ytransactionCommit

public static void ytransactionCommit(MemorySegment txn)

Commits and frees a transaction.

Parameters:

txn - pointer to the transaction

ytransactionStateVectorV1

public static MemorySegment ytransactionStateVectorV1(MemorySegment txn,
 MemorySegment len)

Gets the state vector from a transaction.

Parameters:

txn - pointer to the transaction

len - pointer to store the length

Returns:

pointer to the state vector (must be freed with ybinaryDestroy)

ytransactionStateDiffV1

public static MemorySegment ytransactionStateDiffV1(MemorySegment txn,
 MemorySegment sv,
 int svLen,
 MemorySegment len)

Gets the state diff from a transaction.

Parameters:

txn - pointer to the transaction

sv - pointer to the state vector

svLen - length of the state vector

len - pointer to store the result length

Returns:

pointer to the diff (must be freed with ybinaryDestroy)

ytransactionApply

public static byte ytransactionApply(MemorySegment txn,
 MemorySegment diff,
 int diffLen)

Applies an update diff to a transaction's document.

Parameters:

txn - pointer to the transaction

diff - pointer to the update diff

diffLen - length of the diff

Returns:

0 on success, error code on failure

ytext

public static MemorySegment ytext(MemorySegment doc,
 MemorySegment name)

Gets or creates a YText with the given name.

Parameters:

doc - pointer to the document

name - pointer to the name string

Returns:

pointer to the text branch

ytextLen

public static int ytextLen(MemorySegment txt,
 MemorySegment txn)

Gets the length of a YText.

Parameters:

txt - pointer to the text branch

txn - pointer to the transaction

Returns:

the length

ytextString

public static MemorySegment ytextString(MemorySegment txt,
 MemorySegment txn)

Gets the string content of a YText.

Parameters:

txt - pointer to the text branch

txn - pointer to the transaction

Returns:

pointer to the string (must be freed with ystringDestroy)

ytextInsert

public static void ytextInsert(MemorySegment txt,
 MemorySegment txn,
 int index,
 MemorySegment value,
 MemorySegment attrs)

Inserts text at the given index.

Parameters:

txt - pointer to the text branch

txn - pointer to the transaction

index - the index to insert at

value - pointer to the value string

attrs - pointer to the attributes (can be NULL)

ytextRemoveRange

public static void ytextRemoveRange(MemorySegment txt,
 MemorySegment txn,
 int index,
 int len)

Removes text from the given range.

Parameters:

txt - pointer to the text branch

txn - pointer to the transaction

index - the start index

len - the length to remove

yarray

public static MemorySegment yarray(MemorySegment doc,
 MemorySegment name)

Gets or creates a YArray with the given name.

Parameters:

doc - pointer to the document

name - pointer to the name string

Returns:

pointer to the array branch

yarrayLen

public static int yarrayLen(MemorySegment array)

Gets the length of a YArray.

Parameters:

array - pointer to the array branch

Returns:

the length

yarrayInsertRange

public static void yarrayInsertRange(MemorySegment array,
 MemorySegment txn,
 int index,
 MemorySegment values,
 int valuesLen)

Inserts values into an array at the given index.

Parameters:

array - pointer to the array branch

txn - pointer to the transaction

index - the index to insert at

values - pointer to the values array

valuesLen - the number of values

yarrayRemoveRange

public static void yarrayRemoveRange(MemorySegment array,
 MemorySegment txn,
 int index,
 int len)

Removes values from an array at the given range.

Parameters:

array - pointer to the array branch

txn - pointer to the transaction

index - the start index

len - the number of values to remove

ymap

public static MemorySegment ymap(MemorySegment doc,
 MemorySegment name)

Gets or creates a YMap with the given name.

Parameters:

doc - pointer to the document

name - pointer to the name string

Returns:

pointer to the map branch

ymapLen

public static int ymapLen(MemorySegment map,
 MemorySegment txn)

Gets the number of entries in a YMap.

Parameters:

map - pointer to the map branch

txn - pointer to the transaction

Returns:

the number of entries

ymapInsert

public static void ymapInsert(MemorySegment map,
 MemorySegment txn,
 MemorySegment key,
 MemorySegment value)

Inserts a value into a YMap.

Parameters:

map - pointer to the map branch

txn - pointer to the transaction

key - pointer to the key string

value - pointer to the YInput value

ymapRemove

public static void ymapRemove(MemorySegment map,
 MemorySegment txn,
 MemorySegment key)

Removes a value from a YMap.

Parameters:

map - pointer to the map branch

txn - pointer to the transaction

key - pointer to the key string

yxmlfragment

public static MemorySegment yxmlfragment(MemorySegment doc,
 MemorySegment name)

Gets or creates a YXmlFragment with the given name.

Parameters:

doc - pointer to the document

name - pointer to the name string

Returns:

pointer to the xml fragment branch

ystringDestroy

public static void ystringDestroy(MemorySegment str)

Frees a string allocated by yffi.

Parameters:

str - pointer to the string

ybinaryDestroy

public static void ybinaryDestroy(MemorySegment ptr,
 int len)

Frees a binary buffer allocated by yffi.

Parameters:

ptr - pointer to the buffer

len - length of the buffer

createString

public static MemorySegment createString(Arena arena,
 String str)

Creates a native string from a Java string in the given arena.

Parameters:

arena - the arena to allocate in

str - the Java string

Returns:

pointer to the native string

readAndFreeString

public static String readAndFreeString(MemorySegment ptr)

Reads a native string and frees it.

Parameters:

ptr - pointer to the native string

Returns:

the Java string

readAndFreeBinary

public static byte[] readAndFreeBinary(MemorySegment ptr,
 int len)

Reads a native binary buffer and frees it.

Parameters:

ptr - pointer to the buffer

len - length of the buffer

Returns:

the byte array

createBinary

public static MemorySegment createBinary(Arena arena,
 byte[] data)

Copies a byte array to native memory in the given arena.

Parameters:

arena - the arena to allocate in

data - the byte array

Returns:

pointer to the native buffer

yinputString

public static MemorySegment yinputString(Arena arena,
 MemorySegment str)

Creates a YInput containing a string value.

This constructs the YInput struct manually in Java to avoid ARM64 ABI issues with the native yinput_string function, which returns a 24-byte struct via sret.

Parameters:

arena - the arena to allocate the struct in

str - pointer to the null-terminated string

Returns:

the YInput struct as a MemorySegment

yinputFloat

public static MemorySegment yinputFloat(Arena arena,
 double num)

Creates a YInput containing a double value.

This constructs the YInput struct manually in Java to avoid ARM64 ABI issues with the native yinput_float function.

Parameters:

arena - the arena to allocate the struct in

num - the double value

Returns:

the YInput struct as a MemorySegment

yinputLong

public static MemorySegment yinputLong(Arena arena,
 long num)

Creates a YInput containing a long value.

This constructs the YInput struct manually in Java to avoid ARM64 ABI issues with the native yinput_long function.

Parameters:

arena - the arena to allocate the struct in

num - the long value

Returns:

the YInput struct as a MemorySegment

yinputYdoc

public static MemorySegment yinputYdoc(Arena arena,
 MemorySegment docPtr)

Creates a YInput containing a subdocument.

This constructs the YInput struct manually in Java to avoid ARM64 ABI issues with the native yinput_ydoc function.

Parameters:

arena - the arena to allocate the struct in

docPtr - pointer to the YDoc

Returns:

the YInput struct as a MemorySegment

yinputBool

public static MemorySegment yinputBool(Arena arena,
 boolean value)

Creates a YInput containing a boolean value.

Parameters:

arena - the arena to allocate the struct in

value - the boolean value

Returns:

the YInput struct as a MemorySegment

yinputNull

public static MemorySegment yinputNull(Arena arena)

Creates a YInput containing null (used for removing formatting attributes).

Parameters:

arena - the arena to allocate the struct in

Returns:

the YInput struct as a MemorySegment

yinputMap

public static MemorySegment yinputMap(Arena arena,
 Map<String,Object> attributes)

Creates a YInput containing a map of attributes (for text formatting).

This is used to pass formatting attributes to yxmltext_insert and yxmltext_format. The map is converted to the native YMapInputData format with separate arrays for keys and values.

Parameters:

arena - the arena to allocate all memory in

attributes - the attributes map (can be null or empty)

Returns:

pointer to the YInput struct, or NULL segment if attributes is null/empty

createYInputFromObject

public static MemorySegment createYInputFromObject(Arena arena,
 Object value)

Creates a YInput from a Java Object based on its type.

Supported inputs: null, Boolean, String, Double/Float, and any other Number. A non-primitive, non-null, non-Number object falls back to its Object.toString() representation.

Parameters:

arena - the arena to allocate in

value - the Java value

Returns:

the YInput struct

yarrayGet

public static MemorySegment yarrayGet(MemorySegment array,
 MemorySegment txn,
 int index)

Gets a value from an array at the given index.

Parameters:

array - pointer to the array branch

txn - pointer to the transaction

index - the index

Returns:

pointer to the YOutput (must be freed with youtputDestroy)

youtputDestroy

public static void youtputDestroy(MemorySegment val)

Frees a YOutput value.

Parameters:

val - pointer to the YOutput

youtputReadString

public static MemorySegment youtputReadString(MemorySegment val)

Reads a string from a YOutput value.

Parameters:

val - pointer to the YOutput

Returns:

pointer to the string (must be freed with ystringDestroy), or null if not a string

youtputReadFloat

public static MemorySegment youtputReadFloat(MemorySegment val)

Reads a double from a YOutput value.

Parameters:

val - pointer to the YOutput

Returns:

pointer to the double, or null if not a double

youtputReadLong

public static MemorySegment youtputReadLong(MemorySegment val)

Reads a long from a YOutput value.

Parameters:

val - pointer to the YOutput

Returns:

pointer to the long, or null if not a long

youtputReadYdoc

public static MemorySegment youtputReadYdoc(MemorySegment val)

Reads a subdocument from a YOutput value.

Parameters:

val - pointer to the YOutput

Returns:

pointer to the YDoc, or null if not a subdocument

youtputReadBool

public static MemorySegment youtputReadBool(MemorySegment val)

Reads a boolean from a YOutput value.

Parameters:

val - pointer to the YOutput

Returns:

pointer to the boolean (uint8_t), or null if not a boolean

ymapIter

public static MemorySegment ymapIter(MemorySegment map,
 MemorySegment txn)

Creates an iterator over map entries.

Parameters:

map - pointer to the map branch

txn - pointer to the transaction

Returns:

pointer to the iterator

ymapIterDestroy

public static void ymapIterDestroy(MemorySegment iter)

Destroys a map iterator.

Parameters:

iter - pointer to the iterator

ymapIterNext

public static MemorySegment ymapIterNext(MemorySegment iter)

Gets the next entry from the iterator.

Parameters:

iter - pointer to the iterator

Returns:

pointer to the entry, or null if no more entries

ymapEntryDestroy

public static void ymapEntryDestroy(MemorySegment entry)

Destroys a map entry.

Parameters:

entry - pointer to the entry

ymapEntryReadKey

public static String ymapEntryReadKey(MemorySegment entry)

Reads the key from a YMapEntry.

Parameters:

entry - pointer to the entry

Returns:

the key string

ymapGet

public static MemorySegment ymapGet(MemorySegment map,
 MemorySegment txn,
 MemorySegment key)

Gets a value from a map by key.

Parameters:

map - pointer to the map branch

txn - pointer to the transaction

key - pointer to the key string

Returns:

pointer to the YOutput (must be freed with youtputDestroy), or null if not found

ytypeKind

public static int ytypeKind(MemorySegment branch)

Gets the type kind of a branch.

Parameters:

branch - pointer to the branch

Returns:

the type kind (Y_XML_ELEM, Y_XML_TEXT, Y_XML_FRAG, etc.)

yxmlelemParent

public static MemorySegment yxmlelemParent(MemorySegment xml)

Gets the parent of an XML element or text node.

Parameters:

xml - pointer to the xml branch

Returns:

pointer to the parent branch, or null if root-level

ybranchJson

public static MemorySegment ybranchJson(MemorySegment branch,
 MemorySegment txn)

Gets the JSON representation of a branch.

Parameters:

branch - pointer to the branch

txn - pointer to the transaction

Returns:

pointer to the JSON string (must be freed with ystringDestroy)

ydocObserveUpdatesV1

public static MemorySegment ydocObserveUpdatesV1(MemorySegment doc,
 MemorySegment state,
 MemorySegment callback)

Registers an observer for document updates (v1 encoding).

Parameters:

doc - pointer to the document

state - opaque state pointer passed to callback

callback - function pointer for the callback (created via Linker.upcallStub)

Returns:

pointer to the subscription (must be freed with yunobserve)

yunobserve

public static void yunobserve(MemorySegment subscription)

Unsubscribes an observer.

Parameters:

subscription - pointer to the subscription

yxmlelemObserve

public static MemorySegment yxmlelemObserve(MemorySegment xml,
 MemorySegment state,
 MemorySegment callback)

Registers an observer for XML element/fragment changes.

Parameters:

xml - pointer to the xml branch

state - opaque state pointer passed to callback

callback - function pointer for the callback

Returns:

pointer to the subscription

yxmltextObserve

public static MemorySegment yxmltextObserve(MemorySegment xml,
 MemorySegment state,
 MemorySegment callback)

Registers an observer for XML text changes.

Parameters:

xml - pointer to the xml text branch

state - opaque state pointer passed to callback

callback - function pointer for the callback

Returns:

pointer to the subscription

yxmlelemEventTarget

public static MemorySegment yxmlelemEventTarget(MemorySegment event)

Gets the target branch of an XML element event.

Parameters:

event - pointer to the event

Returns:

pointer to the target branch

yxmltextEventTarget

public static MemorySegment yxmltextEventTarget(MemorySegment event)

Gets the target branch of an XML text event.

Parameters:

event - pointer to the event

Returns:

pointer to the target branch

yxmlelemEventDelta

public static MemorySegment yxmlelemEventDelta(MemorySegment event,
 MemorySegment lenOut)

Gets the delta (child changes) from an XML element event.

Parameters:

event - pointer to the event

lenOut - pointer to uint32_t to receive length

Returns:

pointer to array of YEventChange structs

yxmlelemEventKeys

public static MemorySegment yxmlelemEventKeys(MemorySegment event,
 MemorySegment lenOut)

Gets the key changes (attribute changes) from an XML element event.

Parameters:

event - pointer to the event

lenOut - pointer to uint32_t to receive length

Returns:

pointer to array of YEventKeyChange structs

yxmltextEventDelta

public static MemorySegment yxmltextEventDelta(MemorySegment event,
 MemorySegment lenOut)

Gets the delta (text changes) from an XML text event.

Parameters:

event - pointer to the event

lenOut - pointer to uint32_t to receive length

Returns:

pointer to array of YDeltaOut structs

yeventDeltaDestroy

public static void yeventDeltaDestroy(MemorySegment delta,
 int len)

Destroys an array of YEventChange structs.

Parameters:

delta - pointer to the array

len - length of the array

yeventKeysDestroy

public static void yeventKeysDestroy(MemorySegment keys,
 int len)

Destroys an array of YEventKeyChange structs.

Parameters:

keys - pointer to the array

len - length of the array

ytextDeltaDestroy

public static void ytextDeltaDestroy(MemorySegment delta,
 int len)

Destroys an array of YDeltaOut structs.

Parameters:

delta - pointer to the array

len - length of the array

yxmlelemChildLen

public static int yxmlelemChildLen(MemorySegment xml,
 MemorySegment txn)

Gets the number of children in an XML element or fragment.

Parameters:

xml - pointer to the xml branch

txn - pointer to the transaction

Returns:

the number of children

yxmlelemTag

public static MemorySegment yxmlelemTag(MemorySegment xml)

Gets the tag name of an XML element.

Parameters:

xml - pointer to the xml element branch

Returns:

pointer to the tag string (must be freed with ystringDestroy)

yxmlelemInsertElem

public static MemorySegment yxmlelemInsertElem(MemorySegment xml,
 MemorySegment txn,
 int index,
 MemorySegment name)

Inserts a new XML element as a child at the given index.

Parameters:

xml - pointer to the xml element/fragment branch

txn - pointer to the transaction

index - the index to insert at

name - pointer to the tag name string

Returns:

pointer to the new element branch

yxmlelemInsertText

public static MemorySegment yxmlelemInsertText(MemorySegment xml,
 MemorySegment txn,
 int index)

Inserts a new XML text node as a child at the given index.

Parameters:

xml - pointer to the xml element/fragment branch

txn - pointer to the transaction

index - the index to insert at

Returns:

pointer to the new text branch

yxmlelemRemoveRange

public static void yxmlelemRemoveRange(MemorySegment xml,
 MemorySegment txn,
 int index,
 int len)

Removes children from an XML element/fragment in a range.

Parameters:

xml - pointer to the xml branch

txn - pointer to the transaction

index - the start index

len - the number of children to remove

yxmlelemGet

public static MemorySegment yxmlelemGet(MemorySegment xml,
 MemorySegment txn,
 int index)

Gets a child from an XML element/fragment at the given index.

Parameters:

xml - pointer to the xml branch

txn - pointer to the transaction

index - the index

Returns:

pointer to YOutput (must be freed with youtputDestroy)

yxmlelemString

public static MemorySegment yxmlelemString(MemorySegment xml,
 MemorySegment txn)

Gets the XML string representation of an element/fragment.

Parameters:

xml - pointer to the xml branch

txn - pointer to the transaction

Returns:

pointer to the XML string (must be freed with ystringDestroy)

yxmlelemInsertAttr

public static void yxmlelemInsertAttr(MemorySegment xml,
 MemorySegment txn,
 MemorySegment name,
 MemorySegment value)

Sets an attribute on an XML element.

Parameters:

xml - pointer to the xml element branch

txn - pointer to the transaction

name - pointer to the attribute name string

value - pointer to the attribute value string

yxmlelemRemoveAttr

public static void yxmlelemRemoveAttr(MemorySegment xml,
 MemorySegment txn,
 MemorySegment name)

Removes an attribute from an XML element.

Parameters:

xml - pointer to the xml element branch

txn - pointer to the transaction

name - pointer to the attribute name string

yxmlelemGetAttr

public static MemorySegment yxmlelemGetAttr(MemorySegment xml,
 MemorySegment txn,
 MemorySegment name)

Gets an attribute value from an XML element.

Parameters:

xml - pointer to the xml element branch

txn - pointer to the transaction

name - pointer to the attribute name string

Returns:

pointer to the value string (must be freed with ystringDestroy), or null

yxmlelemAttrIter

public static MemorySegment yxmlelemAttrIter(MemorySegment xml,
 MemorySegment txn)

Creates an iterator over XML element attributes.

Parameters:

xml - pointer to the xml element branch

txn - pointer to the transaction

Returns:

pointer to the iterator

yxmlattrIterNext

public static MemorySegment yxmlattrIterNext(MemorySegment iter)

Gets the next attribute from the iterator.

Parameters:

iter - pointer to the iterator

Returns:

pointer to the attribute, or null if no more attributes

yxmlattrIterDestroy

public static void yxmlattrIterDestroy(MemorySegment iter)

Destroys an attribute iterator.

Parameters:

iter - pointer to the iterator

yxmlattrDestroy

public static void yxmlattrDestroy(MemorySegment attr)

Destroys an attribute.

Parameters:

attr - pointer to the attribute

yxmlattrReadName

public static String yxmlattrReadName(MemorySegment attr)

Reads the name from a YXmlAttr.

Parameters:

attr - pointer to the attribute

Returns:

the name string

yxmlattrReadValue

public static String yxmlattrReadValue(MemorySegment attr)

Reads the value from a YXmlAttr.

Parameters:

attr - pointer to the attribute

Returns:

the value string

yxmltextLen

public static int yxmltextLen(MemorySegment txt,
 MemorySegment txn)

Gets the length of an XML text node.

Parameters:

txt - pointer to the xml text branch

txn - pointer to the transaction

Returns:

the length

yxmltextString

public static MemorySegment yxmltextString(MemorySegment txt,
 MemorySegment txn)

Gets the string content of an XML text node.

Parameters:

txt - pointer to the xml text branch

txn - pointer to the transaction

Returns:

pointer to the string (must be freed with ystringDestroy)

yxmltextInsert

public static void yxmltextInsert(MemorySegment txt,
 MemorySegment txn,
 int index,
 MemorySegment str,
 MemorySegment attrs)

Inserts text into an XML text node at the given index.

Parameters:

txt - pointer to the xml text branch

txn - pointer to the transaction

index - the index to insert at

str - pointer to the string to insert

attrs - pointer to attributes (can be NULL)

yxmltextRemoveRange

public static void yxmltextRemoveRange(MemorySegment txt,
 MemorySegment txn,
 int index,
 int len)

Removes text from an XML text node at the given range.

Parameters:

txt - pointer to the xml text branch

txn - pointer to the transaction

index - the start index

len - the length to remove

yxmltextFormat

public static void yxmltextFormat(MemorySegment txt,
 MemorySegment txn,
 int index,
 int len,
 MemorySegment attrs)

Applies formatting to a range of text in an XML text node.

Parameters:

txt - pointer to the xml text branch

txn - pointer to the transaction

index - the start index

len - the length to format

attrs - pointer to the formatting attributes

youtputReadYxmlelem

public static MemorySegment youtputReadYxmlelem(MemorySegment val)

Reads an XML element from a YOutput value.

Parameters:

val - pointer to the YOutput

Returns:

pointer to the element branch, or null if not an element

youtputReadYxmltext

public static MemorySegment youtputReadYxmltext(MemorySegment val)

Reads an XML text node from a YOutput value.

Parameters:

val - pointer to the YOutput

Returns:

pointer to the text branch, or null if not a text node

youtputGetTag

public static byte youtputGetTag(MemorySegment output)

Reads the tag byte from a YOutput struct.

Parameters:

output - the YOutput memory segment

Returns:

the tag byte indicating the content type

ytextChunks

public static MemorySegment ytextChunks(MemorySegment txt,
 MemorySegment txn,
 MemorySegment lenOut)

Gets formatted text chunks from a text node (YText or YXmlText).

Parameters:

txt - pointer to the text branch

txn - pointer to the transaction

lenOut - pointer to uint32_t to receive chunk count

Returns:

pointer to YChunk array (must be freed with ychunksDestroy)

ychunksDestroy

public static void ychunksDestroy(MemorySegment chunks,
 int len)

Frees a YChunk array returned by ytextChunks.

Parameters:

chunks - pointer to the chunks array

len - number of chunks

ychunkGetData

public static MemorySegment ychunkGetData(MemorySegment chunk)

Gets the embedded YOutput data from a YChunk.

Parameters:

chunk - pointer to the YChunk

Returns:

memory segment pointing to the embedded YOutput data

ychunkGetFmtLen

public static int ychunkGetFmtLen(MemorySegment chunk)

Gets the formatting entry count from a YChunk.

Parameters:

chunk - pointer to the YChunk

Returns:

the number of formatting entries

ychunkGetFmt

public static MemorySegment ychunkGetFmt(MemorySegment chunk)

Gets the formatting entries pointer from a YChunk.

Parameters:

chunk - pointer to the YChunk

Returns:

pointer to the formatting entries array, or NULL if none

ychunkFmtEntryReadKey

public static String ychunkFmtEntryReadKey(MemorySegment entry)

Reads the key from a YChunk formatting entry.

Parameters:

entry - pointer to the formatting entry

Returns:

the key string

ychunkFmtEntryGetValue

public static MemorySegment ychunkFmtEntryGetValue(MemorySegment entry)

Gets a slice of the embedded YOutput value from a YChunk formatting entry.

Parameters:

entry - pointer to the formatting entry

Returns:

memory segment pointing to the embedded YOutput