#include <string.h>
#include "vl_arena.h"
#include "vl_buffer.h"
#include "vl_hashtable.h"

Include dependency graph for vl_msgpack.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	vl_msgpack
	MessagePack Document Object Model. More...

Macros
#define	VL_MSGPACK_ITER_INVALID VL_HASHTABLE_ITER_INVALID

#define	VL_MSGPACK_EXT_NONE -127

#define	VL_MSGPACK_FOREACH_CHILD(packPtr, parentIter, childIterSymbol)

#define	vlMsgPackRoot(packPtr) ((packPtr)->root)
	Macro to retrieve the root of the MessagePack DOM.

Typedefs
typedef vl_hash_iter	vl_msgpack_iter

Enumerations
enum	vl_msgpack_type { VL_MSGPACK_NIL , VL_MSGPACK_BOOL , VL_MSGPACK_INT , VL_MSGPACK_UINT , VL_MSGPACK_FLOAT32 , VL_MSGPACK_FLOAT64 , VL_MSGPACK_STRING , VL_MSGPACK_BINARY , VL_MSGPACK_ARRAY , VL_MSGPACK_MAP , VL_MSGPACK_EXT }
	All MessagePack Types. More...

Functions
VL_API void	vlMsgPackInit (vl_msgpack *pack)
	Initializes the specified MessagePack DOM.

VL_API void	vlMsgPackFree (vl_msgpack *pack)
	Frees the specified MessagePack DOM.

VL_API vl_msgpack *	vlMsgPackNew (void)
	Allocates and initializes a MessagePack DOM.

VL_API void	vlMsgPackDelete (vl_msgpack *pack)
	Deletes the specified MessagePack DOM.

VL_API void	vlMsgPackClear (vl_msgpack *pack)
	Clears the MessagePack DOM, resetting it for reuse.

VL_API vl_msgpack *	vlMsgPackClone (vl_msgpack src, vl_msgpack dest)
	Clones the specified MessagePack DOM to another.

VL_API vl_msgpack_iter	vlMsgPackParent (vl_msgpack *pack, vl_msgpack_iter iter)
	Retrieves the parent node of a given node in the MessagePack DOM.

VL_API vl_dsidx_t	vlMsgPackTotalChildren (vl_msgpack *pack, vl_msgpack_iter iter)
	Retrieves the total number of children of a given node.

VL_API vl_msgpack_iter	vlMsgPackFirstChild (vl_msgpack *pack, vl_msgpack_iter iter)
	Retrieves the first child of a given node.

VL_API vl_msgpack_iter	vlMsgPackNextSibling (vl_msgpack *pack, vl_msgpack_iter iter)
	Retrieves the next sibling of a given node.

VL_API vl_msgpack_iter	vlMsgPackPrevSibling (vl_msgpack *pack, vl_msgpack_iter iter)
	Retrieves the previous sibling of a given node.

VL_API vl_msgpack_type	vlMsgPackType (vl_msgpack *pack, vl_msgpack_iter iter)
	Retrieves the type of a given node in the MessagePack DOM.

VL_API vl_int8_t	vlMsgPackExtType (vl_msgpack *pack, vl_msgpack_iter iter)
	Retrieves the extension type of a MessagePack EXT node.

VL_API vl_msgpack_iter	vlMsgPackInsertExt (vl_msgpack pack, vl_msgpack_type type, vl_int8_t subType, vl_msgpack_iter parent, const void keyPtr, vl_memsize_t keyLen, const void *dataPtr, vl_memsize_t dataLen)
	Inserts a new element into the MessagePack DOM with an extended type.

VL_API void	vlMsgPackRemove (vl_msgpack *pack, vl_msgpack_iter iter)
	Removes an element from the MessagePack DOM.

VL_API vl_msgpack_iter	vlMsgPackFindChild (vl_msgpack pack, vl_msgpack_iter parent, const void key, vl_memsize_t keyLen)
	Finds a child element by key.

