blob: cb5bfa0cd760dd3518a91ebb312bed855fc4ab2a [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
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22/**
23 * @defgroup lyset Generic sets
24 *
25 * Structure and functions to hold and manipulate with sets of nodes from schema or data trees.
26 *
27 * @{
28 */
29
30/**
31 * @brief Structure to hold a set of (not necessary somehow connected) objects. Usually used for ::lyd_node
32 * or ::lys_node objects, but it is not limited to them. Caller is supposed to not mix the type of objects
33 * added to the set and according to its knowledge about the set content, it can access objects via the members
34 * of the set union.
35 *
36 * Until ly_set_rm() or ly_set_rm_index() is used, the set keeps the order of the inserted items as they
37 * were added into the set, so the first added item is on array index 0.
38 *
39 * To free the structure, use ly_set_free() function, to manipulate with the structure, use other
40 * ly_set_* functions.
41 */
42struct ly_set
43{
44 unsigned int size; /**< allocated size of the set array */
45 unsigned int number; /**< number of elements in (used size of) the set array */
46 union
47 {
48 struct lys_node **schemas; /**< array of pointers to a ::lys_node objects */
49 struct lyd_node **data; /**< array of pointers to a ::lyd_node objects */
50 void **objs; /**< dummy array for generic work */
51 }; /**< set array - union to simplify access to the stored objects */
52};
53
54/**
55 * @brief Option for ly_set_add() to allow duplicities in the ly_set structure so the
56 * set is not used as a set, but as a list of (container for) items.
57 */
58#define LY_SET_OPT_USEASLIST 0x01
59
60/**
61 * @brief Create and initiate new ::ly_set structure.
62 *
63 * @return Created ::ly_set structure or NULL in case of error.
64 */
65struct ly_set *ly_set_new (void);
66
67/**
68 * @brief Duplicate the existing set.
69 *
70 * @param[in] set Original set to duplicate
71 * @return Duplication of the original set.
72 */
73struct ly_set *ly_set_dup (const struct ly_set *set);
74
75/**
76 * @brief Add a ::lyd_node or ::lys_node object into the set
77 *
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 */
88int ly_set_add (struct ly_set *set, void *object, int options);
89
90/**
91 * @brief Add all objects from \p src to \p trg.
92 *
93 * Since it is a set, the function checks for duplicities.
94 * After success, \p src is completely freed.
95 *
96 * @param[in] trg Target (result) set.
97 * @param[in] src Source set.
98 * @param[in] options Options to change behavior of the function. Accepted options are:
99 * - #LY_SET_OPT_USEASLIST - do not check for duplicities
100 * @return -1 on failure, number of objects added into \p trg on success.
101 */
102int ly_set_merge (struct ly_set *trg, struct ly_set *src, int options);
103
104/**
105 * @brief Get know if the set contains the specified object.
106 * @param[in] set Set to explore.
107 * @param[in] object Object to be found in the set.
108 * @return Index of the object in the set or -1 if the object is not present in the set.
109 */
110int ly_set_contains (const struct ly_set *set, void *object);
111
112/**
113 * @brief Remove all objects from the set, but keep the set container for further use.
114 *
115 * @param[in] set Set to clean.
116 * @return LY_ERR return value.
117 */
118LY_ERR ly_set_clean (struct ly_set *set);
119
120/**
121 * @brief Remove an object from the set.
122 *
123 * Note that after removing the object from a set, indexes of other objects in the set can change
124 * (the last object is placed instead of the removed object).
125 *
126 * @param[in] set Set from which the \p node will be removed.
127 * @param[in] obejct The object to be removed from the \p set.
128 * @return LY_ERR return value.
129 */
130LY_ERR ly_set_rm (struct ly_set *set, void *object);
131
132/**
133 * @brief Remove an object on the specific set index.
134 *
135 * Note that after removing the object from a set, indexes of other nodes in the set can change
136 * (the last object is placed instead of the removed object).
137 *
138 * @param[in] set Set from which a node will be removed.
139 * @param[in] index Index of the object to remove in the \p set.
140 * @return LY_ERR return value.
141 */
142LY_ERR ly_set_rm_index (struct ly_set *set, unsigned int index);
143
144/**
145 * @brief Free the ::ly_set data. Frees only the set structure content, not the referred data.
146 *
147 * @param[in] set The set to be freed.
148 */
149void ly_set_free (struct ly_set *set);
150
151/** @} lyset */
152
153#ifdef __cplusplus
154}
155#endif
156
157#endif /* LY_SET_H_ */