blob: 915e91e0d2cacc8bd6799700781d2609341e5fa1 [file] [log] [blame]
Radek Krejci5aeea3a2018-09-05 13:29:36 +02001/**
2 * @file set.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief Generic set structure and manipulation routines.
5 *
6 * Copyright (c) 2015 - 2018 CESNET, z.s.p.o.
7 *
8 * This source code is licensed under BSD 3-Clause License (the "License").
9 * You may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
11 *
12 * https://opensource.org/licenses/BSD-3-Clause
13 */
14
15#ifndef LY_SET_H_
16#define LY_SET_H_
17
Radek Krejcie7b95092019-05-15 11:03:07 +020018#include "log.h"
19
Radek Krejci5aeea3a2018-09-05 13:29:36 +020020#ifdef __cplusplus
21extern "C" {
22#endif
23
24/**
25 * @defgroup lyset Generic sets
26 *
27 * Structure and functions to hold and manipulate with sets of nodes from schema or data trees.
28 *
29 * @{
30 */
31
32/**
Radek Krejci59583bb2019-09-11 12:57:55 +020033 * @brief Structure to hold a set of (not necessary somehow connected) objects. Usually used for lyd_node,
Radek Krejcie53a8dc2018-10-17 12:52:40 +020034 * ::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 +020035 * added to the set and according to its knowledge about the set content, it can access objects via the members
36 * of the set union.
37 *
38 * Until ly_set_rm() or ly_set_rm_index() is used, the set keeps the order of the inserted items as they
39 * were added into the set, so the first added item is on array index 0.
40 *
41 * To free the structure, use ly_set_free() function, to manipulate with the structure, use other
42 * ly_set_* functions.
43 */
44struct ly_set
45{
46 unsigned int size; /**< allocated size of the set array */
Michal Vaskob34480a2018-09-17 10:34:45 +020047 unsigned int count; /**< number of elements in (used size of) the set array */
Radek Krejcie53a8dc2018-10-17 12:52:40 +020048 void **objs; /**< set array of generic object pointers */
Radek Krejci5aeea3a2018-09-05 13:29:36 +020049};
50
51/**
52 * @brief Option for ly_set_add() to allow duplicities in the ly_set structure so the
53 * set is not used as a set, but as a list of (container for) items.
54 */
55#define LY_SET_OPT_USEASLIST 0x01
56
57/**
58 * @brief Create and initiate new ::ly_set structure.
59 *
60 * @return Created ::ly_set structure or NULL in case of error.
61 */
Michal Vaskob34480a2018-09-17 10:34:45 +020062struct ly_set *ly_set_new(void);
Radek Krejci5aeea3a2018-09-05 13:29:36 +020063
64/**
65 * @brief Duplicate the existing set.
66 *
67 * @param[in] set Original set to duplicate
Radek Krejci2f2bd902018-09-18 17:04:24 +020068 * @param[in] duplicator Optional pointer to function that duplicates the objects stored
69 * in the original set. If not provided, the new set points to the exact same objects as
70 * the original set.
Radek Krejci5aeea3a2018-09-05 13:29:36 +020071 * @return Duplication of the original set.
72 */
Radek Krejci2f2bd902018-09-18 17:04:24 +020073struct ly_set *ly_set_dup(const struct ly_set *set, void *(*duplicator)(void *obj));
Radek Krejci5aeea3a2018-09-05 13:29:36 +020074
75/**
Radek Krejcie53a8dc2018-10-17 12:52:40 +020076 * @brief Add an object into the set
Radek Krejci5aeea3a2018-09-05 13:29:36 +020077 *
78 * Since it is a set, the function checks for duplicity and if the
79 * node is already in the set, the index of the previously added
80 * node is returned.
81 *
82 * @param[in] set Set where the \p object will be added.
83 * @param[in] object Object to be added into the \p set;
84 * @param[in] options Options to change behavior of the function. Accepted options are:
85 * - #LY_SET_OPT_USEASLIST - do not check for duplicities
86 * @return -1 on failure, index of the \p node in the set on success
87 */
Michal Vaskob34480a2018-09-17 10:34:45 +020088int ly_set_add(struct ly_set *set, void *object, int options);
Radek Krejci5aeea3a2018-09-05 13:29:36 +020089
90/**
91 * @brief Add all objects from \p src to \p trg.
92 *
93 * Since it is a set, the function checks for duplicities.
Radek Krejci5aeea3a2018-09-05 13:29:36 +020094 *
95 * @param[in] trg Target (result) set.
96 * @param[in] src Source set.
97 * @param[in] options Options to change behavior of the function. Accepted options are:
Radek Krejci2f2bd902018-09-18 17:04:24 +020098 * - #LY_SET_OPT_USEASLIST - add without checking for duplicities
99 * @param[in] duplicator Optional pointer to function that duplicates the objects being added
100 * from \p src into \p trg set. If not provided, the \p trg set will point to the exact same
101 * objects as the \p src set.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200102 * @return -1 on failure, number of objects added into \p trg on success.
103 */
Radek Krejci2f2bd902018-09-18 17:04:24 +0200104int ly_set_merge(struct ly_set *trg, struct ly_set *src, int options, void *(*duplicator)(void *obj));
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200105
106/**
107 * @brief Get know if the set contains the specified object.
108 * @param[in] set Set to explore.
109 * @param[in] object Object to be found in the set.
110 * @return Index of the object in the set or -1 if the object is not present in the set.
111 */
Michal Vaskob34480a2018-09-17 10:34:45 +0200112int ly_set_contains(const struct ly_set *set, void *object);
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200113
114/**
115 * @brief Remove all objects from the set, but keep the set container for further use.
116 *
117 * @param[in] set Set to clean.
Radek Krejcia40f21b2018-09-18 10:42:08 +0200118 * @param[in] destructor Optional function to free the objects in the set.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200119 */
Radek Krejcia40f21b2018-09-18 10:42:08 +0200120void ly_set_clean(struct ly_set *set, void (*destructor)(void *obj));
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200121
122/**
123 * @brief Remove an object from the set.
124 *
125 * Note that after removing the object from a set, indexes of other objects in the set can change
126 * (the last object is placed instead of the removed object).
127 *
128 * @param[in] set Set from which the \p node will be removed.
Radek Krejcie53a8dc2018-10-17 12:52:40 +0200129 * @param[in] object The object to be removed from the \p set.
Radek Krejci820d2262018-09-20 12:15:31 +0200130 * @param[in] destructor Optional function to free the objects being removed.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200131 * @return LY_ERR return value.
132 */
Radek Krejci820d2262018-09-20 12:15:31 +0200133LY_ERR ly_set_rm(struct ly_set *set, void *object, void (*destructor)(void *obj));
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200134
135/**
136 * @brief Remove an object on the specific set index.
137 *
138 * Note that after removing the object from a set, indexes of other nodes in the set can change
139 * (the last object is placed instead of the removed object).
140 *
141 * @param[in] set Set from which a node will be removed.
142 * @param[in] index Index of the object to remove in the \p set.
Radek Krejci820d2262018-09-20 12:15:31 +0200143 * @param[in] destructor Optional function to free the objects being removed.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200144 * @return LY_ERR return value.
145 */
Radek Krejci820d2262018-09-20 12:15:31 +0200146LY_ERR ly_set_rm_index(struct ly_set *set, unsigned int index, void (*destructor)(void *obj));
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200147
148/**
Radek Krejcia40f21b2018-09-18 10:42:08 +0200149 * @brief Free the ::ly_set data. If the destructor is not provided, it frees only the set structure
150 * content, not the referred data.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200151 *
152 * @param[in] set The set to be freed.
Radek Krejcia40f21b2018-09-18 10:42:08 +0200153 * @param[in] destructor Optional function to free the objects in the set.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200154 */
Radek Krejcia40f21b2018-09-18 10:42:08 +0200155void ly_set_free(struct ly_set *set, void (*destructor)(void *obj));
156
157/**
158 * @brief Alternative to the ly_set_free() for static ::ly_set objects - in contrast to ly_set_free()
159 * it does not free the provided ::ly_set object.
160 *
161 * @param[in] set The set to be erased.
162 * @param[in] destructor Optional function to free the objects in the set.
163 */
164void ly_set_erase(struct ly_set *set, void (*destructor)(void *obj));
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200165
166/** @} lyset */
167
168#ifdef __cplusplus
169}
170#endif
171
172#endif /* LY_SET_H_ */