From 9558074af8ceef4dc2c3b168a0263775f8a377e0 Mon Sep 17 00:00:00 2001 From: Felix Morgner Date: Tue, 14 Jul 2026 19:22:01 +0200 Subject: kstd: flesh out system_error documentation --- libs/kstd/kstd/system_error.hpp | 72 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/libs/kstd/kstd/system_error.hpp b/libs/kstd/kstd/system_error.hpp index 77d85172..09efb097 100644 --- a/libs/kstd/kstd/system_error.hpp +++ b/libs/kstd/kstd/system_error.hpp @@ -136,60 +136,93 @@ namespace kstd } }; + //! An error condition represents a generic, system-level error. + //! + //! Error conditions are used to represent errors to be tested for. struct error_condition { + //! Construct an error condition with a default value and category. constexpr error_condition() noexcept; + //! Construct an error condition with a specific value and category. + //! + //! @param value The error code value. + //! @param category The error category. constexpr error_condition(int value, error_category const & category) noexcept : m_value{value} , m_category{&category} {} + //! Construct an error condition from an error condition enumeration value. + //! + //! @tparam Enum The error condition enumeration type. + //! @param value The error condition enumeration value. template constexpr error_condition(Enum value) noexcept : error_condition{make_error_condition(value)} {} + //! Assign an error condition enumeration value to this error condition. + //! + //! @tparam Enum The error condition enumeration type. + //! @param value The error condition enumeration value. template constexpr auto operator=(Enum value) noexcept -> error_condition & { *this = make_error_condition(value); } + //! Assign a new value and category to this error condition. + //! + //! @param value The new error code value. + //! @param category The new error category. constexpr auto assign(int value, error_category const & category) noexcept -> void { m_value = value; m_category = &category; } + //! Clear this error condition. + //! + //! This sets the value to 0 and the category to the generic error category. constexpr auto clear() noexcept -> void; + //! Get the raw error code value of this error condition. [[nodiscard]] constexpr auto value() const noexcept -> int { return m_value; } + //! Get the error category of this error condition. [[nodiscard]] constexpr auto category() const noexcept -> error_category const & { return *m_category; } + //! Get the message associated with this error condition based on its value and category. [[nodiscard]] constexpr auto message() const noexcept -> std::string_view { return m_category->message(m_value); } + //! Check if this error condition holds an error. + //! + //! @return @p true iff. this error condition holds a non-zero value, @p false otherwise. [[nodiscard]] constexpr explicit operator bool() const noexcept { return m_value != 0; } + //! Check if two error conditions are equal. + //! + //! Error conditions are considered equal if they hold the same value and reference the same category. [[nodiscard]] constexpr auto friend operator==(error_condition const & lhs, error_condition const & rhs) noexcept -> bool { return lhs.category() == rhs.category() && lhs.value() == rhs.value(); } + //! Lexicographically compare two error conditions. [[nodiscard]] constexpr auto friend operator<=>(error_condition const & lhs, error_condition const & rhs) noexcept -> std::strong_ordering { @@ -206,64 +239,95 @@ namespace kstd error_category const * m_category{}; }; + //! An error code represents a specific, subsystem-level error. + //! + //! Error codes are used to represent errors that are specific to a subsystem. Equivalence between error codes and + //! error conditions can be defined per each error enumeration type. struct error_code { + //! Construct an error code with a default value and category. constexpr error_code() noexcept; + //! Construct an error code with a specific value and category. constexpr error_code(int value, error_category const & category) noexcept : m_value{value} , m_category{&category} {} + //! Construct an error code from an error code enumeration value. + //! + //! @tparam Enum The error code enumeration type. + //! @param value The error code enumeration value. template constexpr error_code(Enum value) noexcept : error_code{make_error_code(value)} {} + //! Assign an error code enumeration value to this error code. + //! + //! The category is chosen based on the enumeration type of the value. + //! @tparam Enum The error code enumeration type. + //! @param value The error code enumeration value. template constexpr auto operator=(Enum value) noexcept -> error_code & { return *this = make_error_code(value); } + //! Assign a new value and category to this error code. + //! + //! @param value The new error code value. + //! @param category The new error code category. constexpr auto assign(int value, error_category const & category) noexcept -> void { m_value = value; m_category = &category; } + //! Clear this error code. constexpr auto clear() noexcept -> void; + //! Get the raw error code value of this error code. [[nodiscard]] constexpr auto value() const noexcept -> int { return m_value; } + //! Get the error category of this error code. [[nodiscard]] constexpr auto category() const noexcept -> error_category const & { return *m_category; } + //! Get and error condition that is equivalent to this error code. [[nodiscard]] constexpr auto default_error_condition() const noexcept -> error_condition { return m_category->default_error_condition(m_value); } + //! Get the message associated with this error code based on its value and category. [[nodiscard]] constexpr auto message() const noexcept -> std::string_view { return m_category->message(m_value); } + //! Check if this error code holds an error. + //! + //! @return @p true iff. this error code holds a non-zero value, @p false otherwise. [[nodiscard]] constexpr explicit operator bool() const noexcept { return m_value != 0; } + //! Check if two error codes are equal. + //! + //! Error codes are considered equal if they hold the same value and reference the same category. [[nodiscard]] constexpr auto friend operator==(error_code const & lhs, error_code const & rhs) noexcept -> bool { return lhs.category() == rhs.category() && lhs.value() == rhs.value(); } + //! Lexicographically compare two error codes. [[nodiscard]] constexpr auto friend operator<=>(error_code const & lhs, error_code const & rhs) noexcept -> std::strong_ordering { @@ -358,6 +422,7 @@ namespace kstd wrong_protocol_type = posix::eprototype, }; + //! Mark the kstd::errc enumeration as an error condition enumeration. template<> struct is_error_condition_enum : std::true_type { @@ -476,11 +541,13 @@ namespace kstd } constexpr inline system_category_instance{}; } // namespace bits + //! Get a reference to the generic error category. constexpr auto inline generic_category() noexcept -> error_category const & { return bits::generic_category_instance; } + //! Get a reference to the system error category. constexpr auto inline system_category() noexcept -> error_category const & { return bits::system_category_instance; @@ -526,16 +593,21 @@ namespace kstd m_category = &system_category(); } + //! Create an error code from an kstd::errc enumeration value. [[nodiscard]] constexpr auto inline make_error_code(errc const value) noexcept -> error_code { return {static_cast(value), generic_category()}; } + //! Create an error condition from an kstd::errc enumeration value. [[nodiscard]] constexpr auto inline make_error_condition(errc const value) noexcept -> error_condition { return {static_cast(value), generic_category()}; } + //! Enable formatting of kstd::error_code + //! + //! There are currently no valid format specifiers for error codes. template<> struct formatter { -- cgit v1.2.3