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