Generic sets

Data Structures
struct	ly_set
	Structure to hold a set of (not necessary somehow connected) objects. Usually used for lyd_node, lysp_node or lysc_node objects, but it is not limited to them. Caller is supposed to not mix the type of objects added to the set and according to its knowledge about the set content, it can access objects via the members of the set union. More...
union	ly_set.__unnamed__

Functions
LIBYANG_API_DECL LY_ERR	ly_set_add (struct ly_set *set, const void *object, ly_bool list, uint32_t *index_p)
	Add an object into the set. More...
LIBYANG_API_DECL void	ly_set_clean (struct ly_set *set, void(*destructor)(void *obj))
	Remove all objects from the set, but keep the set container for further use. More...
LIBYANG_API_DECL ly_bool	ly_set_contains (const struct ly_set *set, const void *object, uint32_t *index_p)
	Learn whether the set contains the specified object. More...
LIBYANG_API_DECL LY_ERR	ly_set_dup (const struct ly_set *set, void *(*duplicator)(const void *obj), struct ly_set **newset_p)
	Duplicate the existing set. More...
LIBYANG_API_DECL void	ly_set_erase (struct ly_set *set, void(*destructor)(void *obj))
	Alternative to the ly_set_free() for static ly_set objects - in contrast to ly_set_free() it does not free the provided ly_set object. More...
LIBYANG_API_DECL void	ly_set_free (struct ly_set *set, void(*destructor)(void *obj))
	Free the ly_set data. If the destructor is not provided, it frees only the set structure content, not the referred data. More...
LIBYANG_API_DECL LY_ERR	ly_set_merge (struct ly_set *trg, const struct ly_set *src, ly_bool list, void *(*duplicator)(const void *obj))
	Add all objects from src to trg. More...
LIBYANG_API_DECL LY_ERR	ly_set_new (struct ly_set **set_p)
	Create and initiate new ly_set structure. More...
LIBYANG_API_DECL LY_ERR	ly_set_rm (struct ly_set *set, void *object, void(*destructor)(void *obj))
	Remove an object from the set. More...
LIBYANG_API_DECL LY_ERR	ly_set_rm_index (struct ly_set *set, uint32_t index, void(*destructor)(void *obj))
	Remove an object on the specific set index. More...
LIBYANG_API_DECL LY_ERR	ly_set_rm_index_ordered (struct ly_set *set, uint32_t index, void(*destructor)(void *obj))
	Remove an object on the specific set index. More...

Detailed Description

Structure and functions to hold and manipulate with sets of nodes from schema or data trees.

---

Data Structure Documentation

struct ly_set

Structure to hold a set of (not necessary somehow connected) objects. Usually used for lyd_node, lysp_node or lysc_node objects, but it is not limited to them. Caller is supposed to not mix the type of objects added to the set and according to its knowledge about the set content, it can access objects via the members of the set union.

Until ly_set_rm() or ly_set_rm_index() is used, the set keeps the order of the inserted items as they were added into the set, so the first added item is on array index 0.

To free the structure, use ly_set_free() function, to manipulate with the structure, use other ly_set_* functions.

Definition at line 47 of file set.h.

Data Fields
union ly_set	__unnamed__
uint32_t	count	number of elements in (used size of) the set array
uint32_t	size	allocated size of the set array

union ly_set.__unnamed__

Definition at line 51 of file set.h.

Data Fields
struct lyd_node **	dnodes	set array of data nodes
void **	objs	set array of generic object pointers
struct lysc_node **	snodes	set array of schema nodes

Function Documentation

LIBYANG_API_DECL LY_ERR ly_set_add	(	struct ly_set *	set,
		const void *	object,
		ly_bool	list,
		uint32_t *	index_p
	)

Add an object into the set.

Parameters

[in]	set	Set where the object will be added.
[in]	object	Object to be added into the set;
[in]	list	flag to handle set as a list (without checking for (ignoring) duplicit items)
[out]	index_p	Optional pointer to return index of the added object. Usually it is the last index (ly_set::count - 1), but in case the duplicities are checked and the object is already in the set, the object is not added and index of the already present object is returned.

Returns

LY_SUCCESS in case of success

LY_EINVAL in case of invalid input parameters.

LY_EMEM in case of memory allocation failure.

LIBYANG_API_DECL void ly_set_clean	(	struct ly_set *	set,
		void(*)(void *obj)	destructor
	)