VL_API vl_msgpack_iter	vlMsgPackFindChildIndexed (vl_msgpack *pack, vl_msgpack_iter iter, vl_dsidx_t idx)
	Finds a child element by index.

VL_API const vl_transient *	vlMsgPackSampleKey (vl_msgpack pack, vl_msgpack_iter iter, vl_memsize_t size)
	Retrieves the key associated with an element.

VL_API vl_transient *	vlMsgPackSampleValue (vl_msgpack pack, vl_msgpack_iter iter, vl_memsize_t size)
	Retrieves the value associated with an element.

Data Structure Documentation

◆ vl_msgpack

struct vl_msgpack

MessagePack Document Object Model.

An in-memory, hierarchical representation of a complete MessagePack.

This structure represents an N-Tree with parent-child relationships that accurately represents a MessagePack structure. It is implemented using a hierarchical hash table for nodes and parent-child relationships, using a separate arena allocator for node values. Nodes in this structure are dynamically typed.

The design of this structure is NOT completely compliant with the MessagePack spec. It requires the two following rules to be enforced:

Elements in a Map must ALWAYS have String keys (e.g, named elements).
Elements in an Array must ALWAYS have Integer keys (e.g, indexed elements), although their keys are implicit. This design choice simplifies the implementation by disallowing complex structures such as Maps and Arrays to act as Map keys, keeping it in line with formats comparable to JSON.

All strings in and out of this structure, keys or values, are assumed to be UTF-8 encoded.

See also: https://github.com/msgpack/msgpack/blob/master/spec.md

Collaboration diagram for vl_msgpack:

Data Fields
vl_hashtable	nodes
vl_msgpack_iter	root
vl_arena	values

Macro Definition Documentation

◆ VL_MSGPACK_EXT_NONE

#define VL_MSGPACK_EXT_NONE -127

◆ VL_MSGPACK_FOREACH_CHILD

#define VL_MSGPACK_FOREACH_CHILD	(	packPtr,
		parentIter,
		childIterSymbol
	)

Value:

    for (vl_msgpack_iter childIterSymbol = vlMsgPackFirstChild((packPtr), (parentIter));                               \
         childIterSymbol != VL_MSGPACK_ITER_INVALID;                                                                   \
         childIterSymbol = vlMsgPackNextSibling((packPtr), (childIterSymbol)))

◆ VL_MSGPACK_ITER_INVALID

#define VL_MSGPACK_ITER_INVALID VL_HASHTABLE_ITER_INVALID

██ ██ ██ █████ ███████ █████ ██████ ███ ██ █████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ███████ ███████ ███████ ██ ███ ██ ██ ██ ███████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ███████ ██ ██ ███████ ██ ██ ██████ ██ ████ ██ ██ ====—: A Data Structure and Algorithms library for C11. :—====

◆ vlMsgPackRoot

#define vlMsgPackRoot ( packPtr ) ((packPtr)->root)

Macro to retrieve the root of the MessagePack DOM.

This macro provides access to the root node of the DOM. The root node is always a map.

Parameters

packPtr A pointer to the MessagePack DOM instance.

Returns: The root iterator of the MessagePack DOM.

Typedef Documentation

◆ vl_msgpack_iter

typedef vl_hash_iter vl_msgpack_iter

Enumeration Type Documentation

◆ vl_msgpack_type

enum vl_msgpack_type

All MessagePack Types.

Enumerator
VL_MSGPACK_NIL	MessagePack type equivalent to NIL. Has no data associated with it.
VL_MSGPACK_BOOL	MessagePack Boolean. Either True (1) or False (0).
VL_MSGPACK_INT	MessagePack Signed Integer. Implemented as vl_ilarge_t.
VL_MSGPACK_UINT	MessagePack Unsigned Integer. Implemented as vl_ularge_t.
VL_MSGPACK_FLOAT32	MessagePack 32-bit Float. Implemented as vl_float32_t.
VL_MSGPACK_FLOAT64	MessagePack 64-bit Float. Implemented as vl_float64_t.
VL_MSGPACK_STRING	MessagePack String. Must have UTF-8 encoding.
VL_MSGPACK_BINARY	MessagePack Binary. An arbitrary sequence of bytes with a well-defined length.
VL_MSGPACK_ARRAY	MessagePack Array. A sequence of dynamically-typed nodes of a well-determined length.
VL_MSGPACK_MAP	MessagePack Map. A collection of node key-value pairs of an arbitrary size.
VL_MSGPACK_EXT	MessagePack Extension Type. Has a type identifier in range of 0...127 and arbitrary data.

