From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2181) id 9586F3857C52; Thu, 21 Oct 2021 21:54:17 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 9586F3857C52 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-4622] libstdc++: Add Doxygen comments to contents of X-Act-Checkin: gcc X-Git-Author: Jonathan Wakely X-Git-Refname: refs/heads/master X-Git-Oldrev: 6667d5feb9cbb14fc4e2a4f90d9dfa14e24d5bd9 X-Git-Newrev: 5a5d7c2c802f005f8cf85e0bfb7a77cf13203dae Message-Id: <20211021215417.9586F3857C52@sourceware.org> Date: Thu, 21 Oct 2021 21:54:17 +0000 (GMT) X-BeenThere: libstdc++-cvs@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libstdc++-cvs mailing list List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 21 Oct 2021 21:54:17 -0000 https://gcc.gnu.org/g:5a5d7c2c802f005f8cf85e0bfb7a77cf13203dae commit r12-4622-g5a5d7c2c802f005f8cf85e0bfb7a77cf13203dae Author: Jonathan Wakely Date: Thu Oct 21 17:44:47 2021 +0100 libstdc++: Add Doxygen comments to contents of libstdc++-v3/ChangeLog: * include/bits/mofunc_impl.h: Add doxygen comments. * include/std/functional: Likewise. Diff: --- libstdc++-v3/include/bits/mofunc_impl.h | 37 +++++++++++++ libstdc++-v3/include/std/functional | 94 ++++++++++++++++++++++++++++----- 2 files changed, 119 insertions(+), 12 deletions(-) diff --git a/libstdc++-v3/include/bits/mofunc_impl.h b/libstdc++-v3/include/bits/mofunc_impl.h index 968d235f867..6cc9711a42b 100644 --- a/libstdc++-v3/include/bits/mofunc_impl.h +++ b/libstdc++-v3/include/bits/mofunc_impl.h @@ -44,6 +44,22 @@ namespace std _GLIBCXX_VISIBILITY(default) { _GLIBCXX_BEGIN_NAMESPACE_VERSION + /** + * @brief Polymorphic function wrapper. + * @ingroup functors + * @since C++23 + * @headername functional + * + * The `std::move_only_function` class template is a call wrapper similar + * to * `std::function`, but does not require the stored target function + * to be copyable. + * + * It also supports const-qualification, ref-qualification, and + * no-throw guarantees. The qualifications and exception-specification + * of the `move_only_function::operator()` member function are respected + * when invoking the target function. + * + */ template class move_only_function<_Res(_ArgTypes...) _GLIBCXX_MOF_CV _GLIBCXX_MOF_REF noexcept(_Noex)> @@ -64,15 +80,19 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION public: using result_type = _Res; + /// Creates an empty object. move_only_function() noexcept { } + /// Creates an empty object. move_only_function(nullptr_t) noexcept { } + /// Moves the target object, leaving the source empty. move_only_function(move_only_function&& __x) noexcept : _Mofunc_base(static_cast<_Mofunc_base&&>(__x)), _M_invoke(std::__exchange(__x._M_invoke, nullptr)) { } + /// Stores a target object initialized from the argument. template> requires (!is_same_v<_Vt, move_only_function>) && (!__is_in_place_type_v<_Vt>) && __is_callable_from<_Vt> @@ -89,6 +109,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION _M_invoke = &_S_invoke<_Vt>; } + /// Stores a target object initialized from the arguments. template requires is_constructible_v<_Tp, _Args...> && __is_callable_from<_Tp> @@ -101,6 +122,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION _M_init<_Tp>(std::forward<_Args>(__args)...); } + /// Stores a target object initialized from the arguments. template requires is_constructible_v<_Tp, initializer_list<_Up>&, _Args...> && __is_callable_from<_Tp> @@ -114,6 +136,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION _M_init<_Tp>(__il, std::forward<_Args>(__args)...); } + /// Stores a new target object, leaving `x` empty. move_only_function& operator=(move_only_function&& __x) noexcept { @@ -122,6 +145,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return *this; } + /// Destroys the target object (if any). move_only_function& operator=(nullptr_t) noexcept { @@ -130,6 +154,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return *this; } + /// Stores a new target object, initialized from the argument. template requires is_constructible_v move_only_function& @@ -142,8 +167,17 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION ~move_only_function() = default; + /// True if a target object is present, false otherwise. explicit operator bool() const noexcept { return _M_invoke != nullptr; } + /** Invoke the target object. + * + * The target object will be invoked using the supplied arguments, + * and as an lvalue or rvalue, and as const or non-const, as dictated + * by the template arguments of the `move_only_function` specialization. + * + * @pre Must not be empty. + */ _Res operator()(_ArgTypes... __args) _GLIBCXX_MOF_CV_REF noexcept(_Noex) { @@ -151,6 +185,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return _M_invoke(this, std::forward<_ArgTypes>(__args)...); } + /// Exchange the target objects (if any). void swap(move_only_function& __x) noexcept { @@ -158,10 +193,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION std::swap(_M_invoke, __x._M_invoke); } + /// Exchange the target objects (if any). friend void swap(move_only_function& __x, move_only_function& __y) noexcept { __x.swap(__y); } + /// Check for emptiness by comparing with `nullptr`. friend bool operator==(const move_only_function& __x, nullptr_t) noexcept { return __x._M_invoke == nullptr; } diff --git a/libstdc++-v3/include/std/functional b/libstdc++-v3/include/std/functional index 2db1c05349b..5cf4417b963 100644 --- a/libstdc++-v3/include/std/functional +++ b/libstdc++-v3/include/std/functional @@ -79,6 +79,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** @brief The type of placeholder objects defined by libstdc++. * @ingroup binders + * @since C++11 */ template struct _Placeholder { }; @@ -90,7 +91,17 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION # define __cpp_lib_constexpr_functional 201907L # endif - /// Invoke a callable object. + /** Invoke a callable object. + * + * `std::invoke` takes a callable object as its first argument and calls it + * with the remaining arguments. The callable object can be a pointer or + * reference to a function, a lambda closure, a class with `operator()`, + * or even a pointer-to-member. For a pointer-to-member the first argument + * must be a reference or pointer to the object that the pointer-to-member + * will be applied to. + * + * @since C++17 + */ template inline _GLIBCXX20_CONSTEXPR invoke_result_t<_Callable, _Args...> invoke(_Callable&& __fn, _Args&&... __args) @@ -103,7 +114,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #if __cplusplus > 202002L # define __cpp_lib_invoke_r 202106L - /// Invoke a callable object and convert the result to _Res. + /** Invoke a callable object and convert the result to `_Res`. + * + * `std::invoke_r(f, args...)` is equivalent to `std::invoke(f, args...)` + * with the result implicitly converted to `R`. + * + * @since C++23 + */ template requires is_invocable_r_v<_Res, _Callable, _Args...> constexpr _Res @@ -116,6 +133,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #endif // C++23 #endif // C++17 + /// @cond undocumented + template::value> class _Mem_fn_base @@ -182,13 +201,32 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { using _Mem_fn_base<_Res _Class::*>::_Mem_fn_base; }; + /// @endcond // _GLIBCXX_RESOLVE_LIB_DEFECTS // 2048. Unnecessary mem_fn overloads /** - * @brief Returns a function object that forwards to the member - * pointer @a pm. - * @ingroup functors + * @brief Returns a function object that forwards to the member pointer + * pointer `pm`. + * + * This allows a pointer-to-member to be transformed into a function object + * that can be called with an object expression as its first argument. + * + * For a pointer-to-data-member the result must be called with exactly one + * argument, the object expression that would be used as the first operand + * in a `obj.*memptr` or `objp->*memptr` expression. + * + * For a pointer-to-member-function the result must be called with an object + * expression and any additional arguments to pass to the member function, + * as in an expression like `(obj.*memfun)(args...)` or + * `(objp->*memfun)(args...)`. + * + * The object expression can be a pointer, reference, `reference_wrapper`, + * or smart pointer, and the call wrapper will dereference it as needed + * to apply the pointer-to-member. + * + * @ingroup functors + * @since C++11 */ template _GLIBCXX20_CONSTEXPR @@ -199,12 +237,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } /** - * @brief Determines if the given type _Tp is a function object that - * should be treated as a subexpression when evaluating calls to - * function objects returned by bind(). + * @brief Trait that identifies a bind expression. + * + * Determines if the given type `_Tp` is a function object that + * should be treated as a subexpression when evaluating calls to + * function objects returned by `std::bind`. * - * C++11 [func.bind.isbind]. - * @ingroup binders + * C++11 [func.bind.isbind]. + * @ingroup binders + * @since C++11 */ template struct is_bind_expression @@ -216,6 +257,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * * C++11 [func.bind.isplace]. * @ingroup binders + * @since C++11 */ template struct is_placeholder @@ -232,6 +274,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** @namespace std::placeholders * @brief ISO C++ 2011 namespace for std::bind placeholders. * @ingroup binders + * @since C++11 */ namespace placeholders { @@ -274,6 +317,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * Partial specialization of is_placeholder that provides the placeholder * number for the placeholder objects defined by libstdc++. * @ingroup binders + * @since C++11 */ template struct is_placeholder<_Placeholder<_Num> > @@ -285,6 +329,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION : public integral_constant { }; + /// @cond undocumented // Like tuple_element_t but SFINAE-friendly. template @@ -414,6 +459,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION -> __tuple_element_t<_Ind, tuple<_Tp...>> const volatile& { return std::get<_Ind>(const_cast&>(__tuple)); } + /// @endcond + /// Type of the function object returned from bind(). template class _Bind; @@ -799,6 +846,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** * @brief Function template for std::bind. * @ingroup binders + * @since C++11 */ template inline _GLIBCXX20_CONSTEXPR typename @@ -823,6 +871,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** * @brief Function template for std::bind. * @ingroup binders + * @since C++11 */ template inline _GLIBCXX20_CONSTEXPR @@ -923,6 +972,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION using _Bind_front_t = _Bind_front, decay_t<_Args>...>; + /** Create call wrapper by partial application of arguments to function. + * + * The result of `std::bind_front(f, args...)` is a function object that + * stores `f` and the bound arguments, `args...`. When that function + * object is invoked with `call_args...` it returns the result of calling + * `f(args..., call_args...)`. + * + * @since C++20 + */ template constexpr _Bind_front_t<_Fn, _Args...> bind_front(_Fn&& __fn, _Args&&... __args) @@ -932,7 +990,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return _Bind_front_t<_Fn, _Args...>(0, std::forward<_Fn>(__fn), std::forward<_Args>(__args)...); } -#endif +#endif // C++20 #if __cplusplus >= 201402L /// Generalized negator. @@ -1003,8 +1061,20 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION struct __is_byte_like> : true_type { }; + // [func.not_fn] Function template not_fn #define __cpp_lib_not_fn 201603 - /// [func.not_fn] Function template not_fn + /** Wrap a function object to create one that negates its result. + * + * The function template `std::not_fn` creates a "forwarding call wrapper", + * which is a function object that wraps another function object and + * when called, forwards its arguments to the wrapped function object. + * + * The result of invoking the wrapper is the negation (using `!`) of + * the wrapped function object. + * + * @ingroup functors + * @since C++17 + */ template _GLIBCXX20_CONSTEXPR inline auto