Iterators

Create and use iterators for objects/arrays. More...

Data Structures
struct	lite3_iter
	Struct containing iterator state. More...

Macros
#define	LITE3_ITER_ITEM
	Return value of lite3_iter_next(); iterator produced an item, continue;.
#define	LITE3_ITER_DONE
	Return value of lite3_iter_next(); iterator finished; stop.

Functions
static int	lite3_iter_create (const unsigned char *buf, size_t buflen, size_t ofs, lite3_iter *out)
	Create a lite3 iterator for the given object or array.
int	lite3_iter_next (const unsigned char *buf, size_t buflen, lite3_iter *iter, lite3_str *out_key, size_t *out_val_ofs)
	Get the next item from a lite3 iterator.

Detailed Description

Create and use iterators for objects/arrays.

Iter functions read buflen to know the currently used portion of the buffer.

The ofs (offset) field is used to target an object or array inside the Lite³ buffer. To target the root-level object/array, use ofs == 0.

Warning

Read-only operations are thread-safe. This includes all iterator funtions. Mixing reads and writes however is not thread-safe.

Macro Definition Documentation

LITE3_ITER_DONE

#define LITE3_ITER_DONE

Return value of lite3_iter_next(); iterator finished; stop.

Definition at line 2618 of file lite3.h.

LITE3_ITER_ITEM

#define LITE3_ITER_ITEM

Return value of lite3_iter_next(); iterator produced an item, continue;.

Definition at line 2616 of file lite3.h.

Function Documentation

lite3_iter_create()

static int lite3_iter_create ( const unsigned char *  buf, size_t  buflen, size_t  ofs, lite3_iter *  out  )

inlinestatic

Create a lite3 iterator for the given object or array.

Returns

0 on success

< 0 on error

Parameters

[in]	buf	buffer pointer
[in]	buflen	buffer used length
[in]	ofs	start offset (0 == root)
[out]	out	iterator struct pointer

Definition at line 2644 of file lite3.h.

lite3_iter_next()

int lite3_iter_next	(	const unsigned char *	buf,
		size_t	buflen,
		lite3_iter *	iter,
		lite3_str *	out_key,
		size_t *	out_val_ofs
	)

Get the next item from a lite3 iterator.

To use in conjunctions with lite3_val functions, the *out_val_ofs can be casted to (lite3_val *).

Returns

LITE3_ITER_ITEM (== 1) on item produced

LITE3_ITER_DONE (== 0) on success (no more items)

< 0 on error

Note

If the user does not want a key or value, simply pass NULL. For array iterators, out_key should always be passed as NULL.

Warning

Iterators are read-only. Any attempt to write to the buffer using lite3_set_xxxx() will immediately invalidate the iterator. If you need to make changes to the buffer, first prepare your changes, then apply them afterwards in one batch.

Parameters

[in]	buf	buffer pointer
[in]	buflen	buffer used length
[in]	iter	iterator struct pointer
[out]	out_key	current key (if not needed, pass NULL)
[out]	out_val_ofs	current value offset (if not needed, pass NULL)

Definition at line 333 of file lite3.c.