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