Function Documentation

◆ vlMsgPackClear()

VL_API void vlMsgPackClear ( vl_msgpack * pack )

Clears the MessagePack DOM, resetting it for reuse.

This function resets the MessagePack DOM instance without deallocating memory. Previously allocated memory remains available for reuse, improving performance when repeatedly decoding into the same structure.

Parameters

pack	The MessagePack DOM instance to clear.

Here is the call graph for this function:

◆ vlMsgPackClone()

VL_API vl_msgpack * vlMsgPackClone	(	vl_msgpack *	src,
		vl_msgpack *	dest
	)

Clones the specified MessagePack DOM to another.

Clones the entirety of the src MessagePack to the dest MessagePack.

The 'src' DOM must be non-null and initialized. The 'dest' DOM may be null, but if it is not null it must be initialized.

If the 'dest' table pointer is null, a new DOM is created via vlMsgPackNew.

See also: vlMsgPackNew

Parameters

src	source DOM pointer
dest	destination DOM pointer

Returns: pointer to the MessagePack that was copied to or created.

Here is the call graph for this function:

◆ vlMsgPackDelete()

VL_API void vlMsgPackDelete ( vl_msgpack * pack )

Deletes the specified MessagePack DOM.

The specified MessagePack must have been initialized via vlMsgPackNew before calling this function.

Contract

Ownership: Releases ownership and all associated resources.
Lifetime: The pack pointer becomes invalid.
Thread Safety: Not thread-safe.
Nullability: Safe to call with NULL (due to internal free safety).
Error Conditions: None.
Undefined Behavior: Double deletion.
Memory Allocation Expectations: Frees all heap memory associated with the DOM.
Return-value Semantics: None (void).

See also: vlMsgPackNew

Parameters

pack	pointer to DOM

Here is the call graph for this function:

◆ vlMsgPackExtType()

VL_API vl_int8_t vlMsgPackExtType	(	vl_msgpack *	pack,
		vl_msgpack_iter	iter
	)

Retrieves the extension type of a MessagePack EXT node.

Parameters

pack	The MessagePack DOM instance.
iter	The iterator pointing to the current node.

Returns: The extension type value, or an undefined result if the node is not an EXT type.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlMsgPackFindChild()

VL_API vl_msgpack_iter vlMsgPackFindChild	(	vl_msgpack *	pack,
		vl_msgpack_iter	parent,
		const void *	key,
		vl_memsize_t	keyLen
	)

Finds a child element by key.

This function searches for a child under the given parent node with a matching key.

Parameters

pack	The MessagePack DOM instance.
parent	The parent node to search in.
key	Pointer to the key data.
keyLen	Length of the key.

Returns: An iterator to the matching child or an invalid iterator if not found.

Here is the call graph for this function:

◆ vlMsgPackFindChildIndexed()

VL_API vl_msgpack_iter vlMsgPackFindChildIndexed	(	vl_msgpack *	pack,
		vl_msgpack_iter	iter,
		vl_dsidx_t	idx
	)

Finds a child element by index.

This function retrieves the indexed child from a parent container. The parent must be an array.

Parameters

pack	The MessagePack DOM instance.
iter	The parent node.
idx	The zero-based index of the child.

Returns: An iterator to the indexed child or an invalid iterator if out of bounds.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlMsgPackFirstChild()

VL_API vl_msgpack_iter vlMsgPackFirstChild	(	vl_msgpack *	pack,
		vl_msgpack_iter	iter
	)

Retrieves the first child of a given node.

Parameters

pack	The MessagePack DOM instance.
iter	The iterator pointing to the current node.

