/***************************************************************************//**
 * @file array.h
 * @author Dorian Weber
 * @brief Generischer Array-Typ.
 * 
 * @details
 * Diese Datei enthält die Schnittstelle eines generischen Array-Typs. Um den
 * Element-Typ des Arrays festzulegen, deklariert man eine Variable als Zeiger
 * auf den Element-Typ. Diese kann danach initialisiert und so benutzt werden,
 * als wäre sie ein Zeiger auf ein Array variabler Länge.
 * 
 * Hier ist ein Nutzungsbeispiel:
 * @code
 * int *array;
 * 
 * arrayInit(array);
 * arrayPush(array) = 1;
 * arrayPush(array) = 2;
 * arrayPush(array) = 3;
 * 
 * while (!arrayIsEmpty(array))
 * 	printf("%i\n", arrayPop(array));
 * 
 * arrayRelease(array);
 * @endcode
 * 
 * Viele der genutzten Funktionen sind in Form von Makros implementiert, die die
 * Variable, die den Zeiger auf das Array hält, aktualisieren, obwohl es so
 * aussieht, als würde sich dieser Wert niemals ändern. Das macht es riskant
 * mehr als einen Zeiger auf das Array zu halten, da jede Vergrößerung des
 * Arrays alle Zeiger auf und in das Array potentiell invalidiert. Obwohl diese
 * Fehlerquelle subtil und äußerst schwer diagnostizierbar ist - es ist eine
 * extrem einfache Abstraktion - führt diese Datenstruktur meiner Meinung nach
 * trotzdem zu einem massiven Produktivitätsgewinn; man sollte sich nur in etwa
 * im Klaren über die unterliegende Implementation sein, um genau die Untermenge
 * von Programmiertechniken auszuwählen, die korrekt funktioniert.
 ******************************************************************************/

#ifndef ARRAY_H_INCLUDED
#define ARRAY_H_INCLUDED

/* *** includes ************************************************************* */

#include <stddef.h>

/* *** structures *********************************************************** */

/**@brief Arrayheader.
 * 
 * Diese Struktur wird jedem Array im Speicher vorangestellt und beinhaltet
 * Informationen über Kapazität und aktuelle Auslastung des Arrays. Die
 * Arrayelemente schließen sich dieser Struktur unmittelbar an, so dass der
 * Nutzer von dieser versteckten Information nichts bemerkt.
 */
typedef struct ArrayHdr
{
	size_t len; /**<@brief Anzahl der Array-Elemente. */
	size_t cap; /**<@brief Kapazität des reservierten Speichers. */
} ArrayHdr;

/* *** interface ************************************************************ */

/**@internal
 * @brief Initialisiert und gibt einen Zeiger auf den Start des Arrays zurück.
 * @param capacity  initiale Kapazität
 * @param size      Größe der Arrayelemente
 * @return ein Zeiger auf den Start des Arrays, falls erfolgreich,\n
 *      \c NULL im Falle eines Speicherfehlers
 */
extern void* arrayInit(size_t capacity, size_t size);

/**@brief Initialisiert ein neues Array.
 * @param self  das Array
 * @return 0, falls keine Fehler bei der Initialisierung aufgetreten sind,\n
 *        -1 ansonsten
 */
#define arrayInit(self) \
	((self = arrayInit(8, sizeof((self)[0]))) == NULL ? -1 : 0)

/**@brief Gibt das Array und alle assoziierten Strukturen frei.
 * @param self  das Array
 */
extern void arrayRelease(void* self);

/**@internal
 * @brief Reserviert Platz für einen neuen Wert im Array.
 * @param self  das Array
 * @param size  Größe der Arrayelemente
 * @return der neue Zeiger auf den Start des Arrays
 */
extern void* arrayPush(void* self, size_t size);

/**@brief Legt einen Wert auf das Array.
 * @param self  das Array
 */
#define arrayPush(self) \
	(self = arrayPush(self, sizeof((self)[0])), (self)+arrayLen(self)-1)[0]

/**@brief Entfernt das oberste Element des Arrays.
 * @param self  das Array
 */
extern void arrayPop(void* self);

/**@brief Entfernt und liefert das oberste Element des Arrays.
 * @param self  das Array
 * @return das oberste Element von \p self
 */
#define arrayPop(self) \
	(arrayPop(self), (self)+arrayLen(self))[0]

/**@brief Gibt das oberste Element des Arrays zurück.
 * @param self  das Array
 * @return das oberste Element von \p self
 */
#define arrayTop(self) \
	(self)[arrayLen(self) - 1]

/**@brief Setzt die Länge des Arrays auf 0 zurück.
* @param self  das Array
*/
inline void arrayClear(void* self) {
	((ArrayHdr*) self)[-1].len = 0;
}

/**@brief Gibt zurück, ob das Array leer ist.
 * @param self  das Array
 * @return 0, falls nicht leer\n
           1, falls leer
 */
inline int arrayIsEmpty(const void* self) {
	return ((ArrayHdr*) self)[-1].len == 0;
}

/**@brief Gibt die Anzahl der Array-Elemente zurück.
 * @param self  das Array
 * @return Anzahl der Elemente des Arrays
 */
inline size_t arrayLen(const void* self) {
	return ((ArrayHdr*) self)[-1].len;
}

#endif /* ARRAY_H_INCLUDED */