Remove all objects from the set, but keep the set container for further use.

Parameters

[in]	set	Set to clean.
[in]	destructor	Optional function to free the objects in the set.

LIBYANG_API_DECL ly_bool ly_set_contains	(	const struct ly_set *	set,
		const void *	object,
		uint32_t *	index_p
	)

Learn whether the set contains the specified object.

Parameters

[in]	set	Set to explore.
[in]	object	Object to be found in the set.
[out]	index_p	Optional pointer to return index of the searched object.

Returns

Boolean value whether the object was found in the set.

LIBYANG_API_DECL LY_ERR ly_set_dup	(	const struct ly_set *	set,
		void *(*)(const void *obj)	duplicator,
		struct ly_set **	newset_p
	)

Duplicate the existing set.

Parameters

[in]	set	Original set to duplicate
[in]	duplicator	Optional pointer to function that duplicates the objects stored in the original set. If not provided, the new set points to the exact same objects as the original set.
[out]	newset_p	Pointer to return the duplication of the original set.

Returns

LY_SUCCESS in case the data were successfully duplicated.

LY_EMEM in case of memory allocation failure.

LY_EINVAL in case of invalid parameters.

LIBYANG_API_DECL void ly_set_erase	(	struct ly_set *	set,
		void(*)(void *obj)	destructor
	)

Alternative to the ly_set_free() for static ly_set objects - in contrast to ly_set_free() it does not free the provided ly_set object.

Parameters

[in]	set	The set to be erased.
[in]	destructor	Optional function to free the objects in the set.

LIBYANG_API_DECL void ly_set_free	(	struct ly_set *	set,
		void(*)(void *obj)	destructor
	)

Free the ly_set data. If the destructor is not provided, it frees only the set structure content, not the referred data.

Parameters

[in]	set	The set to be freed.
[in]	destructor	Optional function to free the objects in the set.

LIBYANG_API_DECL LY_ERR ly_set_merge	(	struct ly_set *	trg,
		const struct ly_set *	src,
		ly_bool	list,
		void *(*)(const void *obj)	duplicator
	)

Add all objects from src to trg.

Since it is a set, the function checks for duplicities.

Parameters

[in]	trg	Target (result) set.
[in]	src	Source set.
[in]	list	flag to handle set as a list (without checking for (ignoring) duplicit items)
[in]	duplicator	Optional pointer to function that duplicates the objects being added from src into trg set. If not provided, the trg set will point to the exact same objects as the src set.

Returns

LY_SUCCESS in case of success

LY_EINVAL in case of invalid input parameters.

LY_EMEM in case of memory allocation failure.

LIBYANG_API_DECL LY_ERR ly_set_new

(

struct ly_set **

set_p

)

Create and initiate new ly_set structure.

Parameters

[out]

set_p

Pointer to store the created ly_set structure.

Returns

LY_SUCCESS on success.

LY_EINVAL in case of NULL set parameter.

LY_EMEM in case of memory allocation failure.

LIBYANG_API_DECL LY_ERR ly_set_rm	(	struct ly_set *	set,
		void *	object,
		void(*)(void *obj)	destructor
	)

Remove an object from the set.

Note that after removing the object from a set, indexes of other objects in the set can change (the last object is placed instead of the removed object).

Parameters

[in]	set	Set from which to remove.
[in]	object	The object to be removed from the set.
[in]	destructor	Optional function to free the objects being removed.

Returns

LY_ERR return value.

LIBYANG_API_DECL LY_ERR ly_set_rm_index	(	struct ly_set *	set,
		uint32_t	index,
		void(*)(void *obj)	destructor
	)

Remove an object on the specific set index.

Note that after removing the object from a set, indexes of other nodes in the set can change (the last object is placed instead of the removed object).

Parameters

[in]	set	Set from which to remove.
[in]	index	Index of the object to remove in the set.
[in]	destructor	Optional function to free the objects being removed.

Returns

LY_ERR return value.

LIBYANG_API_DECL LY_ERR ly_set_rm_index_ordered	(	struct ly_set *	set,
		uint32_t	index,
		void(*)(void *obj)	destructor
	)

Remove an object on the specific set index.

Unlike ly_set_rm_index(), this function moves all the items following the removed one.

Parameters

[in]	set	Set from which to remove.
[in]	index	Index of the object to remove in the set.
[in]	destructor	Optional function to free the objects being removed.

Returns

LY_ERR return value.