feat(error_handling): Migrate TraceableException from CLP with changes:

src/ystdlib/error_handling/CMakeLists.txt

@@ -3,9 +3,13 @@ cpp_library(
     NAMESPACE ystdlib
     PUBLIC_HEADERS
         ErrorCode.hpp
+        TraceableException.hpp
+        types.hpp
+        utils.hpp
     TESTS_SOURCES
         test/constants.hpp
         test/test_ErrorCode.cpp
+        test/test_TraceableException.cpp
         test/types.cpp
         test/types.hpp
 )

src/ystdlib/error_handling/TraceableException.hpp

@@ -0,0 +1,83 @@
+#ifndef YSTDLIB_ERROR_HANDLING_TRACEABLEEXCEPTION_HPP
+#define YSTDLIB_ERROR_HANDLING_TRACEABLEEXCEPTION_HPP
+
+#include <exception>
+#include <source_location>
+#include <sstream>
+#include <string>
+#include <system_error>
+#include <utility>
+
+#include "types.hpp"
+#include "utils.hpp"
+
+namespace ystdlib::error_handling {
+/**
+ * An exception class that is thrown with an `std::error_code`.
+ *
+ * This class extends `std::exception` and can be thrown with an `std::error_code` argument. It also
+ * provides additional information to aid in debugging by storing details in `std::source_location`,
+ * including the function name, file name, and line number of the throwing location.
+ *
+ * @see std::source_location::file_name()
+ * @see std::source_location::function_name()
+ * @see std::source_location::line()
+ */
+template <ErrorCodeType ErrorType = std::error_code>
+class TraceableException : public std::exception {
+public:
+    // Constructors
+    explicit TraceableException(
+            ErrorType error_code,
+            std::source_location const& where = std::source_location::current()
+    )
+            : m_error_code{std::move(error_code)},
+              m_where{where} {
+        std::ostringstream oss;
+        oss << where;
+        m_what = oss.str();
+    }
+
+    explicit TraceableException(
+            ErrorType error_code,
+            std::string what,
+            std::source_location const& where = std::source_location::current()
+    )
+            : m_error_code{std::move(error_code)},
+              m_what{std::move(what)},
+              m_where{where} {}
+
+    // Methods implementing std::exception
+    [[nodiscard]] auto what() const noexcept -> char const* override { return m_what.c_str(); }
+
+    // Methods
+    [[nodiscard]] auto error_code() const -> ErrorType { return m_error_code; }
+
+    [[nodiscard]] auto what() -> std::string& { return m_what; }
+
+    [[nodiscard]] auto where() const noexcept -> std::source_location const& { return m_where; }
+
+private:
+    // Variables
+    ErrorType m_error_code;
+    std::string m_what;
+    std::source_location m_where;
+};
+}  // namespace ystdlib::error_handling
+
+/**
+ * The macro to define a `TraceableException` class with the given class name T.
+ */
+// NOLINTBEGIN(bugprone-macro-parentheses, cppcoreguidelines-macro-usage)
+#define YSTDLIB_ERROR_HANDLING_DEFINE_TRACEABLE_EXCEPTION(T) \
+    class T : public ystdlib::error_handling::TraceableException<> { \
+        using ystdlib::error_handling::TraceableException<>::TraceableException; \
+    }
+
+#define YSTDLIB_ERROR_HANDLING_DEFINE_TRACEABLE_EXCEPTION_WITH_ERROR_TYPE(T, E) \
+    class T : public ystdlib::error_handling::TraceableException<E> { \
+        using ystdlib::error_handling::TraceableException<E>::TraceableException; \
+    }
+// NOLINTEND(bugprone-macro-parentheses, cppcoreguidelines-macro-usage)
+
+#endif  // YSTDLIB_ERROR_HANDLING_TRACEABLEEXCEPTION_HPP

src/ystdlib/error_handling/test/test_TraceableException.cpp

