Foundations

Foundation/c_KnuthShuffle.t.c

@@ -0,0 +1,101 @@
+#include "c_KnuthShuffle.h"
+#include <stdlib.h>
+#include <stdio.h>
+
+// Advanced Line-Tracing Diagnostic Macro
+#define EXPECT_EQ(actual, expected, msg) \
+    do { \
+        if ((actual) != (expected)) { \
+            printf("  [X] Assert Failed: %s (Expected %d, got %d) %s:%d\n", msg, (int)(expected), (int)(actual), __FILE__, __LINE__); \
+            return C_FALSE; \
+        } \
+    } while(0)
+
+// Complex struct data payload representing simulation cards
+typedef struct {
+    int card_id;
+    char suit;
+} DeckCard;
+
+// External declaration of your framework's Knuth Shuffle module
+extern void c_KnuthShuffle(void* base, c_size_t num, c_size_t size);
+
+/**
+ * Unit Test Profile: Validates extreme boundaries, statistical disordering,
+ * and strict payload preservation without data loss.
+ */
+c_bool_t test_knuth_shuffle_lifecycle(void) {
+    // Seed the standard pseudo-random number generator for the shuffle module
+    srand((unsigned int)time(NULL));
+
+    // Checkpoint 1: Boundary conditions check (Should return safely without crashing)
+    int* null_ptr = NULL;
+    c_KnuthShuffle(null_ptr, 0, sizeof(int)); // NULL pointer escape guard
+
+    int single_array[] = { 99 };
+    c_KnuthShuffle(single_array, 1, sizeof(int));
+    EXPECT_EQ(single_array[0], 99, "Single element array mutated unexpectedly");
+
+    // Initialize an ordered deck array of 10 complex structural cards
+    DeckCard deck[10];
+    c_size_t total_cards = sizeof(deck) / sizeof(deck[0]);
+    char suits[] = {'H', 'D', 'C', 'S'};
+
+    for (c_size_t i = 0; i < total_cards; i++) {
+        deck[i].card_id = (int)(i + 1);
+        deck[i].suit = suits[i % 4];
+    }
+
+    // Clone the original array configuration to verify data preservation metrics later
+    DeckCard deck_snapshot[10];
+    memcpy(deck_snapshot, deck, sizeof(deck));
+
+    printf("  [LOG] Executing c_KnuthShuffle across 10 complex data elements...\n");
+    c_KnuthShuffle(deck, total_cards, sizeof(DeckCard));
+
+    // Checkpoint 2: Verification of statistical mismatch (Disordering check)
+    c_size_t identical_matches = 0;
+    for (c_size_t i = 0; i < total_cards; i++) {
+        if (deck[i].card_id == deck_snapshot[i].card_id) {
+            identical_matches++;
+        }
+    }
+
+    // Mathematically, the probability of a 10-element array remaining completely
+    // identical or barely modified after a fair shuffle is near zero (~1 in 3.6 million).
+    printf("    [STAT] Element slots remaining in original positions: %zu/%zu\n", identical_matches, total_cards);
+    EXPECT_EQ(identical_matches < total_cards, C_TRUE, "Shuffle algorithm failed to re-arrange element configurations");
+
+    // Checkpoint 3: Strict Data Integrity Verification (De-duplication & Conservation check)
+    // Ensure that every single original item still exists inside the shuffled deck exactly once.
+    c_bool_t found_flags[10] = { C_FALSE };
+    c_size_t unique_restored_count = 0;
+
+    for (c_size_t i = 0; i < total_cards; i++) {
+        for (c_size_t j = 0; j < total_cards; j++) {
+            if (deck[i].card_id == deck_snapshot[j].card_id && deck[i].suit == deck_snapshot[j].suit) {
+                if (!found_flags[j]) {
+                    found_flags[j] = C_TRUE;
+                    unique_restored_count++;
+                }
+                break;
+            }
+        }
+    }
+
+    EXPECT_EQ(unique_restored_count, total_cards, "Shuffle step introduced data corruption, duplicates, or element losses");
+    printf("  [PASS] All 10 original complex items conserved perfectly with zero data leakage.\n");
+
+    return C_TRUE;
+}
+
+int main(void) {
+    printf("=== Starting Framework Verification: c_KnuthShuffle ===\n");
+
+    if (test_knuth_shuffle_lifecycle()) {
+        printf("  [PASS] Knuth Linear-Time Shuffle Validation & Payload Conservation Verified.\n");
+    } else {
+        printf("  [FAIL] Shuffle Optimization Pipeline Errors Intercepted.\n");
+    }
+    return 0;
+}