blob: a733d237886182b27fc727d03424edbaffe3714a [file] [log] [blame]
Radek Krejci5aeea3a2018-09-05 13:29:36 +02001/**
2 * @file set.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
Michal Vasko534eb3f2023-10-13 09:28:53 +02004 * @author Michal Vasko <mvasko@cesnet.cz>
Radek Krejci5aeea3a2018-09-05 13:29:36 +02005 * @brief Generic set structure and manipulation routines.
6 *
Michal Vasko534eb3f2023-10-13 09:28:53 +02007 * Copyright (c) 2015 - 2023 CESNET, z.s.p.o.
Radek Krejci5aeea3a2018-09-05 13:29:36 +02008 *
9 * This source code is licensed under BSD 3-Clause License (the "License").
10 * You may not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
12 *
13 * https://opensource.org/licenses/BSD-3-Clause
14 */
15
16#ifndef LY_SET_H_
17#define LY_SET_H_
18
Michal Vasko52927e22020-03-16 17:26:14 +010019#include <stdint.h>
20
Radek Krejcie7b95092019-05-15 11:03:07 +020021#include "log.h"
22
Radek Krejci5aeea3a2018-09-05 13:29:36 +020023#ifdef __cplusplus
24extern "C" {
25#endif
26
27/**
28 * @defgroup lyset Generic sets
29 *
30 * Structure and functions to hold and manipulate with sets of nodes from schema or data trees.
31 *
32 * @{
33 */
34
35/**
Radek Krejci59583bb2019-09-11 12:57:55 +020036 * @brief Structure to hold a set of (not necessary somehow connected) objects. Usually used for lyd_node,
Radek Krejcie53a8dc2018-10-17 12:52:40 +020037 * ::lysp_node or ::lysc_node objects, but it is not limited to them. Caller is supposed to not mix the type of objects
Radek Krejci5aeea3a2018-09-05 13:29:36 +020038 * added to the set and according to its knowledge about the set content, it can access objects via the members
39 * of the set union.
40 *
Radek Krejci8678fa42020-08-18 16:07:28 +020041 * Until ::ly_set_rm() or ::ly_set_rm_index() is used, the set keeps the order of the inserted items as they
Radek Krejci5aeea3a2018-09-05 13:29:36 +020042 * were added into the set, so the first added item is on array index 0.
43 *
Radek Krejci8678fa42020-08-18 16:07:28 +020044 * To free the structure, use ::ly_set_free() function, to manipulate with the structure, use other
Radek Krejci5aeea3a2018-09-05 13:29:36 +020045 * ly_set_* functions.
46 */
Michal Vasko87f1cf02021-06-08 14:02:47 +020047struct ly_set {
Michal Vasko52927e22020-03-16 17:26:14 +010048 uint32_t size; /**< allocated size of the set array */
49 uint32_t count; /**< number of elements in (used size of) the set array */
Michal Vasko26bbb272022-08-02 14:54:33 +020050
Michal Vasko0c03f142020-08-11 10:36:13 +020051 union {
52 struct lyd_node **dnodes; /**< set array of data nodes */
53 struct lysc_node **snodes; /**< set array of schema nodes */
54 void **objs; /**< set array of generic object pointers */
55 };
Radek Krejci5aeea3a2018-09-05 13:29:36 +020056};
57
58/**
Radek Krejci5aeea3a2018-09-05 13:29:36 +020059 * @brief Create and initiate new ::ly_set structure.
60 *
Radek Krejci8678fa42020-08-18 16:07:28 +020061 * @param[out] set_p Pointer to store the created ::ly_set structure.
Radek Krejciba03a5a2020-08-27 14:40:41 +020062 * @return LY_SUCCESS on success.
63 * @return LY_EINVAL in case of NULL @p set parameter.
64 * @return LY_EMEM in case of memory allocation failure.
Radek Krejci5aeea3a2018-09-05 13:29:36 +020065 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +010066LIBYANG_API_DECL LY_ERR ly_set_new(struct ly_set **set_p);
Radek Krejci5aeea3a2018-09-05 13:29:36 +020067
68/**
69 * @brief Duplicate the existing set.
70 *
71 * @param[in] set Original set to duplicate
Radek Krejci2f2bd902018-09-18 17:04:24 +020072 * @param[in] duplicator Optional pointer to function that duplicates the objects stored
73 * in the original set. If not provided, the new set points to the exact same objects as
74 * the original set.
Radek Krejci8678fa42020-08-18 16:07:28 +020075 * @param[out] newset_p Pointer to return the duplication of the original set.
76 * @return LY_SUCCESS in case the data were successfully duplicated.
77 * @return LY_EMEM in case of memory allocation failure.
78 * @return LY_EINVAL in case of invalid parameters.
Radek Krejci5aeea3a2018-09-05 13:29:36 +020079 */
Michal Vasko193dacd2022-10-13 08:43:05 +020080LIBYANG_API_DECL LY_ERR ly_set_dup(const struct ly_set *set, void *(*duplicator)(const void *obj), struct ly_set **newset_p);
Radek Krejci5aeea3a2018-09-05 13:29:36 +020081
82/**
Radek Krejcie53a8dc2018-10-17 12:52:40 +020083 * @brief Add an object into the set
Radek Krejci5aeea3a2018-09-05 13:29:36 +020084 *
Michal Vasko534eb3f2023-10-13 09:28:53 +020085 * @param[in] set Set where the @p object will be added.
86 * @param[in] object Object to be added into the @p set;
Radek Krejci3d92e442020-10-12 12:48:13 +020087 * @param[in] list flag to handle set as a list (without checking for (ignoring) duplicit items)
Radek Krejciba03a5a2020-08-27 14:40:41 +020088 * @param[out] index_p Optional pointer to return index of the added @p object. Usually it is the last index (::ly_set::count - 1),
89 * but in case the duplicities are checked and the object is already in the set, the @p object is not added and index of the
90 * already present object is returned.
91 * @return LY_SUCCESS in case of success
92 * @return LY_EINVAL in case of invalid input parameters.
93 * @return LY_EMEM in case of memory allocation failure.
Radek Krejci5aeea3a2018-09-05 13:29:36 +020094 */
Michal Vasko193dacd2022-10-13 08:43:05 +020095LIBYANG_API_DECL LY_ERR ly_set_add(struct ly_set *set, const void *object, ly_bool list, uint32_t *index_p);
Radek Krejci5aeea3a2018-09-05 13:29:36 +020096
97/**
Michal Vasko534eb3f2023-10-13 09:28:53 +020098 * @brief Add all objects from @p src to @p trg.
Radek Krejci5aeea3a2018-09-05 13:29:36 +020099 *
100 * Since it is a set, the function checks for duplicities.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200101 *
102 * @param[in] trg Target (result) set.
103 * @param[in] src Source set.
Radek Krejci52ca92d2020-10-12 16:51:22 +0200104 * @param[in] list flag to handle set as a list (without checking for (ignoring) duplicit items)
Radek Krejci2f2bd902018-09-18 17:04:24 +0200105 * @param[in] duplicator Optional pointer to function that duplicates the objects being added
Michal Vasko534eb3f2023-10-13 09:28:53 +0200106 * from @p src into @p trg set. If not provided, the @p trg set will point to the exact same
107 * objects as the @p src set.
Radek Krejciba03a5a2020-08-27 14:40:41 +0200108 * @return LY_SUCCESS in case of success
109 * @return LY_EINVAL in case of invalid input parameters.
110 * @return LY_EMEM in case of memory allocation failure.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200111 */
Michal Vasko193dacd2022-10-13 08:43:05 +0200112LIBYANG_API_DECL LY_ERR ly_set_merge(struct ly_set *trg, const struct ly_set *src, ly_bool list, void *(*duplicator)(const void *obj));
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200113
114/**
Michal Vasko52927e22020-03-16 17:26:14 +0100115 * @brief Learn whether the set contains the specified object.
116 *
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200117 * @param[in] set Set to explore.
118 * @param[in] object Object to be found in the set.
Radek Krejciba03a5a2020-08-27 14:40:41 +0200119 * @param[out] index_p Optional pointer to return index of the searched @p object.
Radek Krejci857189e2020-09-01 13:26:36 +0200120 * @return Boolean value whether the @p object was found in the @p set.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200121 */
Michal Vasko193dacd2022-10-13 08:43:05 +0200122LIBYANG_API_DECL ly_bool ly_set_contains(const struct ly_set *set, const void *object, uint32_t *index_p);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200123
124/**
125 * @brief Remove all objects from the set, but keep the set container for further use.
126 *
127 * @param[in] set Set to clean.
Radek Krejcia40f21b2018-09-18 10:42:08 +0200128 * @param[in] destructor Optional function to free the objects in the set.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200129 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100130LIBYANG_API_DECL void ly_set_clean(struct ly_set *set, void (*destructor)(void *obj));
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200131
132/**
133 * @brief Remove an object from the set.
134 *
135 * Note that after removing the object from a set, indexes of other objects in the set can change
136 * (the last object is placed instead of the removed object).
137 *
Michal Vasko534eb3f2023-10-13 09:28:53 +0200138 * @param[in] set Set from which to remove.
139 * @param[in] object The object to be removed from the @p set.
Radek Krejci820d2262018-09-20 12:15:31 +0200140 * @param[in] destructor Optional function to free the objects being removed.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200141 * @return LY_ERR return value.
142 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100143LIBYANG_API_DECL LY_ERR ly_set_rm(struct ly_set *set, void *object, void (*destructor)(void *obj));
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200144
145/**
146 * @brief Remove an object on the specific set index.
147 *
148 * Note that after removing the object from a set, indexes of other nodes in the set can change
149 * (the last object is placed instead of the removed object).
150 *
Michal Vasko534eb3f2023-10-13 09:28:53 +0200151 * @param[in] set Set from which to remove.
152 * @param[in] index Index of the object to remove in the @p set.
Radek Krejci820d2262018-09-20 12:15:31 +0200153 * @param[in] destructor Optional function to free the objects being removed.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200154 * @return LY_ERR return value.
155 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100156LIBYANG_API_DECL LY_ERR ly_set_rm_index(struct ly_set *set, uint32_t index, void (*destructor)(void *obj));
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200157
158/**
Michal Vasko534eb3f2023-10-13 09:28:53 +0200159 * @brief Remove an object on the specific set index.
160 *
Michal Vasko2c1f66d2024-01-22 14:36:13 +0100161 * Unlike ::ly_set_rm_index(), this function moves all the items following the removed one.
Michal Vasko534eb3f2023-10-13 09:28:53 +0200162 *
163 * @param[in] set Set from which to remove.
164 * @param[in] index Index of the object to remove in the @p set.
165 * @param[in] destructor Optional function to free the objects being removed.
166 * @return LY_ERR return value.
167 */
168LIBYANG_API_DECL LY_ERR ly_set_rm_index_ordered(struct ly_set *set, uint32_t index, void (*destructor)(void *obj));
169
170/**
Radek Krejcia40f21b2018-09-18 10:42:08 +0200171 * @brief Free the ::ly_set data. If the destructor is not provided, it frees only the set structure
172 * content, not the referred data.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200173 *
174 * @param[in] set The set to be freed.
Radek Krejcia40f21b2018-09-18 10:42:08 +0200175 * @param[in] destructor Optional function to free the objects in the set.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200176 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100177LIBYANG_API_DECL void ly_set_free(struct ly_set *set, void (*destructor)(void *obj));
Radek Krejcia40f21b2018-09-18 10:42:08 +0200178
179/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200180 * @brief Alternative to the ::ly_set_free() for static ::ly_set objects - in contrast to ::ly_set_free()
Radek Krejcia40f21b2018-09-18 10:42:08 +0200181 * it does not free the provided ::ly_set object.
182 *
183 * @param[in] set The set to be erased.
184 * @param[in] destructor Optional function to free the objects in the set.
185 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100186LIBYANG_API_DECL void ly_set_erase(struct ly_set *set, void (*destructor)(void *obj));
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200187
188/** @} lyset */
189
190#ifdef __cplusplus
191}
192#endif
193
194#endif /* LY_SET_H_ */