@@ -0,0 +1,69 @@
+#include <cassert>
+#include <cstring>
+
+#include <ystdlib/error_handling/TraceableException.hpp>
+#include <ystdlib/error_handling/types.hpp>
+
+#include <catch2/catch_test_macros.hpp>
+
+#include "types.hpp"
+
+using ystdlib::error_handling::ErrorCodeType;
+using ystdlib::error_handling::TraceableException;
+
+namespace {
+constexpr auto cCustomFailureDescription{"This operation failed due to invalid args."};
+constexpr auto cCurrentFileName{"src/ystdlib/error_handling/test/test_TraceableException.cpp"};
+constexpr auto cSuccessFuncName{
+        "static void ystdlib::error_handling::test::Worker::execute_with_success()"
+};
+constexpr auto cFailureFuncName{
+        "static void ystdlib::error_handling::test::Worker::execute_with_failure()"
+};
+}  // namespace
+
+namespace ystdlib::error_handling::test {
+class Worker {
+public:
+    YSTDLIB_ERROR_HANDLING_DEFINE_TRACEABLE_EXCEPTION(OperationFailed);
+
+    static auto execute_with_success() -> void {
+        throw OperationFailed(BinaryErrorCode{BinaryErrorCodeEnum::Success});
+    }
+
+    static auto execute_with_failure() -> void {
+        throw OperationFailed(
+                BinaryErrorCode{BinaryErrorCodeEnum::Failure},
+                cCustomFailureDescription
+        );
+    }
+};
+}  // namespace ystdlib::error_handling::test
+
+namespace {
+template <ErrorCodeType ErrorType = std::error_code, typename Callable>
+[[nodiscard]] auto capture_exception(Callable&& f) -> TraceableException<ErrorType>;
+
+template <ErrorCodeType ErrorType, typename Callable>
+auto capture_exception(Callable&& f) -> TraceableException<ErrorType> {
+    try {
+        std::forward<Callable>(f)();
+    } catch (TraceableException<ErrorType>& e) {
+        return e;
+    }
+    assert(false && "The function is expected to throw.");
+}
+}  // namespace
+
+namespace ystdlib::error_handling::test {
+TEST_CASE("test_traceable_exception", "[error_handling][TraceableException]") {
+    auto const ex_success{capture_exception<>(Worker::execute_with_success)};
+    REQUIRE(std::string{ex_success.where().file_name()}.ends_with(cCurrentFileName));
+    REQUIRE((0 == std::strcmp(ex_success.where().function_name(), cSuccessFuncName)));
+
+    auto const ex_failure{capture_exception<>(Worker::execute_with_failure)};
+    REQUIRE((0 == std::strcmp(ex_failure.what(), cCustomFailureDescription)));
+    REQUIRE(std::string{ex_failure.where().file_name()}.ends_with(cCurrentFileName));
+    REQUIRE((0 == std::strcmp(ex_failure.where().function_name(), cFailureFuncName)));
+}
+}  // namespace ystdlib::error_handling::test

src/ystdlib/error_handling/types.hpp

@@ -0,0 +1,17 @@
+#ifndef YSTDLIB_ERROR_HANDLING_TYPES_HPP
+#define YSTDLIB_ERROR_HANDLING_TYPES_HPP
+
+#include <concepts>
+#include <system_error>
+
+namespace ystdlib::error_handling {
+/**
+ * Concept that defines a template parameter of an integer-based error code enumeration.
+ * @tparam Type
+ */
+template <typename Type>
+concept ErrorCodeType
+        = std::same_as<Type, std::error_code> || std::convertible_to<Type, std::error_code>;
+}  // namespace ystdlib::error_handling
+
+#endif  // YSTDLIB_ERROR_HANDLING_TYPES_HPP

src/ystdlib/error_handling/utils.hpp

@@ -0,0 +1,14 @@
+#ifndef YSTDLIB_ERROR_HANDLING_UTILS_HPP
+#define YSTDLIB_ERROR_HANDLING_UTILS_HPP
+
+#include <ostream>
+#include <source_location>
+
+namespace ystdlib::error_handling {
+inline auto operator<<(std::ostream& os, std::source_location const& where) -> std::ostream& {
+    return os << where.file_name() << "(" << where.line() << ":" << where.column()
+              << "), function `" << where.function_name() << "`";
+}
+}  // namespace ystdlib::error_handling
+
+#endif  // YSTDLIB_ERROR_HANDLING_UTILS_HPP