Initial Commit

2026-08-25 06:38:37 -05:00
commit b1ce7c090d
5 changed files with 186 additions and 0 deletions
@@ -0,0 +1,111 @@
+/**
+ * @file assert.h
+ * @brief Contains the definitions for various types of the library and
+ *        declarations for functions that make the library work.
+ * @author John Christman (sorakatadzuma@gmail.com)
+ * @copyright Malunal Studios, LLC.
+ */
+#include "malunal/types/bool.h"
+#include "malunal/types/integer.h"
+#include "malunal/types/string.h"
+
+#ifndef MALUNAL_ASSERT_HEADER
+#define MALUNAL_ASSERT_HEADER
+
+/**
+ * @def     assert
+ * @brief   A preprocessor macro which can test and throw an assertion.
+ * @details This will eventually call @c assert_test which will test the
+ *          assertion formally and throw the assertion if necessary.
+ * @param   cond The condition that should be tested.
+ */
+#ifdef MALUNAL_ENABLE_ASSERTIONS
+#define assert(cond) \
+  assertmsg(cond, (malunal_cstr_t)0)
+#else /* Do not enable assertions. */
+#define assert(cond)
+#endif /* MALUNAL_ENABLE_ASSERTIONS */
+
+/**
+ * @def     assertmsg
+ * @brief   A preprocessor macro which can test and throw an assertion.
+ * @details This is the same as @c assert but with the added benefit that it
+ *          can provide an additional developer message.
+ * @param   cond The condition that should be tested.
+ * @param   msg  The developer message to add to error message.
+ */
+#ifdef MALUNAL_ENABLE_ASSERTIONS
+#define assertmsg(cond, msg) \
+  assert_test(cond, #cond, msg, __FILE__, __LINE__)
+#else /* Do not enable assertions. */
+#define assertmsg(cond, msg)
+#endif /* MALUNAL_ENABLE_ASSERTIONS */
+
+
+/**
+ * @brief   A function pointer type declaration.
+ * @details Allows the ability to handle an assertion failure manually instead
+ *          of the application automatically dumping and exiting.
+ * @param   expr Why the assertion failed.
+ * @param   msg  Why the assertion failed, extra.
+ * @param   file The file in which the assertion failed.
+ * @param   line the line in which the assertion failed.
+ */
+typedef malunal_void_t
+(*assertion_handler_pfn_t)(
+  malunal_cstr_t  expr,
+  malunal_cstr_t  msg,
+  malunal_cstr_t  file,
+  malunal_int32_t line
+);
+
+/**
+ * @brief   Sets the global assertion handler.
+ * @details Provides the capability for developers to catch an assertion and
+ *          handle it manually instead of the application automatically dumping
+ *          and exiting.
+ * @param   handler The pointer to the function which will handle the assertion.
+ */
+malunal_void_t
+assertion_handler(
+  assertion_handler_pfn_t handler
+);
+
+/**
+ * @brief   Tests the given condition.
+ * @details When the condition fails, this will pass the information to the
+ *          failure function which is responsible for handling the failure.
+ * @param   cond The condition being asserted.
+ * @param   expr The expression being asserted.
+ * @param   msg  The developer message about the assertion.
+ * @param   file The file in which the assertion is taking place.
+ * @param   line The line in which the assertion is taking place.
+ */
+malunal_void_t
+assert_test(
+  malunal_bool_t  cond,
+  malunal_cstr_t  expr,
+  malunal_cstr_t  msg,
+  malunal_cstr_t  file,
+  malunal_int32_t line
+);
+
+/**
+ * @brief   Reports that an assertion has failed.
+ * @details This will pass the information to the global assertion handler if
+ *          one is set, otherwise it will print the error message and abort the
+ *          application.
+ * @param   expr The expression that failed.
+ * @param   msg  The developer message about the assertion.
+ * @param   file The file in which the assertion failed.
+ * @param   line The line in which the assertion failed.
+ */
+malunal_void_t
+assert_failed(
+  malunal_cstr_t  expr,
+  malunal_cstr_t  msg,
+  malunal_cstr_t  file,
+  malunal_int32_t line
+);
+
+#endif /* MALUNAL_ASSERT_HEADER */