Restliche Kommentare eingefügt

numbers.c

@@ -1,3 +1,4 @@
+
 #include <stdlib.h>
 #include <stdio.h>
 #include <time.h>
@@ -5,7 +6,17 @@
 #include "numbers.h"
 #include "bintree.h"
 
-// helper comparator for unsigned int for bintree
+/**
+ * @brief Vergleichsfunktion für unsigned int-Werte zur Verwendung im Binärbaum.
+ *
+ * Diese Funktion wird von der Binärbaum-Implementierung genutzt, um die
+ * Ordnung der Knoten zu bestimmen. Sie vergleicht die dereferenzierten
+ * unsigned int-Werte a und b.
+ *
+ * @param a Pointer auf einen unsigned int-Wert (linker Operand)
+ * @param b Pointer auf einen unsigned int-Wert (rechter Operand)
+ * @return -1, falls *a < *b; 1, falls *a > *b; 0, falls *a == *b
+ */
 static int compareUInt(const void *a, const void *b)
 {
     unsigned int va = *(const unsigned int *)a;
@@ -15,7 +26,13 @@ static int compareUInt(const void *a, const void *b)
     return 0;
 }
 
-// comparator for qsort (unsigned int)
+/**
+ * @brief Vergleichsfunktion für qsort() zur Sortierung von unsigned int-Arrays.
+ *
+ * @param a Pointer auf einen Arrayeintrag
+ * @param b Pointer auf einen Arrayeintrag
+ * @return -1, 0, 1 analog zu compareUInt()
+ */
 static int qsort_uint_cmp(const void *a, const void *b)
 {
     unsigned int va = *(const unsigned int *)a;
@@ -25,9 +42,39 @@ static int qsort_uint_cmp(const void *a, const void *b)
     return 0;
 }
 
-// Returns len random numbers between 1 and 2x len in random order which are all different, except for two entries.
-// Returns NULL on errors. Use your implementation of the binary search tree to check for possible duplicates while
-// creating random numbers.
+/**
+ * @brief Erzeugt ein Array aus len Zufallszahlen im Bereich [1 .. 2*len],
+ *        das genau einen duplizierten Wert enthält (d. h. len-1 eindeutige + 1 Duplikat),
+ *        und mischt die Reihenfolge zufällig.
+ *
+ * Funktionsweise:
+ * - Es werden zunächst len-1 eindeutige Zufallszahlen erzeugt. Die Eindeutigkeit wird
+ *   mithilfe eines Binärsuchbaums (BST) geprüft: addToTree() fügt die Zahl ein
+ *   und signalisiert per isDup, ob sie bereits vorhanden war.
+ * - Anschließend wird eine der bereits erzeugten Zahlen zufällig ausgewählt und
+ *   noch einmal an das Ende des Arrays geschrieben, um das geforderte Duplikat sicherzustellen.
+ * - Zum Schluss wird das gesamte Array mittels Fisher–Yates-Algorithmus gemischt.
+ *
+ * Fehlerbehandlung:
+ * - Bei len < 2 wird NULL zurückgegeben, da das Problem ein Duplikat erfordert.
+ * - Bei Speicher- oder Baum-Insertionsfehlern wird aufgeräumt und NULL zurückgegeben.
+ *   Wichtig: Der Baumzeiger root wird erst nach erfolgreichem Insert aktualisiert,
+ *   um im Fehlerfall kein bereits aufgebautes Teilbaum-Objekt zu verlieren.
+ *
+ * Randbedingungen / Annahmen:
+ * - addToTree(root, &val, sizeof(val), compareUInt, &isDup) setzt isDup:
+ *   isDup == 1 bedeutet „Duplikat gefunden, Baum unverändert“,
+ *   isDup == 0 bedeutet „neuer Wert eingefügt (oder Fehler)“.
+ * - Bei Speicherfehler gibt addToTree NULL zurück und isDup bleibt 0.
+ * - clearTree(root) darf mit NULL-Argument aufgerufen werden (No-Op).
+ *
+ * Komplexität:
+ * - Durchschnittlich O(len * log(len)) für die len-1 Einfügungen in den BST.
+ * - Shuffle in O(len).
+ *
+ * @param len Anzahl der zu erzeugenden Werte (muss >= 2 sein)
+ * @return Pointer auf ein Array mit len Einträgen bei Erfolg; NULL bei Fehlern
+ */
 unsigned int *createNumbers(unsigned int len)
 {
     if (len < 2)
@@ -37,37 +84,56 @@ unsigned int *createNumbers(unsigned int len)
     if (numbers == NULL)
         return NULL;
 
-    // seed once
+    // Zufallszahlengenerator nur einmal pro Prozess initialisieren.
+    // Hintergrund: Wird createNumbers mehrfach schnell hintereinander gerufen,
+    // kann time(NULL) identische Seeds liefern und damit identische Zahlenfolgen erzeugen.
+    static int seeded = 0;
+    if (!seeded) {
         srand((unsigned int)time(NULL));
+        seeded = 1;
+    }
 
     TreeNode *root = NULL;
     unsigned int range = 2 * len;
-    // create len-1 unique numbers
+
+    // Schritt 1: len-1 eindeutige Zufallszahlen erzeugen
     for (unsigned int i = 0; i < len - 1; i++)
     {
         unsigned int val;
-        int isDup = 0;
-        // try until a unique number is inserted
-        do
-        {
-            val = (unsigned int)(rand() % range) + 1; // [1..2*len]
-            root = addToTree(root, &val, sizeof(val), compareUInt, &isDup);
-            // if addToTree returned NULL due to allocation failure, cleanup and return NULL
-            if(root == NULL && isDup == 0)
+        int isDup;
+
+        // Wiederholen, bis eine wirklich neue Zahl eingefügt wurde
+        for (;;)
         {
+            isDup = 0; // vor jedem Insert zurücksetzen, um „alte“ Werte zu vermeiden
+            val = (unsigned int)(rand() % range) + 1; // Wertebereich [1 .. 2*len]
+
+            // addToTree kann bei Erfolg einen (ggf. neuen) Wurzelzeiger liefern.
+            // Zur Vermeidung eines Speicherlecks bei Fehlern zunächst in temp speichern.
+            TreeNode *newRoot = addToTree(root, &val, sizeof(val), compareUInt, &isDup);
+
+            if (newRoot == NULL && isDup == 0) {
+                // Vermutlich Speicher-/Insertionsfehler: aufräumen und abbrechen
                 free(numbers);
-                clearTree(root);
+                clearTree(root);  // root zeigt noch auf den gültigen Teilbaum
                 return NULL;
             }
-        } while(isDup);
+
+            if (!isDup) {
+                // Einfügen war erfolgreich und der Wert ist eindeutig.
+                root = newRoot;
                 numbers[i] = val;
+                break;
+            }
+            // Andernfalls Duplikat: Neue Zufallszahl versuchen.
+        }
     }
 
-    // duplicate one existing random entry
-    unsigned int idx = (unsigned int)(rand() % (len - 1));
+    // Schritt 2: Eine der bestehenden Zahlen zufällig duplizieren
+    unsigned int idx = (unsigned int)(rand() % (len - 1)); // Index im Bereich [0 .. len-2]
     numbers[len - 1] = numbers[idx];
 
-    // shuffle array (Fisher-Yates)
+    // Schritt 3: Fisher–Yates-Shuffle über das gesamte Array
     for (unsigned int i = len - 1; i > 0; i--)
     {
         unsigned int j = (unsigned int)(rand() % (i + 1));
@@ -76,31 +142,53 @@ unsigned int *createNumbers(unsigned int len)
         numbers[j] = tmp;
     }
 
-    // free tree resources
+    // Aufräumen: Baum freigeben
     clearTree(root);
     return numbers;
 }
 
