RTI Connext DDS Micro  Version 2.4.9
 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 /*ci
49  * \brief Abstract Indexer type
50  */
51 typedef struct REDA_Indexer REDA_Indexer_T;
52 
53 /*ci
54  * \brief The properties an index can be created with.
55  */
56 struct REDA_IndexerProperty
57 {
58  /*ci
59  * \brief The maximum number of elements the index can handle
60  */
61  RTI_INT32 max_entries;
62 };
63 
64 /*ci
65  * \def REDA_IndexerProperty_INITIALIZER
66  * \brief \ref REDA_IndexerProperty initializer
67  */
68 #define REDA_IndexerProperty_INITIALIZER \
69 {\
70  1\
71 }
72 
73 /*ci
74  * \brief A generic record compare function
75  *
76  * \details
77  *
78  * The compare function must maintain an ordered relationship.
79  *
80  * \param[in] record Already indexed element to compare against
81  * \param[in] key_is_record Whether the key is a complete record or the user
82  * defined key
83  * \param[in] key Key to compare against
84  *
85  * \return The function must return zero if record == key,
86  * a negative integer if record < key,
87  * and a positive integer if record > key
88  */
89 FUNCTION_MUST_TYPEDEF(
90 RTI_INT32
91 (*REDA_Indexer_compare_T)(const void *const record, RTI_BOOL key_is_record,
92  const void *const key)
93 )
94 
95 /*ci
96  * \brief Create a new indexer
97  *
98  * \param[in] compare Compare function that determines the ordering of the
99  * indexed elements as defined for
100  * \ref REDA_Indexer_compare_T
101  *
102  * \param[in] property Indexer property. Refer to \ref
103  * REDA_IndexerProperty for details.
104  *
105  * \return Pointer to new indexer on success, NULL on failure
106  *
107  * \sa REDA_Indexer_delete
108  */
109 MUST_CHECK_RETURN REDADllExport REDA_Indexer_T*
110 REDA_Indexer_new(REDA_Indexer_compare_T compare,
111  struct REDA_IndexerProperty *property);
112 
113 #ifndef RTI_CERT
114 /*ci
115  * \brief Delete an indexer
116  *
117  * \details
118  *
119  * Delete an index. It is legal to delete an index which contains elements.
120  * It is the callers responsibility to make sure that the elements in the
121  * index can be properly deleted.
122  *
123  * \param[in] indexer Indexer to delete
124  *
125  * \return RTI_TRUE on success, RTI_FALSE on failure
126  *
127  * \sa REDA_Indexer_new
128  */
129 SHOULD_CHECK_RETURN REDADllExport RTI_BOOL
130 REDA_Indexer_delete(REDA_Indexer_T *indexer);
131 #endif /* !RTI_CERT */
132 
133 /*ci
134  * \brief Add an element to an index
135  *
136  * \details
137  *
138  * Add an element to the indexer. The indexer is not responsible for managing
139  * the memory owner the entry.
140  *
141  * \param[in] indexer Indexer to add the element to
142  * \param[in] entry Entry to add to indexer
143  *
144  * \return RTI_TRUE on success, RTI_FALSE on failure
145  *
146  * \sa REDA_Indexer_remove_entry
147  */
148 MUST_CHECK_RETURN REDADllExport RTI_BOOL
149 REDA_Indexer_add_entry(REDA_Indexer_T *indexer,void *entry);
150 
151 /*ci
152  * \brief Remove an element from an index
153  *
154  * \details
155  *
156  * Remove an element from an indexer based on the key. The indexer is not
157  * responsible for managing the memory used by the removed entry.
158  *
159  * \param[in] indexer Indexer to add the element to
160  * \param[in] key Key to remove
161  *
162  * \return pointer to removed entry if it existed, NULL otherwise.
163  *
164  * \sa REDA_Indexer_add_entry
165  */
166 SHOULD_CHECK_RETURN REDADllExport void*
167 REDA_Indexer_remove_entry(REDA_Indexer_T *indexer,const void *const key);
168 
169 /*ci
170  * \brief Find an entry based on the key
171  *
172  * \details
173  *
174  * Search for an entry based on the key.
175  *
176  * \param[in] indexer Indexer to search for element in
177  * \param[in] key Key to search for
178  *
179  * \return pointer to entry if it existed, NULL otherwise.
180  *
181  * \sa REDA_Indexer_find_entry_eq_or_gt
182  */
183 MUST_CHECK_RETURN REDADllExport void*
184 REDA_Indexer_find_entry(REDA_Indexer_T *indexer,const void *const key);
185 
186 /*ci
187  * \brief Find an entry with a key greater or equal to the key
188  *
189  * \details
190  *
191  * Find an entry with a key greater or equal to the key.
192  *
193  * \param[in] indexer Indexer to search for element in
194  * \param[in] key Key to search for
195  *
196  * \return pointer to entry if it existed, NULL otherwise.
197  *
198  * \sa REDA_Indexer_find_entry
199  */
200 MUST_CHECK_RETURN REDADllExport void*
201 REDA_Indexer_find_entry_eq_or_gt(REDA_Indexer_T *indexer,const void *const key);
202 
203 /*ci
204  * \brief Return the number of elements in the index
205  *
206  * \details
207  *
208  * Return the number of elements in the index
209  *
210  * \param[in] indexer Indexer to return count for. Indexer cannot be NULL,
211  * and it is the callers responsibility to ensure it is not.
212  *
213  * \return Number of elements in the index.
214  *
215  * \sa REDA_Indexer_get_entry
216  */
217 MUST_CHECK_RETURN REDADllExport RTI_INT32
218 REDA_Indexer_get_count(REDA_Indexer_T *indexer);
219 
220 /*ci
221  * \brief Return the index'th element in the index
222  *
223  * \details
224  *
225  * Return the index'th element in the index.
226  *
227  * \param[in] indexer Indexer to return the element from
228  * \param[in] index Which element to return, starting at 0
229  *
230  * \return The index'th element in the indexer
231  *
232  * \sa REDA_Indexer_get_count
233  */
234 MUST_CHECK_RETURN REDADllExport void*
235 REDA_Indexer_get_entry(REDA_Indexer_T *indexer,RTI_INT32 index);
236 
237 /*ci
238  * \brief Return the first element in the index
239  *
240  * \details
241  *
242  * Return the first element in the index
243  *
244  * \param[in] indexer Indexer to return the the first element from
245  *
246  * \return The first element in the index, NULL if the index is empty.
247  *
248  * \sa
249  */
250 MUST_CHECK_RETURN REDADllExport void*
251 REDA_Indexer_get_first_entry(REDA_Indexer_T *indexer);
252 
253 /*ci
254  * \brief Return the last element in the index
255  *
256  * \details
257  *
258  * Return the last element in the index
259  *
260  * \param[in] indexer Indexer to return the the last element from
261  *
262  * \return The last element in the index, NULL if the index is empty.
263  *
264  * \sa
265  */
266 MUST_CHECK_RETURN REDADllExport void*
267 REDA_Indexer_get_last_entry(REDA_Indexer_T *indexer);
268 
269 #ifdef __cplusplus
270 } /* extern "C" */
271 #endif
272 
273 #endif /* reda_indexer_h */
274 
275 /*ci @} */

RTI Connext DDS Micro Version 2.4.9 Copyright © Thu Dec 15 2016 Real-Time Innovations, Inc