update
[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 items (MAX_T) or min items (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 items (bType==MAX_T) or min items (bType==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 top: max items (bType==MAX_T) or min items (bType==MIN_T).
39 * @param arity Arity of the wrapped heap: any integer >=2.
40 *
41 * Usage: BufferTop* buffertop_new(<Type> type, UInt capacity, OrderTypebType, UInt arity)
42 */
43 #define buffertop_new(type, capacity, bType, arity) \
44 _buffertop_new(sizeof(type), capacity, bType, arity)
45
46 /**
47 * @brief Copy constructor (works well if items do not have allocated sub-pointers).
48 */
49 BufferTop* buffertop_copy(
50 BufferTop* bufferTop ///< "this" pointer.
51 );
52
53 /**
54 * @brief Turn the buffer into a list to scan its content linearly.
55 */
56 List* buffertop_2list(
57 BufferTop* bufferTop ///< "this" pointer.
58 );
59
60 /**
61 * @brief Check if the buffer is empty.
62 */
63 Bool buffertop_empty(
64 BufferTop* bufferTop ///< "this" pointer.
65 );
66
67 /**
68 * @brief Return the size of current buffer (<= capacity).
69 */
70 UInt buffertop_size(
71 BufferTop* bufferTop ///< "this" pointer.
72 );
73
74 /**
75 * @brief (Try to) add an item-value in the buffer.
76 */
77 void _buffertop_tryadd(
78 BufferTop* bufferTop, ///< "this" pointer.
79 void* item, ///< Pointer to an item of type as defined in the constructor.
80 Real value ///< Value associated with the item.
81 );
82
83 /**
84 * @brief (Try to) add an item-value in the buffer.
85 * @param bufferTop "this" pointer.
86 * @param item Item of type as defined in the constructor.
87 * @param value Value associated with the item.
88 *
89 * Usage: void buffertop_tryadd(BufferTop* bufferTop, void item, Real value)
90 */
91 #define buffertop_tryadd(bufferTop, item, value) \
92 { \
93 typeof((item)) tmp = item; \
94 _buffertop_tryadd(bufferTop, &tmp, value); \
95 }
96
97 /**
98 * @brief Return the top ("worst among best") ItemValue inside current buffer.
99 */
100 ItemValue* buffertop_first_raw(
101 BufferTop* bufferTop ///< "this" pointer.
102 );
103
104 /**
105 * @brief Set item_ to the top ("worst among best") item inside current buffer.
106 * @param bufferTop "this" pointer.
107 * @param item_ Variable to be assigned.
108 *
109 * Usage: void buffertop_first(BufferTop* bufferTop, void item)
110 */
111 #define buffertop_first(bufferTop, item_) \
112 { \
113 void* pItem = buffertop_first_raw(bufferTop)->item; \
114 item_ = *((typeof(&item_))pItem); \
115 }
116
117 /**
118 * @brief Remove the top ("worst among best") item-value inside the buffer.
119 */
120 void buffertop_pop(
121 BufferTop* bufferTop ///< "this" pointer.
122 );
123
124 /**
125 * @brief Clear the entire buffer.
126 */
127 void buffertop_clear(
128 BufferTop* bufferTop ///< "this" pointer.
129 );
130
131 /**
132 * @brief Destroy the buffer: clear it, and free 'bufferTop' pointer.
133 */
134 void buffertop_destroy(
135 BufferTop* bufferTop ///< "this" pointer.
136 );
137
138 #endif