RTI Connext DDS Micro  Version 2.4.11
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
reda_indexer.h
1 /*
2  * FILE: reda_indexer.h - Indexer interface
3  *
4  * Copyright 2012-2015 Real-Time Innovations, Inc.
5  *
6  * No duplications, whole or partial, manual or electronic, may be made
7  * without express written permission. Any such copies, or
8  * revisions thereof, must display this notice unaltered.
9  * This code contains trade secrets of Real-Time Innovations, Inc.
10  *
11  * Modification History
12  * --------------------
13  * 31jul2014,tk MICRO-172/PR#1064 - Removed superfluous REDA_Indexer fields
14  * 25oct2012,tk Written
15  */
16 /*ci
17  * \file
18  *
19  * \brief The REDA Indexer interface provides a implementation independent API
20  * for searching and finding elements.
21  *
22  * \defgroup REDAIndexerClass REDA Indexer
23  * \ingroup REDAModule
24  *
25  * \details
26  *
27  * The REDA Indexer indexes elements based on a compare function and
28  * provides function to search and iterate over the elements in the index.
29  * The API is defined so that the underlying data-structures are not exposed.
30  */
31 #ifndef reda_indexer_h
32 #define reda_indexer_h
33 #ifndef reda_dll_h
34 #include "reda/reda_dll.h"
35 #endif
36 
37 #ifdef __cplusplus
38 extern "C"
39 {
40 #endif
41 
42 /*ci
43  * \addtogroup REDAIndexerClass
44  * @{
45  */
46 struct REDA_Indexer;
47 
48 struct REDA_IndexIterator;
49 
50 typedef struct REDA_IndexIterator REDA_IndexIterator_T;
51 
52 /*ci
53  * \brief Abstract Indexer type
54  */
55 typedef struct REDA_Indexer REDA_Indexer_T;
56 
57 /*ci
58  * \brief The properties an index can be created with.
59  */
60 struct REDA_IndexerProperty
61 {
62  /*ci
63  * \brief The maximum number of elements the index can handle
64  */
65  RTI_INT32 max_entries;
66 };
67 
68 /*ci
69  * \def REDA_IndexerProperty_INITIALIZER
70  * \brief \ref REDA_IndexerProperty initializer
71  */
72 #define REDA_IndexerProperty_INITIALIZER \
73 {\
74  1\
75 }
76 
77 /*ci
78  * \brief A generic record compare function
79  *
80  * \details
81  *
82  * The compare function must maintain an ordered relationship.
83  *
84  * \param[in] record Already indexed element to compare against
85  * \param[in] key_is_record Whether the key is a complete record or the user
86  * defined key
87  * \param[in] key Key to compare against
88  *
89  * \return The function must return zero if record == key,
90  * a negative integer if record < key,
91  * and a positive integer if record > key
92  */
93 FUNCTION_MUST_TYPEDEF(
94 RTI_INT32
95 (*REDA_Indexer_compare_T)(const void *const record, RTI_BOOL key_is_record,
96  const void *const key)
97 )
98 
99 /*ci
100  * \brief Create a new indexer
101  *
102  * \param[in] compare Compare function that determines the ordering of the
103  * indexed elements as defined for
104  * \ref REDA_Indexer_compare_T
105  *
106  * \param[in] property Indexer property. Refer to \ref
107  * REDA_IndexerProperty for details.
108  *
109  * \return Pointer to new indexer on success, NULL on failure
110  *
111  * \sa REDA_Indexer_delete
112  */
113 MUST_CHECK_RETURN REDADllExport REDA_Indexer_T*
114 REDA_Indexer_new(REDA_Indexer_compare_T compare,
115  struct REDA_IndexerProperty *property);
116 
117 #ifndef RTI_CERT
118 /*ci
119  * \brief Delete an indexer
120  *
121  * \details
122  *
123  * Delete an index. It is legal to delete an index which contains elements.
124  * It is the callers responsibility to make sure that the elements in the
125  * index can be properly deleted.
126  *
127  * \param[in] indexer Indexer to delete
128  *
129  * \return RTI_TRUE on success, RTI_FALSE on failure
130  *
131  * \sa REDA_Indexer_new
132  */
133 SHOULD_CHECK_RETURN REDADllExport RTI_BOOL
134 REDA_Indexer_delete(REDA_Indexer_T *indexer);
135 #endif /* !RTI_CERT */
136 
137 /*ci
138  * \brief Add an element to an index
139  *
140  * \details
141  *
142  * Add an element to the indexer. The indexer is not responsible for managing
143  * the memory owner the entry.
144  *
145  * \param[in] indexer Indexer to add the element to
146  * \param[in] entry Entry to add to indexer
147  *
148  * \return RTI_TRUE on success, RTI_FALSE on failure
149  *
150  * \sa REDA_Indexer_remove_entry
151  */
152 MUST_CHECK_RETURN REDADllExport RTI_BOOL
153 REDA_Indexer_add_entry(REDA_Indexer_T *indexer,void *entry);
154 
155 /*ci
156  * \brief Remove an element from an index
157  *
158  * \details
159  *
160  * Remove an element from an indexer based on the key. The indexer is not
161  * responsible for managing the memory used by the removed entry.
162  *
163  * \param[in] indexer Indexer to add the element to
164  * \param[in] key Key to remove
165  *
166  * \return pointer to removed entry if it existed, NULL otherwise.
167  *
168  * \sa REDA_Indexer_add_entry
169  */
170 SHOULD_CHECK_RETURN REDADllExport void*
171 REDA_Indexer_remove_entry(REDA_Indexer_T *indexer,const void *const key);
172 
173 /*ci
174  * \brief Find an entry based on the key
175  *
176  * \details
177  *
178  * Search for an entry based on the key.
179  *
180  * \param[in] indexer Indexer to search for element in
181  * \param[in] key Key to search for
182  *
183  * \return pointer to entry if it existed, NULL otherwise.
184  *
185  * \sa REDA_Indexer_find_entry_eq_or_gt
186  */
187 MUST_CHECK_RETURN REDADllExport void*
188 REDA_Indexer_find_entry(REDA_Indexer_T *indexer,const void *const key);
189 
190 /*ci
191  * \brief Find an entry with a key greater or equal to the key
192  *
193  * \details
194  *
195  * Find an entry with a key greater or equal to the key.
196  *
197  * \param[in] indexer Indexer to search for element in
198  * \param[in] key Key to search for
199  *
200  * \return pointer to entry if it existed, NULL otherwise.
201  *
202  * \sa REDA_Indexer_find_entry
203  */
204 MUST_CHECK_RETURN REDADllExport void*
205 REDA_Indexer_find_entry_eq_or_gt(REDA_Indexer_T *indexer,const void *const key);
206 
207 /*ci
208  * \brief Find an entry with a key less than or equal to the key
209  *
210  * \details
211  *
212  * Find an entry with a key greater or equal to the key.
213  *
214  * \param[in] indexer Indexer to search for element in
215  * \param[in] key Key to search for
216  *
217  * \return pointer to entry if it existed, NULL otherwise.
218  *
219  * \sa REDA_Indexer_find_entry
220  */
221 MUST_CHECK_RETURN REDADllExport void*
222 REDA_Indexer_find_entry_eq_or_lt(REDA_Indexer_T *indexer,const void *const key);
223 
224 /*ci
225  * \brief Return the number of elements in the index
226  *
227  * \details
228  *
229  * Return the number of elements in the index
230  *
231  * \param[in] indexer Indexer to return count for. Indexer cannot be NULL,
232  * and it is the callers responsibility to ensure it is not.
233  *
234  * \return Number of elements in the index.
235  *
236  * \sa REDA_Indexer_get_entry
237  */
238 MUST_CHECK_RETURN REDADllExport RTI_INT32
239 REDA_Indexer_get_count(REDA_Indexer_T *indexer);
240 
241 /*ci
242  * \brief Return the index'th element in the index
243  *
244  * \details
245  *
246  * Return the index'th element in the index.
247  *
248  * \param[in] indexer Indexer to return the element from
249  * \param[in] index Which element to return, starting at 0
250  *
251  * \return The index'th element in the indexer
252  *
253  * \sa REDA_Indexer_get_count
254  */
255 MUST_CHECK_RETURN REDADllExport void*
256 REDA_Indexer_get_entry(REDA_Indexer_T *indexer,RTI_INT32 index);
257 
258 /*ci
259  * \brief Return the first element in the index
260  *
261  * \details
262  *
263  * Return the first element in the index
264  *
265  * \param[in] indexer Indexer to return the the first element from
266  *
267  * \return The first element in the index, NULL if the index is empty.
268  *
269  * \sa
270  */
271 MUST_CHECK_RETURN REDADllExport void*
272 REDA_Indexer_get_first_entry(REDA_Indexer_T *indexer);
273 
274 /*ci
275  * \brief Return the last element in the index
276  *
277  * \details
278  *
279  * Return the last element in the index
280  *
281  * \param[in] indexer Indexer to return the the last element from
282  *
283  * \return The last element in the index, NULL if the index is empty.
284  *
285  * \sa
286  */
287 MUST_CHECK_RETURN REDADllExport void*
288 REDA_Indexer_get_last_entry(REDA_Indexer_T *indexer);
289 
290 /*ci
291  * \brief Start an iterator for the indexer
292  *
293  * \details
294  *
295  * Each indexer has exactly one -1- iterator. This function initializes the
296  * iterator for the indexer and clears any previous initialization. Thus,
297  * it is the callers responsibility to ensure that the iterator is used
298  * at most once at a time.
299  *
300  * \param[in] indexer Indexer to iterate over
301  *
302  * \return An initialized iterator
303  */
304 REDADllExport REDA_IndexIterator_T*
305 REDA_Indexer_iterator_begin(REDA_Indexer_T *indexer);
306 
307 /*ci
308  * \brief Return the the next element in the iterator
309  *
310  * \details
311  *
312  * Each call to this function returns the next element in the indexer. The
313  * next element is the element that is larger than the current
314  * element as defined by the indexer's compare function.
315  *
316  * NOTE: If an element is removed the iterator is updated so that no elements
317  * are missed. However, if an element is added the iterator may
318  * include the new element. Thus, a current iteration must be able
319  * to handle the addition of a new element as well as not rely on
320  * the additon of a new element.
321  *
322  * \param[in] iterator Iterator to return the the last element from
323  *
324  *
325  * \return The next element or NULL if there are no more elements
326  */
327 MUST_CHECK_RETURN REDADllExport void*
328 REDA_Indexer_iterator_next(REDA_IndexIterator_T *iterator);
329 
330 #ifdef __cplusplus
331 } /* extern "C" */
332 #endif
333 
334 #endif /* reda_indexer_h */
335 
336 /*ci @} */

RTI Connext DDS Micro Version 2.4.11 Copyright © Mon Jul 23 2018 Real-Time Innovations, Inc