From patchwork Thu Oct 21 22:23:31 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 46513 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 9C085385780B for ; Thu, 21 Oct 2021 22:25:19 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 9C085385780B DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1634855119; bh=sAPoRNLe+709WC+fRFrSkCiryLdufo18R3Zx987GmxQ=; h=References:In-Reply-To:Date:Subject:To:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=LyOP4rbKBqrsgLS05XqFCmZdrL26ZjwR9eVE6ba2TnOBJOKWt2nMa3HN8abozw2Qs LoIjowxLPZ6XGOxBrvHAc70fe/tiYwTQfzb29AZJIUs4S7ngMRz2HcPKIrwSma2+Cl FYOGYfZIxaEYfillz4L7Xu9Wc6WB5kKWvIdKA53I= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id B6D14385781B for ; Thu, 21 Oct 2021 22:23:45 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org B6D14385781B Received: from mail-ua1-f69.google.com (mail-ua1-f69.google.com [209.85.222.69]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-452-yxN2HRIYNWSN-sgPGL5bkQ-1; Thu, 21 Oct 2021 18:23:43 -0400 X-MC-Unique: yxN2HRIYNWSN-sgPGL5bkQ-1 Received: by mail-ua1-f69.google.com with SMTP id u11-20020ab0458b000000b002cb6515556bso186449uau.15 for ; Thu, 21 Oct 2021 15:23:43 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to; bh=cq4evZ9FiWr5fsrad6+2uUwDe9uX+/OPC+aU3EnldL8=; b=3tkrAhgdkGcdTVJtlP8eR385a3gF8ghL/QgyfoWguxTen5KS9YZBeNj7+zvRmWEXhj 9Mys44BUJyhe38TKx0V6uUr3ttoDV2J3BSngPbd5FEv6PuyRhXo8OwdKXo34gMMuyAau 2TfNuNGl2v6U14SYgrWMIr3s72s/MWaMlEMo0P1WE4ckwax2Z94MxEiYyJ/lgYJ5WCx9 NExDOc8LlVcxCXD1tDQphNhBIKTfeYiS2sXBsgVOlGVg7nff66inHHsqhY+1mwhf2gYG uIER8MP8C5s1CHOoUdfJ4ZNisvgyO2wYHxW0B31NTboloE4n1tUOv4A2A5vL7pXLx8Q7 7pBA== X-Gm-Message-State: AOAM5329vUuIqnVUnSCUO61HrVa3eGeW5keDpnnzXGrHdTInvFYaXcob M7LIKDLnYxDrK/wAP6Wus8xpAOYNaTZ5T93KiTSqL9DzSza/rcBF4WuQUDp930e3twxCEQfW6Wg ylpt1+K2isiExZyjfsPYCArAvPmxwlYjTIA== X-Received: by 2002:a67:d89b:: with SMTP id f27mr10480202vsj.16.1634855023189; Thu, 21 Oct 2021 15:23:43 -0700 (PDT) X-Google-Smtp-Source: ABdhPJw/Xxsbeal/7liEqZuJcQuG8cBWKCL/Jo7u0mgM+82b0ClpMaGdpGQRp0NlgaGo0V1z+AVwyZ/3gK4xMTrSkEg= X-Received: by 2002:a67:d89b:: with SMTP id f27mr10480178vsj.16.1634855022907; Thu, 21 Oct 2021 15:23:42 -0700 (PDT) MIME-Version: 1.0 References: <20211021215713.821048-1-jwakely@redhat.com> In-Reply-To: <20211021215713.821048-1-jwakely@redhat.com> Date: Thu, 21 Oct 2021 23:23:31 +0100 Message-ID: Subject: Fwd: [committed] libstdc++: Add Doxygen comments to contents of To: gcc Patches X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-12.9 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, HTML_MESSAGE, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-Content-Filtered-By: Mailman/MimeDel 2.1.29 X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "Gcc-patches" I messed up the CC to gcc-patches for this ... ---------- Forwarded message --------- From: Jonathan Wakely via Libstdc++ Date: Thu, 21 Oct 2021 at 22:57 Subject: [committed] libstdc++: Add Doxygen comments to contents of To: , Tested x86_64-linux, committed to trunk. libstdc++-v3/ChangeLog: * include/bits/mofunc_impl.h: Add doxygen comments. * include/std/functional: Likewise. --- libstdc++-v3/include/bits/mofunc_impl.h | 37 ++++++++++ libstdc++-v3/include/std/functional | 94 +++++++++++++++++++++---- 2 files changed, 119 insertions(+), 12 deletions(-) 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 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 + */