Refactor the project

Refactored core logic to improve readability and maintainability.
Documented the 'transient.c' file to provide clear explanations of its purpose and functions.
Updated the 'util.c' file with necessary comments and improvements to existing code.
Documented the 'util.h' header file to clarify function prototypes and usage.

This update should improve the overall code quality and make it easier for future development.

Signed-off-by: philw <dscr@duck.com>

1 files changed, 59 insertions, 0 deletions

diff --git a/src/util/util.h b/src/util/util.h
new file mode 100644
index 0000000..6ef3c86
--- /dev/null
+++ b/src/util/util.h
@@ -0,0 +1,59 @@
+/* See LICENSE file for copyright and license details. */
+
+/*
+ * MAX(A, B)
+ * Macro to compute the maximum of two values.
+ * It returns the greater of the two values, A or B.
+ * Usage: MAX(3, 5) -> 5
+ */
+#define MAX(A, B) ((A) > (B) ? (A) : (B))
+
+/*
+ * MIN(A, B)
+ * Macro to compute the minimum of two values.
+ * It returns the lesser of the two values, A or B.
+ * Usage: MIN(3, 5) -> 3
+ */
+#define MIN(A, B) ((A) < (B) ? (A) : (B))
+
+/*
+ * BETWEEN(X, A, B)
+ * Macro to check if a value X is between two values A and B (inclusive).
+ * It returns true (1) if X is between A and B, and false (0) otherwise.
+ * Usage: BETWEEN(4, 1, 5) -> 1 (true), BETWEEN(6, 1, 5) -> 0 (false)
+ */
+#define BETWEEN(X, A, B) ((A) <= (X) && (X) <= (B))
+
+/*
+ * die()
+ * Function to print an error message and terminate the program.
+ * Takes a formatted string (`fmt`) and additional arguments (as in `printf`).
+ * This function uses variable arguments and will print the formatted error
+ * message to `stderr` and then exit the program with a non-zero status
+ * (typically 1).
+ *
+ * Usage:
+ *   die("Error occurred in function %s", __func__);
+ */
+void die(const char *fmt, ...);
+
+/*
+ * ecalloc()
+ * Function to allocate memory for an array of elements, initializing the memory
+ * to zero. This function works like `calloc()`, but it adds error handling. If
+ * memory allocation fails, it will call the `die()` function to print an error
+ * message and terminate the program.
+ *
+ * Parameters:
+ *   - `nmemb`: The number of elements to allocate memory for.
+ *   - `size`: The size of each element in bytes.
+ *
+ * Returns:
+ *   - A pointer to the allocated memory (of type `void *`).
+ *   - If the allocation fails, the program will terminate via `die()`.
+ *
+ * Usage:
+ *   int *arr = ecalloc(10, sizeof(int));  // Allocate memory for an array of 10
+ * integers.
+ */
+void *ecalloc(size_t nmemb, size_t size);