draft: Add error handling libs, including ErrorCode and TraceableException.

.github/workflows/unit-tests.yaml

@@ -21,7 +21,8 @@ jobs:
     strategy:
       matrix:
         os:
-          - "macos-latest"
+          - "macos-14"
+          - "macos-15"
           - "ubuntu-20.04"
           - "ubuntu-22.04"
           - "ubuntu-24.04"
@@ -39,27 +40,60 @@ jobs:
         shell: "bash"
         run: "npm install -g @go-task/cli"
 
-      - if: "matrix.os == 'macos-latest'"
+      - if: "matrix.os == 'macos-14'"
         name: "Install coreutils (for md5sum)"
         run: "brew install coreutils"
 
+      - if: "matrix.os == 'macos-14'"
+        name: "Install clang-16 (for c++20)"
+        run: |-
+          brew install llvm@16
+          echo "export CC=/opt/homebrew/opt/llvm@16/bin/clang" >> /Users/runner/.bashrc
+          echo "export CXX=/opt/homebrew/opt/llvm@16/bin/clang++" >> /Users/runner/.bashrc
+
       - if: "matrix.os == 'ubuntu-20.04'"
         name: "Install gcc-10 (for c++20)"
         run: |-
           sudo apt-get update
           sudo DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends -y \
-              g++-10 \
-              gcc-10
-          sudo ln --symbolic --force /usr/bin/gcc-10 /usr/bin/cc
-          sudo ln --symbolic --force /usr/bin/g++-10 /usr/bin/c++
-          sudo ln --symbolic --force /usr/bin/cpp-10 /usr/bin/cpp
+              bzip2 \
+              flex
+          cd ~
+          curl -L -o gcc-11.4.0.tar.gz \
+              https://github.com/gcc-mirror/gcc/archive/refs/tags/releases/gcc-11.4.0.tar.gz
+          tar -xzf gcc-11.4.0.tar.gz
+          cd gcc-releases-gcc-11.4.0
+          sudo ./contrib/download_prerequisites
+          mkdir build
+          cd build
+          ../configure -v \
+              --build=x86_64-linux-gnu \
+              --host=x86_64-linux-gnu \
+              --target=x86_64-linux-gnu \
+              --prefix=/usr/local/gcc-11.4.0 \
+              --enable-checking=release \
+              --enable-languages=c,c++,fortran \
+              --disable-multilib \
+              --program-suffix=-11.4
+          make -j$(nproc)
+          make install PREFIX=/usr/local/gcc-11.4.0/bin
+          sudo ln --symbolic --force /usr/local/gcc-11.4.0/bin/gcc-11.4 /usr/bin/cc
+          sudo ln --symbolic --force /usr/local/gcc-11.4.0/bin/g++-11.4 /usr/bin/c++
+          sudo ln --symbolic --force /usr/local/gcc-11.4.0/bin/cpp-11.4 /usr/bin/cpp
 
       - name: "Log tool versions"
         run: |-
-          command -v md5sum
-          command -v python
-          command -v tar
-          command -v task
+          [ -n "$ZSH_VERSION" ] && source ~/.zshrc || { [ -n "$BASH_VERSION" ] && source ~/.bashrc; }
+          clang --version
+          g++ --version
+          gcc --version
+          md5sum --version
+          python --version
+          tar --version
+          task --version
 
       - name: "Run unit tests"
-        run: "task test-all"
+        run: |-
+          [ -n "$ZSH_VERSION" ] && source ~/.zshrc || { [ -n "$BASH_VERSION" ] && source ~/.bashrc; }
+          task clean
+          task test-all

CMakeLists.txt

@@ -13,6 +13,11 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS
 
 option(BUILD_TESTING "If ON, unit tests will be built." ON)
 
+# Macro providing the length of the absolute source directory path so we can output file name
+# information with relative (rather than absolute) paths.
+string(LENGTH "${CMAKE_SOURCE_DIR}/" SOURCE_PATH_SIZE)
+add_definitions("-DSOURCE_PATH_SIZE=${SOURCE_PATH_SIZE}")
+
 # Import CMake helper functions
 list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR}/CMake)
 

src/ystdlib/CMakeLists.txt

@@ -1 +1 @@
-add_subdirectory(testlib)
+add_subdirectory(error_handling)

src/ystdlib/error_handling/CMakeLists.txt

@@ -0,0 +1,9 @@
+cpp_library(
+    NAME error_handling
+    NAMESPACE ystdlib
+    TESTS_SOURCES
+        test-Defs.hpp
+        test-Defs.cpp
+        test-ErrorCode.cpp
+        test-TraceableException.cpp
+)

src/ystdlib/error_handling/ErrorCode.hpp

