VirtualBox

source: vbox/trunk/include/iprt/table.h@ 77921

Last change on this file since 77921 was 76585, checked in by vboxsync, 6 years ago

*: scm --fix-header-guard-endif

  • Property eol-style set to native
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 23.5 KB
Line 
1/** @file
2 * IPRT - Abstract Table/Trees.
3 */
4
5/*
6 * Copyright (C) 2006-2019 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef IPRT_INCLUDED_table_h
27#define IPRT_INCLUDED_table_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <iprt/types.h>
33
34/** @defgroup grp_rt_tab RTTab - Generic Tree and Table Interface.
35 * @ingroup grp_rt
36 * @{
37 */
38
39RT_C_DECLS_BEGIN
40
41/** Pointer to an allocator. */
42typedef struct RTTABALLOCATOR *PRTTABALLOCATOR;
43
44/**
45 * Allocates memory.
46 *
47 * @returns Pointer to the allocated memory.
48 * @returns NULL on failure. (don't throw!)
49 * @param pAllocator The allocator structure.
50 * @param cb The number of bytes to allocate. (Never 0.)
51 */
52typedef DECLCALLBACK(void *) FNRTTABALLOC(PRTTABALLOCATOR pAllocator, size_t cb);
53/** Pointer to a FNRTTABALLOC() function. */
54typedef FNRTTABALLOC *PFNRTTABALLOC;
55
56/**
57 * Frees memory.
58 *
59 * @param pAllocator The allocator structure.
60 * @param pv The memory to free. (can be NULL)
61 */
62typedef DECLCALLBACK(void *) FNRTTABFREE(PRTTABALLOCATOR pAllocator, void *pv);
63/** Pointer to a FNRTTABFREE() function. */
64typedef FNRTTABFREE *PFNRTTABFREE;
65
66/**
67 * The allocator structure.
68 * (Hint: use this as like 'base class' for your custom allocators.)
69 */
70typedef struct RTTABALLOCATOR
71{
72 /** The allocation function. */
73 PFNRTTABALLOC pfnAlloc;
74 /** The free function. */
75 PFNRTTABFREE pfnFree;
76} RTTABALLOCATOR;
77
78/**
79 * Gets the default allocator.
80 *
81 * @returns Pointer to the default allocator.
82 */
83RTDECL(RTTABALLOCATOR) RTTabDefaultAllocator(void);
84
85
86/**
87 * Compares two table items.
88 *
89 * @returns 0 if equal
90 * @returns <0 if pvItem1 is less than pvItem2 (pvItem2 is then greater than pvItem1).
91 * @returns >0 if pvItem1 is less than pvItem2 (pvItem1 is then greater than pvItem2).
92 *
93 * @param pvItem1 The first item.
94 * @param pvItem2 The second item.
95 * @param pvUser The user argument.
96 */
97typedef DECLCALLBACK(int) FNRTTABCOMP(const void *pvItem1, const void *pvItem2, void *pvUser);
98/** Pointer to a FNRTTABCOMP() function. */
99typedef FNRTTABCOMP *PFNRTTABCOMP;
100
101/**
102 * Duplicates a table item.
103 * This is used when duplicating or copying a table.
104 *
105 * @returns Pointer to the copy.
106 * @returns NULL on failure.
107 *
108 * @param pvItem The item to copy.
109 * @param pvUser The user argument.
110 */
111typedef DECLCALLBACK(void *) FNRTTABDUPLICATE(const void *pvItem, void *pvUser);
112/** Pointer to a FNRTTABDUPLICATE() function. */
113typedef FNRTTABDUPLICATE *PFNRTTABDUPLICATE;
114
115/**
116 * Callback function for doing something with an item.
117 *
118 * What exactly we're doing is specific to the context of the call.
119 *
120 * @param pvItem The item.
121 * @param pvUser The user argument.
122 */
123typedef DECLCALLBACK(void) FNRTTABCALLBACK(const void *pvItem, void *pvUser);
124/** Pointer to a FNRTTABCALLBACK() function. */
125typedef FNRTTABCALLBACK *PFNRTTABCALLBACK;
126
127
128/** Pointer to const table operations. */
129typedef const struct RTTABOPS *PCRTTABOPS;
130/** Pointer to a table. */
131typedef struct RTTAB *PRTTAB;
132/** Pointer to a const table. */
133typedef const struct RTTAB *PCRTTAB;
134/** Pointer to a traverser. */
135typedef struct RTTABTRAVERSER *PRTTABTRAVERSER;
136/** Pointer to a const traverser. */
137typedef const struct RTTABTRAVERSER *PCRTTABTRAVERSER;
138/** Pointer to a traverser core. */
139typedef struct RTTABTRAVERSERCORE *PRTTABTRAVERSERCORE;
140/** Pointer to a const traverser core. */
141typedef const struct RTTABTRAVERSERCORE *PCRTTABTRAVERSERCORE;
142
143
144/**
145 * Table operations.
146 */
147typedef struct RTTABOPS
148{
149 /**
150 * Create a table.
151 *
152 * @returns Pointer to the new table.
153 * @returns NULL if we're out of memory or some other resource.
154 * @param pOps The table operations.
155 * @param fCreateFlags The table type specific creation flags.
156 * @param pAllocator Custom allocator. Pass NULL for the default allocator.
157 * @param pfnComp The comparision function.
158 */
159 DECLCALLBACKMEMBER(PRTTAB, pfnCreate)(PCRTTABOPS pOps, unsigned fCreateFlags, PRTTABALLOCATOR pAllocator, PFNRTTABCOMP pfnComp);
160
161 /**
162 * Duplicates a table to a table of the same type.
163 *
164 * @returns Pointer to the new table.
165 * @returns NULL if we're out of memory or some other resource.
166 * @param pTab The table to duplicate.
167 * @param pfnDuplicate Pointer to the item duplication function. If NULL the new table will
168 * be referencing the same data as the old one.
169 * @param pfnNewCB Callback which is called for all the items in the new table. Optional.
170 * @param pAllocator Custom allocator. Pass NULL to use the same allocator as pTab.
171 */
172 DECLCALLBACKMEMBER(PRTTAB, pfnDuplicate)(PCRTTAB pTab, PFNRTTABDUPLICATE pfnDuplicate, PFNRTTABCALLBACK pfnNewCB, PRTTABALLOCATOR pAllocator);
173
174 /**
175 * Destroys a table.
176 *
177 * @param pTab The table to destroy.
178 */
179 DECLCALLBACKMEMBER(void, pfnDestroy)(PRTTAB pTab);
180
181 /**
182 * Inserts an item into the table, if a matching item is encountered
183 * the pointer to the pointer to it will be returned.
184 *
185 * @returns Pointer to the item pointer in the table.
186 * This can be used to replace existing items (don't break anything, dude).
187 * @returns NULL if we failed to allocate memory for the new node.
188 * @param pTab The table.
189 * @param pvItem The item which will be inserted if an matching item was not found in the table.
190 */
191 DECLCALLBACKMEMBER(void **, pfnProbe)(PRTTAB pTab, void *pvItem);
192
193 /**
194 * Inserts an item into the table, fail if a matching item exists.
195 *
196 * @returns NULL on success and allocation failure.
197 * @returns Pointer to the matching item.
198 * @param pTab The table.
199 * @param pvItem The item which is to be inserted.
200 */
201 DECLCALLBACKMEMBER(void *, pfnInsert)(PRTTAB pTab, void *pvItem);
202
203 /**
204 * Inserts an item into the table, if a matching item is encountered
205 * it will be replaced and returned.
206 *
207 * @returns NULL if inserted and allocation failure.
208 * @returns Pointer to the replaced item.
209 * @param pTab The table.
210 * @param pvItem The item which is to be inserted.
211 */
212 DECLCALLBACKMEMBER(void *, pfnReplace)(PRTTAB pTab, void *pvItem);
213
214 /**
215 * Removes an item from the table if found.
216 *
217 * @returns Pointer to the removed item.
218 * @returns NULL if no item matched pvItem.
219 * @param pTab The table.
220 * @param pvItem The item which is to be inserted.
221 */
222 DECLCALLBACKMEMBER(void *, pfnRemove)(PRTTAB pTab, const void *pvItem);
223
224 /**
225 * Finds an item in the table.
226 *
227 * @returns Pointer to the item it found.
228 * @returns NULL if no item matched pvItem.
229 * @param pTab The table.
230 * @param pvItem The item which is to be inserted.
231 */
232 DECLCALLBACKMEMBER(void *, pfnFind)(PRTTAB pTab, const void *pvItem);
233
234 /**
235 * Initializes a traverser to the NULL item.
236 *
237 * The NULL item is an imaginary table item before the first and after
238 * the last items in the table.
239 *
240 * @returns Pointer to the traverser positioned at the NULL item.
241 * @returns NULL on failure to allocate the traverser.
242 *
243 * @param pTab The table.
244 * @param pTravNew Pointer to a preallocated structure. Optional.
245 */
246 DECLCALLBACKMEMBER(PRTTABTRAVERSERCORE, pfnTravInit)(PRTTAB pTab, PRTTABTRAVERSER pTravNew);
247
248 /**
249 * Initializes a traverser to the first item in the table.
250 *
251 * If the table is empty, the traverser will be positioned at the NULL item
252 * like with RTTabTravInit().
253 *
254 * @returns Pointer to the traverser positioned at the first item or NULL item.
255 * @returns NULL on failure to allocate the traverser.
256 *
257 * @param pTab The table.
258 * @param pTravNew Pointer to a preallocated structure. Optional.
259 */
260 DECLCALLBACKMEMBER(PRTTABTRAVERSERCORE, pfnTravFirst)(PRTTAB pTab, PRTTABTRAVERSER pTravNew);
261
262 /**
263 * Initializes a traverser to the last item in the table.
264 *
265 * If the table is empty, the traverser will be positioned at the NULL item
266 * like with RTTabTravInit().
267 *
268 * @returns Pointer to the traverser positioned at the last item or NULL item.
269 * @returns NULL on failure to allocate the traverser.
270 *
271 * @param pTab The table.
272 * @param pTravNew Pointer to a preallocated structure. Optional.
273 */
274 DECLCALLBACKMEMBER(PRTTABTRAVERSERCORE, pfnTravLast)(PRTTAB pTab, PRTTABTRAVERSER pTravNew);
275
276 /**
277 * Initializes a traverser to an item matching the given one.
278 *
279 * If the item isn't found, the traverser will be positioned at the NULL item
280 * like with RTTabTravInit().
281 *
282 * @returns Pointer to the traverser positioned at the matching item or NULL item.
283 * @returns NULL on failure to allocate the traverser.
284 *
285 * @param pTab The table.
286 * @param pTravNew Pointer to a preallocated structure. Optional.
287 * @param pvItem The item to find the match to.
288 */
289 DECLCALLBACKMEMBER(PRTTABTRAVERSERCORE, pfnTravFind)(PRTTAB pTab, PRTTABTRAVERSER pTravNew, const void *pvItem);
290
291 /**
292 * Initializes a traverser to the inserted item.
293 *
294 * If there already exists an item in the tree matching pvItem, the traverser
295 * is positioned at that item like with RTTabTravFind().
296 *
297 * If the insert operation failes because of an out of memory condition, the
298 * traverser will be positioned at the NULL item like with RTTabTravInit().
299 *
300 * @returns Pointer to the traverser positioned at the inserted, existing or NULL item.
301 * @returns NULL on failure to allocate the traverser.
302 *
303 * @param pTab The table.
304 * @param pTravNew Pointer to a preallocated structure. Optional.
305 * @param pvItem The item to be inserted.
306 */
307 DECLCALLBACKMEMBER(PRTTABTRAVERSERCORE, pfnTravInsert)(PRTTAB pTab, PRTTABTRAVERSER pTravNew, void *pvItem);
308
309 /**
310 * Duplicates a traverser.
311 *
312 * @returns The pointer to the duplicate.
313 * @returns NULL on allocation failure.
314 *
315 * @param pTrav The traverser to duplicate.
316 * @param pTravNew Pointer to a preallocated structure. Optional.
317 */
318 DECLCALLBACKMEMBER(PRTTABTRAVERSERCORE, pfnTravDuplicate)(PRTTABTRAVERSERCORE pTrav, PCRTTABTRAVERSER pTravNew);
319
320 /**
321 * Frees a traverser.
322 *
323 * This can safely be called even if the traverser structure
324 * wasn't dynamically allocated or the constructor failed.
325 *
326 * @param pTrav The traverser which is to be free.
327 */
328 DECLCALLBACKMEMBER(void, pfnTravFree)(PRTTABTRAVERSERCORE pTrav);
329
330 /**
331 * Gets the current item.
332 *
333 * @returns The current item. (NULL indicates the imaginary NULL item.)
334 * @param pTrav The traverser.
335 */
336 DECLCALLBACKMEMBER(void *, pfnTravCur)(PCRTTABTRAVERSERCORE pTrav);
337
338 /**
339 * Advances to the next item.
340 *
341 * @returns The new current item. (NULL indicates the imaginary NULL item.)
342 * @param pTrav The traverser.
343 */
344 DECLCALLBACKMEMBER(void *, pfnTravNext)(PRTTABTRAVERSERCORE pTrav);
345
346 /**
347 * Advances to the previous item.
348 *
349 * @returns The new current item. (NULL indicates the imaginary NULL item.)
350 * @param pTrav The traverser.
351 */
352 DECLCALLBACKMEMBER(void *, pfnTravPrev)(PRTTABTRAVERSERCORE pTrav);
353
354 /**
355 * Replaces the current item.
356 *
357 * This has the same restrictions as RTTabProbe(), e.g. it's not permitted to
358 * break the order of the table.
359 *
360 * @returns The replaced item.
361 * @returns NULL if the current item is the NULL item. The traverser
362 * and table remains unchanged.
363 * @param pTrav The traverser.
364 * @param pvItem The item to be inserted.
365 */
366 DECLCALLBACKMEMBER(void *, pfnTravReplace)(PRTTABTRAVERSERCORE pTrav, void *pvItem);
367
368 /** The type of table type. */
369 const char *pszType;
370} RTTABOPS;
371
372/**
373 * A table.
374 */
375typedef struct RTTAB
376{
377 /** The table operations. */
378 PCRTTABOPS pOps;
379 /** The function for comparing table items. */
380 PFNRTTABCOMP pfnComp;
381 /** The number of items in the table. */
382 RTUINT cItems;
383 /** The table generation number.
384 * This must be updated whenever the table changes. */
385 RTUINT idGeneration;
386} RTTAB;
387
388
389/**
390 * Create a table.
391 *
392 * @returns Pointer to the new table.
393 * @returns NULL if we're out of memory or some other resource.
394 * @param pOps The table operations.
395 * @param fCreateFlags The table type specific creation flags.
396 * @param pAllocator Custom allocator. Pass NULL for the default allocator.
397 * @param pfnComp The comparision function.
398 */
399DECLINLINE(PRTTAB) RTTabCreate(PCRTTABOPS pOps, unsigned fCreateFlags, PRTTABALLOCATOR pAllocator, PFNRTTABCOMP pfnComp)
400{
401 return pOps->pfnCreate(pOps, fCreateFlags, pAllocator, pfnComp);
402}
403
404/**
405 * Duplicates a table to a table of the same type.
406 *
407 * @returns Pointer to the new table.
408 * @returns NULL if we're out of memory or some other resource.
409 * @param pTab The table to duplicate.
410 * @param pfnDuplicate Pointer to the item duplication function. If NULL the new table will
411 * be referencing the same data as the old one.
412 * @param pfnNewCB Callback which is called for all the items in the new table. Optional.
413 * @param pAllocator Custom allocator. Pass NULL to use the same allocator as pTab.
414 */
415DECLINLINE(PRTTAB) RTTabDuplicate(PCRTTAB pTab, PFNRTTABDUPLICATE pfnDuplicate, PFNRTTABCALLBACK pfnNewCB, PRTTABALLOCATOR pAllocator)
416{
417 return pTab->pOps->pfnDuplicate(pTab, pfnDuplicate, pfnNewCB, pAllocator);
418}
419
420/**
421 * Destroys a table.
422 *
423 * @param pTab The table to destroy.
424 */
425DECLINLINE(void) RTTabDestroy(PRTTAB pTab)
426{
427 pTab->pOps->pfnDestroy(pTab);
428}
429
430/**
431 * Count the item in the table.
432 *
433 * @returns Number of items in the table.
434 * @param pTab The table to count.
435 */
436DECLINLINE(RTUINT) RTTabCount(PRTTAB pTab)
437{
438 return pTab->cItems;
439}
440
441/**
442 * Inserts an item into the table, if a matching item is encountered
443 * the pointer to the pointer to it will be returned.
444 *
445 * @returns Pointer to the item pointer in the table.
446 * This can be used to replace existing items (don't break anything, dude).
447 * @returns NULL if we failed to allocate memory for the new node.
448 * @param pTab The table.
449 * @param pvItem The item which will be inserted if an matching item was not found in the table.
450 */
451DECLINLINE(void **) RTTabProbe(PRTTAB pTab, void *pvItem)
452{
453 return pTab->pOps->pfnProbe(pTab, pvItem);
454}
455
456/**
457 * Inserts an item into the table, fail if a matching item exists.
458 *
459 * @returns NULL on success and allocation failure.
460 * @returns Pointer to the matching item.
461 * @param pTab The table.
462 * @param pvItem The item which is to be inserted.
463 */
464DECLINLINE(void *) RTTabInsert(PRTTAB pTab, void *pvItem)
465{
466 return pTab->pOps->pfnInsert(pTab, pvItem);
467}
468
469/**
470 * Inserts an item into the table, if a matching item is encountered
471 * it will be replaced and returned.
472 *
473 * @returns NULL if inserted and allocation failure.
474 * @returns Pointer to the replaced item.
475 * @param pTab The table.
476 * @param pvItem The item which is to be inserted.
477 */
478DECLINLINE(void *) RTTabReplace(PRTTAB pTab, void *pvItem)
479{
480 return pTab->pOps->pfnReplace(pTab, pvItem);
481}
482
483/**
484 * Removes an item from the table if found.
485 *
486 * @returns Pointer to the removed item.
487 * @returns NULL if no item matched pvItem.
488 * @param pTab The table.
489 * @param pvItem The item which is to be inserted.
490 */
491DECLINLINE(void *) RTTabRemove(PRTTAB pTab, const void *pvItem)
492{
493 return pTab->pOps->pfnRemove(pTab, pvItem);
494}
495
496/**
497 * Finds an item in the table.
498 *
499 * @returns Pointer to the item it found.
500 * @returns NULL if no item matched pvItem.
501 * @param pTab The table.
502 * @param pvItem The item to find the match to.
503 */
504DECLINLINE(void *) RTTabFind(PRTTAB pTab, const void *pvItem)
505{
506 return pTab->pOps->pfnFind(pTab, pvItem);
507}
508
509
510/**
511 * Common traverser core.
512 */
513typedef struct RTTABTRAVERSERCORE
514{
515 /** The table being traversed. */
516 PRTTAB pTab;
517 /** Indicates that this traverser was allocated. */
518 bool fAllocated;
519 /** The table generation id this traverser was last updated for.
520 * This is used to catch up with table changes. */
521 RTUINT idGeneration;
522} RTTABTRAVERSERCORE;
523
524/**
525 * Generic traverser structure.
526 *
527 * Tree implementations will use the tree specific part by mapping
528 * this structure onto their own internal traverser structure.
529 *
530 * @remark It would be better to use alloca() for allocating the structure,
531 * OTOH this is simpler for the user.
532 */
533typedef struct RTTABTRAVERSER
534{
535 /** The common core of the traverser data. */
536 RTTABTRAVERSERCORE Core;
537 /** The tree specific data. */
538 void *apvTreeSpecific[32];
539} RTTABTRAVERSER;
540
541
542/**
543 * Initializes a traverser to the NULL item.
544 *
545 * The NULL item is an imaginary table item before the first and after
546 * the last items in the table.
547 *
548 * @returns Pointer to the traverser positioned at the NULL item.
549 * @returns NULL on failure to allocate the traverser.
550 *
551 * @param pTab The table.
552 * @param pTravNew Pointer to a preallocated structure. Optional.
553 */
554DECLINLINE(PRTTABTRAVERSERCORE) RTTabTravInit(PRTTAB pTab, PRTTABTRAVERSER pTravNew)
555{
556 return pTab->pOps->pfnTravInit(pTab, pTravNew);
557}
558
559/**
560 * Initializes a traverser to the first item in the table.
561 *
562 * If the table is empty, the traverser will be positioned at the NULL item
563 * like with RTTabTravInit().
564 *
565 * @returns Pointer to the traverser positioned at the first item or NULL item.
566 * @returns NULL on failure to allocate the traverser.
567 *
568 * @param pTab The table.
569 * @param pTravNew Pointer to a preallocated structure. Optional.
570 */
571DECLINLINE(PRTTABTRAVERSERCORE) RTTabTravFirst(PRTTAB pTab, PRTTABTRAVERSER pTravNew)
572{
573 return pTab->pOps->pfnTravFirst(pTab, pTravNew);
574}
575
576/**
577 * Initializes a traverser to the last item in the table.
578 *
579 * If the table is empty, the traverser will be positioned at the NULL item
580 * like with RTTabTravInit().
581 *
582 * @returns Pointer to the traverser positioned at the last item or NULL item.
583 * @returns NULL on failure to allocate the traverser.
584 *
585 * @param pTab The table.
586 * @param pTravNew Pointer to a preallocated structure. Optional.
587 */
588DECLINLINE(PRTTABTRAVERSERCORE) RTTabTravLast(PRTTAB pTab, PRTTABTRAVERSER pTravNew)
589{
590 return pTab->pOps->pfnTravLast(pTab, pTravNew);
591}
592
593/**
594 * Initializes a traverser to an item matching the given one.
595 *
596 * If the item isn't found, the traverser will be positioned at the NULL item
597 * like with RTTabTravInit().
598 *
599 * @returns Pointer to the traverser positioned at the matching item or NULL item.
600 * @returns NULL on failure to allocate the traverser.
601 *
602 * @param pTab The table.
603 * @param pTravNew Pointer to a preallocated structure. Optional.
604 * @param pvItem The item to find the match to.
605 */
606DECLINLINE(PRTTABTRAVERSERCORE) RTTabTravFind(PRTTAB pTab, PRTTABTRAVERSER pTravNew, const void *pvItem)
607{
608 return pTab->pOps->pfnTravFind(pTab, pTravNew, pvItem);
609}
610
611/**
612 * Initializes a traverser to the inserted item.
613 *
614 * If there already exists an item in the tree matching pvItem, the traverser
615 * is positioned at that item like with RTTabTravFind().
616 *
617 * If the insert operation failes because of an out of memory condition, the
618 * traverser will be positioned at the NULL item like with RTTabTravInit().
619 *
620 * @returns Pointer to the traverser positioned at the inserted, existing or NULL item.
621 * @returns NULL on failure to allocate the traverser.
622 *
623 * @param pTab The table.
624 * @param pTravNew Pointer to a preallocated structure. Optional.
625 * @param pvItem The item to be inserted.
626 */
627DECLINLINE(PRTTABTRAVERSERCORE) RTTabTravInsert(PRTTAB pTab, PRTTABTRAVERSER pTravNew, void *pvItem)
628{
629 return pTab->pOps->pfnTravInsert(pTab, pTravNew, pvItem);
630}
631
632/**
633 * Duplicates a traverser.
634 *
635 * @returns The pointer to the duplicate.
636 * @returns NULL on allocation failure.
637 *
638 * @param pTrav The traverser to duplicate.
639 * @param pTravNew Pointer to a preallocated structure. Optional.
640 */
641DECLINLINE(PRTTABTRAVERSERCORE) RTTabTravDuplicate(PRTTABTRAVERSERCORE pTrav, PCRTTABTRAVERSER pTravNew)
642{
643 if (pTrav)
644 return pTrav->pTab->pOps->pfnTravDuplicate(pTrav, pTravNew);
645 return NULL;
646}
647
648/**
649 * Frees a traverser.
650 *
651 * This can safely be called even if the traverser structure
652 * wasn't dynamically allocated or the constructor failed.
653 *
654 * @param pTrav The traverser which is to be free.
655 */
656DECLINLINE(void) RTTabTravFree(PRTTABTRAVERSERCORE pTrav)
657{
658 if (pTrav && pTrav->fAllocated)
659 pTrav->pTab->pOps->pfnTravFree(pTrav);
660}
661
662/**
663 * Gets the current item.
664 *
665 * @returns The current item. (NULL indicates the imaginary NULL item.)
666 * @param pTrav The traverser.
667 */
668DECLINLINE(void *) RTTabTravCur(PCRTTABTRAVERSERCORE pTrav)
669{
670 return pTrav->pTab->pOps->pfnTravCur(pTrav);
671}
672
673/**
674 * Advances to the next item.
675 *
676 * @returns The new current item. (NULL indicates the imaginary NULL item.)
677 * @param pTrav The traverser.
678 */
679DECLINLINE(void *) RTTabTravNext(PRTTABTRAVERSERCORE pTrav)
680{
681 return pTrav->pTab->pOps->pfnTravNext(pTrav);
682}
683
684/**
685 * Advances to the previous item.
686 *
687 * @returns The new current item. (NULL indicates the imaginary NULL item.)
688 * @param pTrav The traverser.
689 */
690DECLINLINE(void *) RTTabTravPrev(PRTTABTRAVERSERCORE pTrav)
691{
692 return pTrav->pTab->pOps->pfnTravPrev(pTrav);
693}
694
695/**
696 * Replaces the current item.
697 *
698 * This has the same restrictions as RTTabProbe(), e.g. it's not permitted to
699 * break the order of the table.
700 *
701 * @returns The replaced item.
702 * @returns NULL if the current item is the NULL item. The traverser
703 * and table remains unchanged.
704 * @param pTrav The traverser.
705 * @param pvItem The item to be inserted.
706 */
707DECLINLINE(void *) RTTabTravReplace(PRTTABTRAVERSERCORE pTrav, void *pvItem)
708{
709 return pTrav->pTab->pOps->pfnTravReplace(pTrav, pvItem);
710}
711
712RT_C_DECLS_END
713
714/** @} */
715
716#endif /* !IPRT_INCLUDED_table_h */
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette