Add traceable exception

Author: Bill-hbrhbr

src/ystdlib/error_handling/CMakeLists.txt

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

src/ystdlib/error_handling/SourceLocation.hpp

@@ -0,0 +1,28 @@
+#ifndef YSTDLIB_ERROR_HANDLING_SOURCELOCATION_HPP
+#define YSTDLIB_ERROR_HANDLING_SOURCELOCATION_HPP
+
+#include <iostream>
+#include <source_location>
+
+namespace ystdlib::error_handling {
+class SourceLocation : public std::source_location {
+public:
+    // Constructor
+    constexpr explicit SourceLocation(std::source_location where) : std::source_location{where} {}
+
+#ifdef YSTDLIB_CPP_PROJECT_SOURCE_PATH_SIZE
+    [[nodiscard]] auto file_name() const -> char const* {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-bounds-pointer-arithmetic)
+        return std::source_location::file_name() + YSTDLIB_CPP_PROJECT_SOURCE_PATH_SIZE;
+    }
+#endif
+
+    friend std::ostream& operator<<(std::ostream& os, SourceLocation const& where) {
+        os << where.file_name() << "(" << where.line() << ":" << where.column() << "), function `"
+           << where.function_name() << "`";
+        return os;
+    }
+};
+}  // namespace ystdlib::error_handling
+
+#endif  // YSTDLIB_ERROR_HANDLING_SOURCELOCATION_HPP

src/ystdlib/error_handling/TraceableException.hpp

@@ -0,0 +1,81 @@
+#ifndef YSTDLIB_ERROR_HANDLING_TRACEABLEEXCEPTION_HPP
+#define YSTDLIB_ERROR_HANDLING_TRACEABLEEXCEPTION_HPP
+
+#include <concepts>
+#include <exception>
+#include <source_location>
+#include <stacktrace>
+#include <string>
+#include <system_error>
+
+#include "SourceLocation.hpp"
+
+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>;
+
+/**
+ * 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 <typename ErrorCodeType>
+class TraceableException : public std::exception, public std::source_location {
+public:
+    // Constructors
+    explicit TraceableException(
+            ErrorCodeType error_code,
+            std::source_location const& where = std::source_location::current()
+    )
+            : TraceableException{std::move(error_code), where.function_name(), where} {}
+
+    explicit TraceableException(
+            ErrorCodeType 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 -> ErrorCodeType { return m_error_code; }
+
+    [[nodiscard]] auto what() -> std::string& { return m_what; }
+
+    [[nodiscard]] auto where() const noexcept -> SourceLocation const& { return m_where; }
+
+private:
+    // Variables
+    ErrorCodeType const m_error_code;
+    std::string m_what;
+    SourceLocation const 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, 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,60 @@
+#include <cassert>
+#include <iostream>
+
+#include <ystdlib/error_handling/TraceableException.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 has failed."};
+}  // namespace
+
+namespace ystdlib::error_handling::test {
+class Worker {
+public:
+    YSTDLIB_ERROR_HANDLING_DEFINE_TRACEABLE_EXCEPTION(OperationFailed, BinaryErrorCode);
+
+    static auto execute_with_success() -> void {
+        throw OperationFailed(BinaryErrorCode{BinaryErrorCodeEnum::Success});
+    }
+
+    static auto execute_with_failure() -> void {
+        // clang-format off
+        throw OperationFailed(BinaryErrorCode{BinaryErrorCodeEnum::Failure}, cCustomFailureDescription);
+        // clang-format on
+    }
+
+    // static auto execute_with_invalid_args() -> void {
+    //     throw OperationFailed(std::make_error_code(std::errc::invalid_argument));
+    // }
+};
+}  // namespace ystdlib::error_handling::test
+
+namespace {
+template <ErrorCodeType E, typename Callable>
+[[nodiscard]] auto capture_exception(Callable&& f) -> TraceableException<E>;
+
+template <ErrorCodeType E, typename Callable>
+auto capture_exception(Callable&& f) -> TraceableException<E> {
+    try {
+        std::forward<Callable>(f)();
+    } catch (TraceableException<E>& 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]") {
+    REQUIRE(1 == 1);
+    auto const ex{capture_exception<BinaryErrorCode>(Worker::execute_with_success)};
+    std::cout << ex.where().file_name() << std::endl;
+    std::cout << ex.where() << std::endl;
+}
+}  // namespace ystdlib::error_handling::test