From 04576dc2a3f761eb041b808b56f13a58052e7655 Mon Sep 17 00:00:00 2001
From: Stefan Zabka <zabkaste@hu-berlin.de>
Date: Sun, 24 May 2020 12:19:52 +0200
Subject: Moved back to 02_exercise

---
 02_exercise/array.h | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 142 insertions(+)
 create mode 100644 02_exercise/array.h

(limited to '02_exercise/array.h')

diff --git a/02_exercise/array.h b/02_exercise/array.h
new file mode 100644
index 0000000..78d21c9
--- /dev/null
+++ b/02_exercise/array.h
@@ -0,0 +1,142 @@
+/***************************************************************************//**
+ * @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 */
-- 
cgit v1.2.3-54-g00ecf