96af7695238f8f73a6352736d6588cd8423fec14
[cgds.git] / src / BufferTop.h
1 /**
2 * @file BufferTop.h
3 */
4
5 #ifndef CGDS_BUFFER_TOP_H
6 #define CGDS_BUFFER_TOP_H
7
8 #include <stdlib.h>
9 #include <string.h>
10 #include "cgds/types.h"
11 #include "cgds/Heap.h"
12 #include "cgds/List.h"
13 #include "cgds/safe_alloc.h"
14
15 /**
16 * @brief Data structure to store top (MAX or MIN) elements in a buffer.
17 */
18 typedef struct BufferTop {
19 UInt capacity; ///< Buffer capacity (in items count).
20 OrderType bType; ///< Type of buffer: keep max or min items (MAX_T or MIN_T).
21 Heap* heap; ///< Item-ValueS are internally organized into a heap.
22 } BufferTop;
23
24 /**
25 * @brief Return an allocated and initialized buffer.
26 */
27 BufferTop* _buffertop_new(
28 size_t dataSize, ///< Size in bytes of a buffer element.
29 UInt capacity, ///< Maximum number of elements that the buffer can contain.
30 OrderType bType, ///< Type of buffer: keep max or min items (MAX_T or MIN_T).
31 UInt arity ///< Arity of the wrapped heap: any integer >=2.
32 );
33
34 /**
35 * @brief Return an allocated and initialized buffer.
36 * @param type Type of a buffer item (int, char*, ...).
37 * @param capacity Maximum number of elements that the buffer can contain.
38 * @param bType type of buffer: keep max or min items (MAX_T or MIN_T).
39 * @param arity Arity of the wrapped heap: any integer >=2.
40 *
41 * Usage: BufferTop* buffertop_new(\
42 * <Type> type, UInt capacity, OrderTypebType, UInt arity)
43 */
44 #define buffertop_new(type, capacity, bType, arity) \
45 _buffertop_new(sizeof(type), capacity, bType, arity)
46
47 /**
48 * @brief Copy constructor (shallow copy, ok for basic types).
49 */
50 BufferTop* buffertop_copy(
51 BufferTop* bufferTop ///< "this" pointer.
52 );
53
54 /**
55 * @brief Turn the buffer into a list to scan its content linearly.
56 */
57 List* buffertop_2list(
58 BufferTop* bufferTop ///< "this" pointer.
59 );
60
61 /**
62 * @brief Check if the buffer is empty.
63 */
64 bool buffertop_empty(
65 BufferTop* bufferTop ///< "this" pointer.
66 );
67
68 /**
69 * @brief Return the size of current buffer (<= capacity).
70 */
71 UInt buffertop_size(
72 BufferTop* bufferTop ///< "this" pointer.
73 );
74
75 /**
76 * @brief (Try to) add an item-value in the buffer.
77 */
78 void _buffertop_tryadd(
79 BufferTop* bufferTop, ///< "this" pointer.
80 void* item, ///< Pointer to an item of type as defined in the constructor.
81 Real value ///< Value associated with the item.
82 );
83
84 /**
85 * @brief (Try to) add an item-value in the buffer.
86 * @param bufferTop "this" pointer.
87 * @param item Item of type as defined in the constructor.
88 * @param value Value associated with the item.
89 *
90 * Usage: void buffertop_tryadd(BufferTop* bufferTop, void item, Real value)
91 */
92 #define buffertop_tryadd(bufferTop, item, value) \
93 { \
94 typeof((item)) tmp = item; \
95 _buffertop_tryadd(bufferTop, &tmp, value); \
96 }
97
98 /**
99 * @brief Return the top ("worst among best") ItemValue inside current buffer.
100 */
101 ItemValue* buffertop_first_raw(
102 BufferTop* bufferTop ///< "this" pointer.
103 );
104
105 /**
106 * @brief Set item_ to the top ("worst among best") item inside current buffer.
107 * @param bufferTop "this" pointer.
108 * @param item_ Variable to be assigned.
109 *
110 * Usage: void buffertop_first(BufferTop* bufferTop, void item)
111 */
112 #define buffertop_first(bufferTop, item_) \
113 { \
114 void* pItem = buffertop_first_raw(bufferTop)->item; \
115 item_ = *((typeof(&item_))pItem); \
116 }
117
118 /**
119 * @brief Remove the top ("worst among best") item-value inside the buffer.
120 */
121 void buffertop_pop(
122 BufferTop* bufferTop ///< "this" pointer.
123 );
124
125 /**
126 * @brief Clear the entire buffer.
127 */
128 void buffertop_clear(
129 BufferTop* bufferTop ///< "this" pointer.
130 );
131
132 /**
133 * @brief Destroy the buffer: clear it, and free 'bufferTop' pointer.
134 */
135 void buffertop_destroy(
136 BufferTop* bufferTop ///< "this" pointer.
137 );
138
139 #endif