Returns: An iterator to the first child node, or an invalid iterator if there are no children.

Here is the call graph for this function:

◆ vlMsgPackFree()

VL_API void vlMsgPackFree ( vl_msgpack * pack )

Frees the specified MessagePack DOM.

The specified MessagePack must have been initialized via vlMsgPackInit before calling this function.

Contract

Ownership: Releases ownership of internal resources (hashtable, arena).
Lifetime: The pack structure remains but its internal data is invalid.
Thread Safety: Not thread-safe.
Nullability: pack must not be NULL.
Error Conditions: None.
Undefined Behavior: Passing NULL. Calling on a pack that was not initialized.
Memory Allocation Expectations: Deallocates internal hashtable and arena.
Return-value Semantics: None (void).

Parameters

pack	pointer to DOM

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlMsgPackInit()

VL_API void vlMsgPackInit ( vl_msgpack * pack )

Initializes the specified MessagePack DOM.

Contract

Ownership: The caller provides the pack memory.
Lifetime: The pack remains valid until vlMsgPackFree.
Thread Safety: Not thread-safe for the same pack instance.
Nullability: pack must not be NULL.
Error Conditions: None.
Undefined Behavior: Passing NULL. Initializing an already initialized pack without freeing it.
Memory Allocation Expectations: Allocates internal hashtable and arena structures.
Return-value Semantics: None (void).

See also: vlMsgPackInit

Parameters

pack	pointer to DOM

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlMsgPackInsertExt()

VL_API vl_msgpack_iter vlMsgPackInsertExt	(	vl_msgpack *	pack,
		vl_msgpack_type	type,
		vl_int8_t	subType,
		vl_msgpack_iter	parent,
		const void *	keyPtr,
		vl_memsize_t	keyLen,
		const void *	dataPtr,
		vl_memsize_t	dataLen
	)

Inserts a new element into the MessagePack DOM with an extended type.

This function inserts an element of the specified MessagePack type and optional extended type under a given parent node. The key and value are copied into the internal storage, allowing external memory to be safely freed after insertion.

Parameters

pack	The MessagePack DOM instance.
type	The type of the inserted element.
subType	The extended type (used for MessagePack ext types).
parent	The parent node where the element is inserted.
keyPtr	Pointer to the key data.
keyLen	Length of the key.
dataPtr	Pointer to the value data.
dataLen	Length of the value.

Returns: An iterator to the newly inserted element.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlMsgPackNew()

VL_API vl_msgpack * vlMsgPackNew ( void )

Allocates and initializes a MessagePack DOM.

The returned pointer is to be deleted via vlMsgPackDelete.

Contract

Ownership: The caller owns the returned vl_msgpack pointer and is responsible for calling vlMsgPackDelete.
Lifetime: The DOM remains valid until vlMsgPackDelete.
Thread Safety: This function is thread-safe (uses heap allocation).
Nullability: Returns NULL if allocation fails.
Error Conditions: Returns NULL on heap allocation failure.
Undefined Behavior: None.
Memory Allocation Expectations: Allocates the vl_msgpack structure and its internal data on the heap.
Return-value Semantics: Returns a pointer to the new DOM, or NULL on failure.

See also: vlMsgPackDelete

Returns: pointer to DOM

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlMsgPackNextSibling()

VL_API vl_msgpack_iter vlMsgPackNextSibling	(	vl_msgpack *	pack,
		vl_msgpack_iter	iter
	)

Retrieves the next sibling of a given node.

Parameters

pack	The MessagePack DOM instance.
iter	The iterator pointing to the current node.

Returns: An iterator to the next sibling node, or an invalid iterator if there is no next sibling.

Here is the call graph for this function:

◆ vlMsgPackParent()

VL_API vl_msgpack_iter vlMsgPackParent	(	vl_msgpack *	pack,
		vl_msgpack_iter	iter
	)

Retrieves the parent node of a given node in the MessagePack DOM.

Parameters

pack	The MessagePack DOM instance.
iter	The iterator pointing to the current node.

Returns: An iterator to the parent node, or an invalid iterator if the node has no parent.

Here is the call graph for this function:

◆ vlMsgPackPrevSibling()

VL_API vl_msgpack_iter vlMsgPackPrevSibling	(	vl_msgpack *	pack,
		vl_msgpack_iter	iter
	)

Retrieves the previous sibling of a given node.

Parameters

pack	The MessagePack DOM instance.
iter	The iterator pointing to the current node.

Returns: An iterator to the previous sibling node, or an invalid iterator if there is no previous sibling.

Here is the call graph for this function:

◆ vlMsgPackRemove()

VL_API void vlMsgPackRemove	(	vl_msgpack *	pack,
		vl_msgpack_iter	iter
	)

Removes an element from the MessagePack DOM.

This function removes the specified element and all its children from the DOM. Memory may be reused depending on the allocator's behavior.

Parameters

pack	The MessagePack DOM instance.
iter	Iterator pointing to the element to be removed.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlMsgPackSampleKey()

VL_API const vl_transient * vlMsgPackSampleKey	(	vl_msgpack *	pack,
		vl_msgpack_iter	iter,
		vl_memsize_t *	size
	)

Retrieves the key associated with an element.

This function returns a pointer to the key data of the given element. The key may move if modifications occur in the DOM, so users should not store this pointer for long-term access.

Parameters

pack	The MessagePack DOM instance.
iter	The element iterator.
size	Pointer to receive the key size (optional, can be NULL).

Returns: A transient pointer to the key data.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlMsgPackSampleValue()

VL_API vl_transient * vlMsgPackSampleValue	(	vl_msgpack *	pack,
		vl_msgpack_iter	iter,
		vl_memsize_t *	size
	)

Retrieves the value associated with an element.

This function returns a pointer to the value data of the given element. The value may move if modifications occur in the DOM, so users should not store this pointer for long-term access.

Parameters

pack	The MessagePack DOM instance.
iter	The element iterator.
size	Pointer to receive the value size (optional, can be NULL).

Returns: A transient pointer to the value data.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vlMsgPackTotalChildren()

VL_API vl_dsidx_t vlMsgPackTotalChildren	(	vl_msgpack *	pack,
		vl_msgpack_iter	iter
	)

Retrieves the total number of children of a given node.

Parameters

pack	The MessagePack DOM instance.
iter	The iterator pointing to the current node.

Returns: The number of child nodes.

Here is the call graph for this function:

◆ vlMsgPackType()

VL_API vl_msgpack_type vlMsgPackType	(	vl_msgpack *	pack,
		vl_msgpack_iter	iter
	)

Retrieves the type of a given node in the MessagePack DOM.

Parameters

pack	The MessagePack DOM instance.
iter	The iterator pointing to the current node.

Returns: The MessagePack type of the node.

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

◆ vl_msgpack

Macro Definition Documentation

◆ VL_MSGPACK_EXT_NONE

◆ VL_MSGPACK_FOREACH_CHILD

◆ VL_MSGPACK_ITER_INVALID

◆ vlMsgPackRoot

Typedef Documentation

◆ vl_msgpack_iter

Enumeration Type Documentation

◆ vl_msgpack_type

Function Documentation

◆ vlMsgPackClear()

◆ vlMsgPackClone()

◆ vlMsgPackDelete()

Contract

◆ vlMsgPackExtType()

◆ vlMsgPackFindChild()

◆ vlMsgPackFindChildIndexed()

◆ vlMsgPackFirstChild()

◆ vlMsgPackFree()

Contract

◆ vlMsgPackInit()

Contract

◆ vlMsgPackInsertExt()

◆ vlMsgPackNew()

Contract

◆ vlMsgPackNextSibling()

◆ vlMsgPackParent()

◆ vlMsgPackPrevSibling()

◆ vlMsgPackRemove()

◆ vlMsgPackSampleKey()

◆ vlMsgPackSampleValue()

◆ vlMsgPackTotalChildren()

◆ vlMsgPackType()