Buffer API

Buffer API. More...

Modules
	Object / Array Initialization
	Object / array initialization.
	Object Set
	Set key-value pair in object.
	Array Append
	Append value to array.
	Array Set
	Set value in array.
	Utility Functions
	Utility functions.
	Object Get
	Get value from object by key.
	Array Get
	Get value from array by index.
	Iterators
	Create and use iterators for objects/arrays.
	JSON Conversion
	Conversion between Lite³ and JSON.

Detailed Description

Buffer API.

Functions in the Buffer API use caller-provided buffers. Some scenarios where this is useful:

1. the user points to a buffer and Lite³ serializes directly into it;
2. the user points to an existing Lite³ message to perform lookups, iterators or mutations on it directly;
3. the user does not tolerate unexpected latency variations from automatic memory management / reallocation.

Overall, maximum control is given to the user. This also means it is the user's responsibility to allocate enough memory, and retry if necessary.

All functions include handles for proper retry logic. When a mutation fails because of insufficient buffer space, the function will return -1 and set errno to the ENOBUFS signal. After this, the caller can allocate more space and try again.

Note

If you are using Lite³ for the first time, it is recommended to start with the Context API. This API represents a more accessible alternative where memory allocations are hidden from the user, providing all the same functionality without requiring manual buffer management.

Error handling

Unless otherwise specified, Lite³ uses the POSIX error handling convention. This means functions will return a value of -1 and set errno to one of several values:

Err	Hex	Var	Description
2	0x02	ENOENT	No such file or directory
5	0x05	EIO	Input/output error
14	0x0e	EFAULT	Bad address
22	0x16	EINVAL	Invalid argument
74	0x4a	EBADMSG	Bad message
75	0x4b	EOVERFLOW	Value too large for defined data type
90	0x5a	EMSGSIZE	Message too long
105	0x69	ENOBUFS	No buffer space available

Used feature breaking ANSI-C / C89 compatibility:

C99:

• inline functions
• compound literals
• flexible array member (no specified size)
• single-line comments //
• variadic macros (VA_ARGS)
• restrict pointers
  
• initializing a structure by field names: struct Point p = { .x = 1, .y = 2 };

C11:

• static_assert