-// Returns only the only number in numbers which is present twice. Returns zero on errors.
+/**
+ * @brief Findet den einzigen duplizierten Wert in einem Array aus len unsigned int.
+ *
+ * Funktionsweise:
+ * - Es wird eine Kopie des Eingabearrays erstellt, um die Reihenfolge des
+ *   Originalarrays nicht zu verändern.
+ * - Die Kopie wird mittels qsort() aufsteigend sortiert.
+ * - Beim Durchlauf werden benachbarte Elemente verglichen. Da genau ein Wert
+ *   doppelt vorkommt, finden wir ihn als erstes Paar gleicher Nachbarn.
+ *
+ * Fehlerbehandlung:
+ * - Bei ungültigen Parametern (numbers == NULL oder len < 2) wird 0 geliefert.
+ * - Bei Speicherfehlern beim Kopieren ebenfalls 0.
+ *
+ * Komplexität:
+ * - Sortieren in O(len * log(len)), anschließender Linearpass O(len).
+ *
+ * @param numbers Pointer auf das Eingabearray
+ * @param len     Länge des Arrays (muss >= 2 sein)
+ * @return Der doppelte Wert; 0 bei Fehlern oder falls kein Duplikat gefunden wurde
+ *         (gemäß Aufgabenstellung sollte aber genau ein Duplikat existieren).
+ */
 unsigned int getDuplicate(const unsigned int numbers[], unsigned int len)
 {
     if (numbers == NULL || len < 2)
         return 0;
 
-    // make a copy so original array order is not modified by caller expectation
+    // Kopie erstellen, damit das Original unangetastet bleibt
     unsigned int *copy = (unsigned int *)malloc(sizeof(unsigned int) * len);
     if (copy == NULL)
         return 0;
 
     memcpy(copy, numbers, sizeof(unsigned int) * len);
 
+    // Sortieren der Kopie
     qsort(copy, len, sizeof(unsigned int), qsort_uint_cmp);
 
+    // Linearer Scan: erstes Paar identischer Nachbarn ist das Duplikat
     unsigned int result = 0;
     for (unsigned int i = 0; i + 1 < len; i++)
     {
-        if(copy[i] == copy[i+1])
-        {
+        if (copy[i] == copy[i + 1]) {
             result = copy[i];
             break;
         }

test_numbers.c

@@ -1,41 +1,91 @@
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include "numbers.h"
 
+/**
+ * @brief Selbsttest für createNumbers() und getDuplicate().
+ *
+ * Erzeugt ein Array aus len Zufallszahlen mit genau einem duplizierten Wert,
+ * validiert die Eigenschaften per Zähl-Array (Wertebereich, Häufigkeiten)
+ * und prüft anschließend, ob getDuplicate() dasselbe Duplikat ermittelt.
+ *
+ * Rückgabecodes:
+ *  0: OK
+ *  1: createNumbers() fehlgeschlagen
+ *  2: Speicherfehler für counts
+ *  3: Wert außerhalb des Bereichs [1..2*len]
+ *  4: Ein Wert erscheint öfter als zweimal
+ *  5: Nicht genau ein Duplikat gefunden
+ *  6: getDuplicate() liefert anderes Ergebnis als Zählung
+ */
 int main(void)
 {
-    unsigned int len = 100;
+    unsigned int len = 100;              // Anzahl zu erzeugender Zahlen
     unsigned int *nums = createNumbers(len);
-    if(nums == NULL) { fprintf(stderr, "createNumbers returned NULL\n"); return 1; }
+    if (nums == NULL) {
+        fprintf(stderr, "createNumbers returned NULL\n");
+        return 1;                        // Erzeugung fehlgeschlagen
+    }
 
-    // count occurrences
-    unsigned int maxVal = 2 * len;
+    unsigned int maxVal = 2 * len;       // Erlaubter Bereich: [1 .. 2*len]
+
+    // Zähl-Array für Häufigkeiten pro Wert (Index 0 bleibt ungenutzt)
     unsigned int *counts = calloc(maxVal + 1, sizeof(unsigned int));
-    if(counts == NULL) { free(nums); return 2; }
-
-    for(unsigned int i = 0; i < len; i++)
-    {
-        if(nums[i] > maxVal) { fprintf(stderr, "value out of expected range\n"); free(nums); free(counts); return 3; }
-        counts[nums[i]]++;
+    if (counts == NULL) {
+        free(nums);
+        return 2;                        // Speicherfehler bei counts
     }
 
-    int duplicatesFound = 0;
-    unsigned int duplicateValue = 0;
-    for(unsigned int v = 1; v <= maxVal; v++)
-    {
-        if(counts[v] == 2) { duplicatesFound++; duplicateValue = v; }
-        else if(counts[v] > 2) { fprintf(stderr, "value %u appears more than twice\n", v); free(nums); free(counts); return 4; }
-    }
-
-    if(duplicatesFound != 1) { fprintf(stderr, "expected exactly one duplicated value, found %d\n", duplicatesFound); free(nums); free(counts); return 5; }
-
-    unsigned int found = getDuplicate(nums, len);
-    if(found != duplicateValue) { fprintf(stderr, "getDuplicate returned %u expected %u\n", found, duplicateValue); free(nums); free(counts); return 6; }
-
+    // Häufigkeiten bestimmen und gleichzeitig Bereich prüfen
+    for (unsigned int i = 0; i < len; i++) {
+        unsigned int v = nums[i];
+        if (v == 0 || v > maxVal) {      // sollte nicht passieren, wenn createNumbers korrekt ist
+            fprintf(stderr, "value out of expected range\n");
             free(nums);
             free(counts);
+            return 3;
+        }
+        counts[v]++;                     // Auftreten des Werts v zählen
+    }
 
+    // Exakt ein Wert muss doppelt vorkommen; keiner darf >2-mal vorkommen
+    int duplicatesFound = 0;
+    unsigned int duplicateValue = 0;
+
+    for (unsigned int v = 1; v <= maxVal; v++) {
+        if (counts[v] == 2) {
+            duplicatesFound++;
+            duplicateValue = v;          // den doppelten Wert merken
+        } else if (counts[v] > 2) {
+            fprintf(stderr, "value %u appears more than twice\n", v);
+            free(nums);
+            free(counts);
+            return 4;                    // Vertragsbruch: zu häufiges Auftreten
+        }
+        // counts[v] == 0 oder 1 sind unkritisch
+    }
+
+    if (duplicatesFound != 1) {
+        fprintf(stderr, "expected exactly one duplicated value, found %d\n", duplicatesFound);
+        free(nums);
+        free(counts);
+        return 5;                        // zu wenige/zu viele Duplikate
+    }
+
+    // Ergebnis von getDuplicate() mit der Zählung abgleichen
+    unsigned int found = getDuplicate(nums, len);
+    if (found != duplicateValue) {
+        fprintf(stderr, "getDuplicate returned %u expected %u\n", found, duplicateValue);
+        free(nums);
+        free(counts);
+        return 6;                        // Abweichung zwischen Methoden
+    }
+
+    // Ressourcen freigeben und Erfolg melden
+    free(nums);
+    free(counts);
     printf("test_numbers: OK (duplicate = %u)\n", duplicateValue);
     return 0;
 }