@@ -0,0 +1,148 @@
+#ifndef YSTDLIB_ERROR_HANDLING_ERRORCODE_HPP
+#define YSTDLIB_ERROR_HANDLING_ERRORCODE_HPP
+
+#include <concepts>
+#include <string>
+#include <system_error>
+#include <type_traits>
+
+namespace ystdlib::error_handling {
+/**
+ * Concept that defines a template parameter of an integer-based error code enumeration.
+ * @tparam Type
+ */
+template <typename Type>
+concept ErrorCodeEnumType = std::is_enum_v<Type> && requires(Type type) {
+    {
+        static_cast<std::underlying_type_t<Type>>(type)
+    } -> std::convertible_to<int>;
+};
+
+/**
+ * Template that defines a `std::error_category` of the given set of error code enumeration.
+ * @tparam ErrorCodeEnum
+ */
+template <ErrorCodeEnumType ErrorCodeEnum>
+class ErrorCategory : public std::error_category {
+public:
+    // Methods implementing `std::error_category`
+    /**
+     * Gets the error category name.
+     * Note: A specialization must be explicitly implemented for each valid `ErrorCodeEnum`.
+     * @return The name of the error category.
+     */
+    [[nodiscard]] auto name() const noexcept -> char const* override;
+
+    /**
+     * Gets the descriptive message associated with the given error.
+     * @param error_num
+     * @return The descriptive message for the error.
+     */
+    [[nodiscard]] auto message(int error_num) const -> std::string override {
+        return message(static_cast<ErrorCodeEnum>(error_num));
+    }
+
+    /**
+     * @param error_num
+     * @param condition
+     * @return Whether the error condition of the given error matches the given condition.
+     */
+    [[nodiscard]] auto
+    equivalent(int error_num, std::error_condition const& condition) const noexcept
+            -> bool override {
+        return equivalent(static_cast<ErrorCodeEnum>(error_num), condition);
+    }
+
+    // Methods
+    /**
+     * Gets the descriptive message associated with the given error.
+     * Note: A specialization must be explicitly implemented for each valid `ErrorCodeEnum`.
+     * @param error_enum.
+     * @return The descriptive message for the error.
+     */
+    [[nodiscard]] auto message(ErrorCodeEnum error_enum) const -> std::string;
+
+    /**
+     * Note: A specialization can be implemented to create error enum to error condition mappings.
+     * @param error_num
+     * @param condition
+     * @return Whether the error condition of the given error matches the given condition.
+     */
+    [[nodiscard]] auto
+    equivalent(ErrorCodeEnum error_enum, std::error_condition const& condition) const noexcept
+            -> bool;
+};
+
+/**
+ * Template class that defines an error code. An error code is represented by a error enum value and
+ * the associated error category. This template class is designed to be `std::error_code`
+ * compatible, meaning that every instance of this class can be used to construct a corresponded
+ * `std::error_code` instance, or compare with a `std::error_code` instance to inspect a specific
+ * error.
+ * @tparam ErrorCodeEnum
+ */
+template <ErrorCodeEnumType ErrorCodeEnum>
+class ErrorCode {
+public:
+    // Constructor
+    ErrorCode(ErrorCodeEnum error) : m_error{error} {}
+
+    /**
+     * @return The underlying error code enum.
+     */
+    [[nodiscard]] auto get_error() const -> ErrorCodeEnum { return m_error; }
+
+    /**
+     * @return The error code as an error number.
+     */
+    [[nodiscard]] auto get_error_num() const -> int { return static_cast<int>(m_error); }
+
+    /**
+     * @return The reference to the singleton of the corresponded error category.
+     */
+    [[nodiscard]] constexpr static auto get_category() -> ErrorCategory<ErrorCodeEnum> const& {
+        return cCategory;
+    }
+
+private:
+    static inline ErrorCategory<ErrorCodeEnum> const cCategory;
+
+    ErrorCodeEnum m_error;
+};
+
+/**
+ * @tparam ErrorCodeEnum
+ * @param error
+ * @return Constructed `std::error_code` from the given `ErrorCode` instance.
+ */
+template <typename ErrorCodeEnum>
+[[nodiscard]] auto make_error_code(ErrorCode<ErrorCodeEnum> error) -> std::error_code;
+
+template <ErrorCodeEnumType ErrorCodeEnum>
+auto ErrorCategory<ErrorCodeEnum>::equivalent(
+        ErrorCodeEnum error_enum,
+        std::error_condition const& condition
+) const noexcept -> bool {
+    return std::error_category::default_error_condition(static_cast<int>(error_enum)) == condition;
+}
+
+template <typename ErrorCodeEnum>
+auto make_error_code(ErrorCode<ErrorCodeEnum> error) -> std::error_code {
+    return {error.get_error_num(), ErrorCode<ErrorCodeEnum>::get_category()};
+}
+}  // namespace ystdlib::error_handling
+
+/**
+ * The macro to create a specialization of `std::is_error_code_enum` for a given type T. Only types
+ * that are marked with this macro will be considered as a valid YStdlib error code enum, and thus
+ * used to specialize `ErrorCode` and `ErrorCategory` templates.
+ */
+// NOLINTBEGIN(bugprone-macro-parentheses, cppcoreguidelines-macro-usage)
+#define YSTDLIB_ERROR_HANDLING_MARK_AS_ERROR_CODE_ENUM(T) \
+    template <> \
+    struct std::is_error_code_enum<ystdlib::error_handling::ErrorCode<T>> : std::true_type { \
+        static_assert(std::is_enum_v<T>); \
+    };
+// NOLINTEND(bugprone-macro-parentheses, cppcoreguidelines-macro-usage)
+
+#endif  // YSTDLIB_ERROR_HANDLING_ERRORCODE_HPP

