From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2181) id 8209A38768B7; Tue, 28 Mar 2023 23:34:19 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 8209A38768B7 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1680046459; bh=xNmFYDuwV36CJi3XyOq4XXUf/KSZCi1BweioyOSbWM0=; h=From:To:Subject:Date:From; b=MKCABr/T8+n5kwCj/TxTMrSACm//9FstyQoWoSD1oAMy3xIzwY2ovcBspRPWTvRd2 Fn4A1cr0Q0flolHOcNm9AoxSlGaNEiHYowqkhefxtTOudBMxarSNaz9qq4+0OHiT6N YQlQwdiaKTn0EDWEHi+QsFSdBHKnejGwI5EbzDzA= MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="utf-8" From: Jonathan Wakely To: gcc-cvs@gcc.gnu.org, libstdc++-cvs@gcc.gnu.org Subject: [gcc r12-9335] libstdc++: Improve doxygen docs for X-Act-Checkin: gcc X-Git-Author: Jonathan Wakely X-Git-Refname: refs/heads/releases/gcc-12 X-Git-Oldrev: e1c8dc0ba5a012bd3bc0c527e4db40a885c8bc42 X-Git-Newrev: 639299834b5bc86b5d0488b7f291a88d2e1e2d5d Message-Id: <20230328233419.8209A38768B7@sourceware.org> Date: Tue, 28 Mar 2023 23:34:19 +0000 (GMT) List-Id: https://gcc.gnu.org/g:639299834b5bc86b5d0488b7f291a88d2e1e2d5d commit r12-9335-g639299834b5bc86b5d0488b7f291a88d2e1e2d5d Author: Jonathan Wakely Date: Wed May 11 22:48:17 2022 +0100 libstdc++: Improve doxygen docs for libstdc++-v3/ChangeLog: * include/std/system_error: Improve doxygen comments. (cherry picked from commit 20b917e7c007f54dd471f64b301124d4d1f8b636) Diff: --- libstdc++-v3/include/std/system_error | 136 ++++++++++++++++++++++++++-------- 1 file changed, 107 insertions(+), 29 deletions(-) diff --git a/libstdc++-v3/include/std/system_error b/libstdc++-v3/include/std/system_error index 45a1d283556..e7415a44ed1 100644 --- a/libstdc++-v3/include/std/system_error +++ b/libstdc++-v3/include/std/system_error @@ -85,13 +85,20 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** Abstract base class for types defining a category of error codes. * - * An error category defines a context that give meaning to the integer + * An error category defines a context that gives meaning to the integer * stored in an `error_code` or `error_condition` object. For example, * the standard `errno` constants such a `EINVAL` and `ENOMEM` are * associated with the "generic" category and other OS-specific error * numbers are associated with the "system" category, but a user-defined * category might give different meanings to the same numerical values. * + * A user-defined category can override the `equivalent` member functions + * to define correspondence between errors in different categories. + * For example, a category for errors from disk I/O could consider some + * of its error numbers equivalent to ENOSPC and ENOENT in the generic + * category. + * + * @headerfile system_error * @since C++11 */ class error_category @@ -104,6 +111,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION error_category(const error_category&) = delete; error_category& operator=(const error_category&) = delete; + /// A string that identifies the error category. virtual const char* name() const noexcept = 0; @@ -118,6 +126,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION _M_message(int) const; public: + /// A description of the error condition corresponding to the number. _GLIBCXX_DEFAULT_ABI_TAG virtual string message(int) const = 0; @@ -131,31 +140,36 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #endif public: + /// Return an error_condition corresponding to `i` in this category. virtual error_condition default_error_condition(int __i) const noexcept; + /// Test whether `cond` corresponds to `i` for this category. virtual bool equivalent(int __i, const error_condition& __cond) const noexcept; + /// Test whether `code` corresponds to `i` for this category. virtual bool equivalent(const error_code& __code, int __i) const noexcept; + /// An error_category only compares equal to itself. bool operator==(const error_category& __other) const noexcept { return this == &__other; } + /// Ordered comparison that defines a total order for error categories. #if __cpp_lib_three_way_comparison strong_ordering operator<=>(const error_category& __rhs) const noexcept { return std::compare_three_way()(this, &__rhs); } #else - bool - operator!=(const error_category& __other) const noexcept - { return this != &__other; } - bool operator<(const error_category& __other) const noexcept { return less()(this, &__other); } + + bool + operator!=(const error_category& __other) const noexcept + { return this != &__other; } #endif }; @@ -190,8 +204,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * library might be represented by an HTTP response status code (e.g. 404) * and a custom category defined by the library. * + * @headerfile system_error * @since C++11 - * @ingroup diagnostics */ class error_code { @@ -225,20 +239,25 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION operator=(_ErrorCodeEnum __e) noexcept { return *this = make_error_code(__e); } + /// The error value. int value() const noexcept { return _M_value; } + /// The error category that this error belongs to. const error_category& category() const noexcept { return *_M_cat; } + /// An `error_condition` for this error's category and value. error_condition default_error_condition() const noexcept; + /// The category's description of the value. _GLIBCXX_DEFAULT_ABI_TAG string message() const { return category().message(value()); } + /// Test whether `value()` is non-zero. explicit operator bool() const noexcept { return _M_value != 0; } @@ -248,14 +267,28 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION const error_category* _M_cat; }; - // 19.4.2.6 non-member functions - - /// @relates error_code @{ + // C++11 19.5.2.5 non-member functions + /** Create an `error_code` representing a standard `errc` condition. + * + * The `std::errc` constants correspond to `errno` macros and so use the + * generic category. + * + * @relates error_code + * @since C++11 + */ inline error_code make_error_code(errc __e) noexcept { return error_code(static_cast(__e), generic_category()); } + /** Ordered comparison for std::error_code. + * + * This defines a total order by comparing the categories, and then + * if they are equal comparing the values. + * + * @relates error_code + * @since C++11 + */ #if __cpp_lib_three_way_comparison inline strong_ordering operator<=>(const error_code& __lhs, const error_code& __rhs) noexcept @@ -274,13 +307,16 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } #endif + /** Write a std::error_code to an ostream. + * + * @relates error_code + * @since C++11 + */ template basic_ostream<_CharT, _Traits>& operator<<(basic_ostream<_CharT, _Traits>& __os, const error_code& __e) { return (__os << __e.category().name() << ':' << __e.value()); } - /// @} - error_condition make_error_condition(errc) noexcept; /** Class error_condition @@ -292,14 +328,17 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * An `error_condition` represents something that the program can test for, * and subsequently take appropriate action. * + * @headerfile system_error * @since C++11 */ class error_condition { public: + /// Initialize with a zero (no error) value and the generic category. error_condition() noexcept : _M_value(0), _M_cat(&generic_category()) { } + /// Initialize with the specified value and category. error_condition(int __v, const error_category& __cat) noexcept : _M_value(__v), _M_cat(&__cat) { } @@ -308,6 +347,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION error_condition(_ErrorConditionEnum __e) noexcept { *this = make_error_condition(__e); } + /// Set the value and category. void assign(int __v, const error_category& __cat) noexcept { @@ -322,22 +362,28 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION operator=(_ErrorConditionEnum __e) noexcept { return *this = make_error_condition(__e); } + /// Reset the value and category to the default-constructed state. void clear() noexcept { assign(0, generic_category()); } - // 19.4.3.4 observers + // C++11 19.5.3.4 observers + + /// The error value. int value() const noexcept { return _M_value; } + /// The error category that this error belongs to. const error_category& category() const noexcept { return *_M_cat; } + /// The category's description of the value. _GLIBCXX_DEFAULT_ABI_TAG string message() const { return category().message(value()); } + /// Test whether `value()` is non-zero. explicit operator bool() const noexcept { return _M_value != 0; } @@ -347,42 +393,75 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION const error_category* _M_cat; }; - // 19.4.3.6 non-member functions + // C++11 19.5.3.5 non-member functions - /// Create an `error_condition` representing a standard `errc` condition. - /// @relates error_condition + /** Create an `error_condition` representing a standard `errc` condition. + * + * The `std::errc` constants correspond to `errno` macros and so use the + * generic category. + * + * @relates error_condition + * @since C++11 + */ inline error_condition make_error_condition(errc __e) noexcept { return error_condition(static_cast(__e), generic_category()); } - // 19.4.4 Comparison operators + // C++11 19.5.4 Comparison operators - /// @relates error_code + /** Equality comparison for std::error_code. + * + * Returns true only if they have the same category and the same value. + * + * @relates error_condition + * @since C++11 + */ inline bool operator==(const error_code& __lhs, const error_code& __rhs) noexcept - { return (__lhs.category() == __rhs.category() - && __lhs.value() == __rhs.value()); } + { + return __lhs.category() == __rhs.category() + && __lhs.value() == __rhs.value(); + } - /// @relates error_code + /** Equality comparison for std::error_code and std::error_condition. + * + * Uses each category's `equivalent` member function to check whether + * the values correspond to an equivalent error in that category. + * + * @relates error_condition + * @since C++11 + */ inline bool operator==(const error_code& __lhs, const error_condition& __rhs) noexcept { - return (__lhs.category().equivalent(__lhs.value(), __rhs) - || __rhs.category().equivalent(__lhs, __rhs.value())); + return __lhs.category().equivalent(__lhs.value(), __rhs) + || __rhs.category().equivalent(__lhs, __rhs.value()); } - /// @relates error_condition + /** Equality comparison for std::error_condition. + * + * Returns true only if they have the same category and the same value. + * + * @relates error_condition + * @since C++11 + */ inline bool operator==(const error_condition& __lhs, const error_condition& __rhs) noexcept { - return (__lhs.category() == __rhs.category() - && __lhs.value() == __rhs.value()); + return __lhs.category() == __rhs.category() + && __lhs.value() == __rhs.value(); } + /** Ordered comparison for std::error_condition. + * + * This defines a total order by comparing the categories, and then + * if they are equal comparing the values. + * + * @relates error_condition + * @since C++11 + */ #if __cpp_lib_three_way_comparison - /// Define an ordering for error_condition objects. - /// @relates error_condition inline strong_ordering operator<=>(const error_condition& __lhs, const error_condition& __rhs) noexcept @@ -392,8 +471,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return __lhs.value() <=> __rhs.value(); } #else - /// Define an ordering for error_condition objects. - /// @relates error_condition inline bool operator<(const error_condition& __lhs, const error_condition& __rhs) noexcept @@ -440,6 +517,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * Typically used to report errors from the operating system and other * low-level APIs. * + * @headerfile system_error * @since C++11 * @ingroup exceptions */