src/Queue.h

   1 /**
   2  * @file Queue.h
   3  */
   4
   5 #ifndef CGDS_QUEUE_H
   6 #define CGDS_QUEUE_H
   7
   8 #include <stdlib.h>
   9 #include <string.h>
  10 #include "cgds/types.h"
  11 #include "cgds/safe_alloc.h"
  12
  13 /**
  14  * @brief Generic internal queue cell.
  15  */
  16 typedef struct QueueCell {
  17     void* data; ///< Generic data contained in the cell.
  18     struct QueueCell* next; ///< Next cell in the internal single-linked list.
  19 } QueueCell;
  20
  21 /**
  22  * @brief Queue containing generic data.
  23  * @param dataSize Size in bytes of a queue element.
  24  */
  25 typedef struct Queue {
  26     UInt size; ///< Count elements in the queue.
  27     size_t dataSize; ///< Size in bytes of a queue element.
  28     QueueCell* front; ///< Pointer to the next dequeued element.
  29     QueueCell* back; ///< Pointer to the last enqueued element.
  30 } Queue;
  31
  32 /**
  33  * @brief Initialize an empty queue.
  34  * @param queue "this" pointer.
  35  * @param dataSize Size in bytes of a queue element.
  36  */
  37 void _queue_init(
  38     Queue* queue, ///< "this" pointer.
  39     size_t dataSize ///< Size in bytes of a queue element.
  40 );
  41
  42 /**
  43  * @brief Return an allocated and initialized queue.
  44  */
  45 Queue* _queue_new(
  46     size_t dataSize ///< Size in bytes of a queue element.
  47 );
  48
  49 /**
  50  * @brief Return an allocated and initialized queue.
  51  * @param type Type of a queue element (int, char*, ...).
  52  *
  53  * Usage: Queue* queue_new(<Type> type)
  54  */
  55 #define queue_new(type) \
  56     _queue_new(sizeof(type))
  57
  58 /**
  59  * @brief Copy constructor (works well if items do not have allocated sub-pointers).
  60  */
  61 Queue* queue_copy(
  62     Queue* queue ///< "this" pointer.
  63 );
  64
  65 /**
  66  * @brief Check if the queue is empty.
  67  */
  68 Bool queue_empty(
  69     Queue* queue ///< "this" pointer.
  70 );
  71
  72 /**
  73  * @brief Return size of the current queue.
  74  */
  75 UInt queue_size(
  76     Queue* queue ///< "this" pointer.
  77 );
  78
  79 /**
  80  * @brief Add something at the end of the queue.
  81  */
  82 void _queue_push(
  83     Queue* queue, ///< "this" pointer.
  84     void* data ///< Data to be pushed.
  85 );
  86
  87 /**
  88  * @brief Add something at the end of the queue.
  89  * @param queue "this" pointer
  90  * @param data Data to be pushed.
  91  *
  92  * Usage: void queue_push(Queue* queue, void data)
  93  */
  94 #define queue_push(queue, data) \
  95 { \
  96     typeof((data)) tmp = data; \
  97     _queue_push(queue, &tmp); \
  98 }
  99
 100 /**
 101  * @brief Return what is at the beginning of the queue.
 102  */
 103 void* _queue_peek(
 104     Queue* queue ///< "this" pointer.
 105 );
 106
 107 /**
 108  * @brief Return what is at the beginning of the queue.
 109  * @param queue "this" pointer.
 110  * @param data Data to be assigned.
 111  *
 112  * Usage: void queue_peek(Queue* queue, void data)
 113  */
 114 #define queue_peek(queue, data) \
 115 { \
 116     void* pData = _queue_peek(queue); \
 117     data = *((typeof(&data))pData); \
 118 }
 119
 120 /**
 121  * @brief Remove the beginning of the queue.
 122  */
 123 void queue_pop(
 124     Queue* queue ///< "this" pointer.
 125 );
 126
 127 /**
 128  * @brief Clear the entire queue.
 129  */
 130 void queue_clear(
 131     Queue* queue ///< "this" pointer.
 132 );
 133
 134 /**
 135  * @brief Destroy the queue: clear it, and free 'queue' pointer.
 136  */
 137 void queue_destroy(
 138     Queue* queue ///< "this" pointer.
 139 );
 140
 141 #endif