src/ystdlib/error_handling/TraceableException.hpp

@@ -0,0 +1,70 @@
+#ifndef YSTDLIB_ERROR_HANDLING_TRACEABLEEXCEPTION_HPP
+#define YSTDLIB_ERROR_HANDLING_TRACEABLEEXCEPTION_HPP
+
+#include <exception>
+#include <source_location>
+#include <string>
+#include <system_error>
+
+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()
+ */
+class TraceableException : public std::exception, public std::source_location {
+public:
+    // Constructors
+    explicit TraceableException(
+            std::error_code error_code,
+            std::source_location const& location = std::source_location::current()
+    )
+            : TraceableException{error_code, location.function_name(), location} {}
+
+    explicit TraceableException(
+            std::error_code error_code,
+            std::string const& what,
+            std::source_location const& location = std::source_location::current()
+    )
+            : std::source_location{location},
+              m_error_code{error_code},
+              m_what{what} {}
+
+    // Methods
+    [[nodiscard]] auto error_code() const -> std::error_code { return m_error_code; }
+
+#ifdef SOURCE_PATH_SIZE
+    [[nodiscard]] auto file_name() const -> char const* {
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-bounds-pointer-arithmetic)
+        return std::source_location::file_name() + SOURCE_PATH_SIZE;
+    }
+#endif
+
+    // Methods implementing std::exception
+    [[nodiscard]] auto what() const noexcept -> char const* override { return m_what.c_str(); }
+
+private:
+    // Variables
+    std::error_code m_error_code;
+    std::string m_what;
+};
+
+}  // 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; \
+    }
+// NOLINTEND(bugprone-macro-parentheses, cppcoreguidelines-macro-usage)
+
+#endif  // YSTDLIB_ERROR_HANDLING_TRACEABLEEXCEPTION_HPP

src/ystdlib/error_handling/test-Defs.cpp

@@ -0,0 +1,57 @@
+#include "test-Defs.hpp"
+
+#include <algorithm>
+#include <array>
+#include <string>
+#include <string_view>
+#include <system_error>
+
+template <>
+auto AlwaysSuccessErrorCategory::name() const noexcept -> char const* {
+    return cAlwaysSuccessErrorCategoryName.data();
+}
+
+template <>
+auto AlwaysSuccessErrorCategory::message(AlwaysSuccessErrorCodeEnum error_enum) const
+        -> std::string {
+    switch (error_enum) {
+        case AlwaysSuccessErrorCodeEnum::Success:
+            return std::string{cSuccessErrorMsg};
+        default:
+            return std::string{cUnrecognizedErrorCode};
+    }
+}
+
+template <>
+auto BinaryErrorCategory::name() const noexcept -> char const* {
+    return cBinaryTestErrorCategoryName.data();
+}
+
+template <>
+auto BinaryErrorCategory::message(BinaryErrorCodeEnum error_enum) const -> std::string {
+    switch (error_enum) {
+        case BinaryErrorCodeEnum::Success:
+            return std::string{cSuccessErrorMsg};
+        case BinaryErrorCodeEnum::Failure:
+            return std::string{cFailureErrorMsg};
+        default:
+            return std::string{cUnrecognizedErrorCode};
+    }
+}
+
+template <>
+auto BinaryErrorCategory::equivalent(
+        BinaryErrorCodeEnum error_enum,
+        std::error_condition const& condition
+) const noexcept -> bool {
+    switch (error_enum) {
+        case BinaryErrorCodeEnum::Failure:
+            return std::ranges::any_of(
+                    cFailureConditions.cbegin(),
+                    cFailureConditions.cend(),
+                    [&](auto failure_condition) -> bool { return condition == failure_condition; }
+            );
+        default:
+            return false;
+    }
+}