Some fixes + improvements (Vector) + code reformatting
[cgds.git] / src / BufferTop.h
... / ...
CommitLineData
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 */
18typedef 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; ///< Items + values are internally organized into a heap.
22} BufferTop;
23
24/**
25 * @brief Return an allocated and initialized buffer.
26 */
27BufferTop* _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(<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 (shallow copy, ok for basic types).
48 */
49BufferTop* buffertop_copy(
50 BufferTop* bufferTop ///< "this" pointer.
51);
52
53/**
54 * @brief Turn the buffer into a list to scan its content linearly.
55 */
56List* buffertop_2list(
57 BufferTop* bufferTop ///< "this" pointer.
58);
59
60/**
61 * @brief Check if the buffer is empty.
62 */
63bool buffertop_empty(
64 BufferTop* bufferTop ///< "this" pointer.
65);
66
67/**
68 * @brief Return the size of current buffer (<= capacity).
69 */
70UInt buffertop_size(
71 BufferTop* bufferTop ///< "this" pointer.
72);
73
74/**
75 * @brief (Try to) add an item-value in the buffer.
76 */
77void _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 */
100ItemValue _buffertop_first(
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 ItemValue iv = _buffertop_first(bufferTop); \
114 item_ = *((typeof(item_)*)(iv.item)); \
115}
116
117/**
118 * @brief Remove the top ("worst among best") item-value inside the buffer.
119 */
120void buffertop_pop(
121 BufferTop* bufferTop ///< "this" pointer.
122);
123
124/**
125 * @brief Clear the entire buffer.
126 */
127void buffertop_clear(
128 BufferTop* bufferTop ///< "this" pointer.
129);
130
131/**
132 * @brief Destroy the buffer: clear it, and free 'bufferTop' pointer.
133 */
134void buffertop_destroy(
135 BufferTop* bufferTop ///< "this" pointer.
136);
137
138#endif