remove obsolete TODO

[cgds.git] / src / BufferTop.h

/**
 * @file BufferTop.h
 */

#ifndef CGDS_BUFFER_TOP_H
#define CGDS_BUFFER_TOP_H

#include <stdlib.h>
#include <string.h>
#include "cgds/types.h"
#include "cgds/Heap.h"
#include "cgds/List.h"
#include "cgds/safe_alloc.h"

/**
 * @brief Data structure to store top (MAX or MIN) elements in a buffer.
 */
typedef struct BufferTop {
	UInt capacity; ///< Buffer capacity (in items count).
	OrderType bType; ///< Type of buffer: keep max items (MAX_T) or min items (MIN_T).
	Heap* heap; ///< Item-ValueS are internally organized into a heap.
} BufferTop;

/**
 * @brief Return an allocated and initialized buffer.
 */
BufferTop* _buffertop_new(
	size_t dataSize, ///< Size in bytes of a buffer element.
	UInt capacity, ///< Maximum number of elements that the buffer can contain.
	OrderType bType, ///< Type of buffer: keep max items (bType==MAX_T) or min items (bType==MIN_T).
	UInt arity ///< Arity of the wrapped heap: any integer >=2.
);

/**
 * @brief Return an allocated and initialized buffer.
 * @param type Type of a buffer item (int, char*, ...).
 * @param capacity Maximum number of elements that the buffer can contain.
 * @param bType type of buffer top: max items (bType==MAX_T) or min items (bType==MIN_T).
 * @param arity Arity of the wrapped heap: any integer >=2.
 * 
 * Usage: BufferTop* buffertop_new(<Type> type, UInt capacity, OrderTypebType, UInt arity)
 */
#define buffertop_new(type, capacity, bType, arity) \
	_buffertop_new(sizeof(type), capacity, bType, arity)

/**
 * @brief Copy constructor (works well if items do not have allocated sub-pointers).
 */
BufferTop* buffertop_copy(
	BufferTop* bufferTop ///< "this" pointer.
);

/**
 * @brief Turn the buffer into a list to scan its content linearly.
 */
List* buffertop_2list(
	BufferTop* bufferTop ///< "this" pointer.
);

/**
 * @brief Check if the buffer is empty.
 */
Bool buffertop_empty(
	BufferTop* bufferTop ///< "this" pointer.
);

/**
 * @brief Return the size of current buffer (<= capacity).
 */
UInt buffertop_size(
	BufferTop* bufferTop ///< "this" pointer.
);

/**
 * @brief (Try to) add an item-value in the buffer.
 */
void _buffertop_tryadd(
	BufferTop* bufferTop, ///< "this" pointer.
	void* item, ///< Pointer to an item of type as defined in the constructor.
	Real value ///< Value associated with the item.
);

/**
 * @brief (Try to) add an item-value in the buffer.
 * @param bufferTop "this" pointer.
 * @param item Item of type as defined in the constructor.
 * @param value Value associated with the item.
 * 
 * Usage: void buffertop_tryadd(BufferTop* bufferTop, void item, Real value)
 */
#define buffertop_tryadd(bufferTop, item, value) \
{ \
	typeof((item)) tmp = item; \
	_buffertop_tryadd(bufferTop, &tmp, value); \
}

/**
 * @brief Return the top ("worst among best") ItemValue inside current buffer.
 */
ItemValue* buffertop_first_raw(
	BufferTop* bufferTop ///< "this" pointer.
);

/**
 * @brief Set item_ to the top ("worst among best") item inside current buffer.
 * @param bufferTop "this" pointer.
 * @param item_ Variable to be assigned.
 * 
 * Usage: void buffertop_first(BufferTop* bufferTop, void item)
 */
#define buffertop_first(bufferTop, item_) \
{ \
	void* pItem = buffertop_first_raw(bufferTop)->item; \
	item_ = *((typeof(&item_))pItem); \
}

/**
 * @brief Remove the top ("worst among best") item-value inside the buffer.
 */
void buffertop_pop(
	BufferTop* bufferTop ///< "this" pointer.
);

/**
 * @brief Clear the entire buffer.
 */
void buffertop_clear(
	BufferTop* bufferTop ///< "this" pointer.
);

/**
 * @brief Destroy the buffer: clear it, and free 'bufferTop' pointer.
 */
void buffertop_destroy(
	BufferTop* bufferTop ///< "this" pointer.
);

#endif