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