* [committed] libstdc++: Add Doxygen comments to contents of <functional>
@ 2021-10-21 21:57 Jonathan Wakely
0 siblings, 0 replies; only message in thread
From: Jonathan Wakely @ 2021-10-21 21:57 UTC (permalink / raw)
To: patches, libstdc++
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(-)
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<typename _Res, typename... _ArgTypes, bool _Noex>
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<typename _Fn, typename _Vt = decay_t<_Fn>>
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<typename _Tp, typename... _Args>
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<typename _Tp, typename _Up, typename... _Args>
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<typename _Fn>
requires is_constructible_v<move_only_function, _Fn>
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<int _Num> 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<typename _Callable, typename... _Args>
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<R>(f, args...)` is equivalent to `std::invoke(f, args...)`
+ * with the result implicitly converted to `R`.
+ *
+ * @since C++23
+ */
template<typename _Res, typename _Callable, typename... _Args>
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<typename _MemFunPtr,
bool __is_mem_fn = is_member_function_pointer<_MemFunPtr>::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<typename _Tp, typename _Class>
_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<typename _Tp>
struct is_bind_expression
@@ -216,6 +257,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* C++11 [func.bind.isplace].
* @ingroup binders
+ * @since C++11
*/
template<typename _Tp>
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<int _Num>
struct is_placeholder<_Placeholder<_Num> >
@@ -285,6 +329,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
: public integral_constant<int, _Num>
{ };
+ /// @cond undocumented
// Like tuple_element_t but SFINAE-friendly.
template<std::size_t __i, typename _Tuple>
@@ -414,6 +459,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
-> __tuple_element_t<_Ind, tuple<_Tp...>> const volatile&
{ return std::get<_Ind>(const_cast<const tuple<_Tp...>&>(__tuple)); }
+ /// @endcond
+
/// Type of the function object returned from bind().
template<typename _Signature>
class _Bind;
@@ -799,6 +846,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief Function template for std::bind.
* @ingroup binders
+ * @since C++11
*/
template<typename _Func, typename... _BoundArgs>
inline _GLIBCXX20_CONSTEXPR typename
@@ -823,6 +871,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief Function template for std::bind<R>.
* @ingroup binders
+ * @since C++11
*/
template<typename _Result, typename _Func, typename... _BoundArgs>
inline _GLIBCXX20_CONSTEXPR
@@ -923,6 +972,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
using _Bind_front_t
= _Bind_front<decay_t<_Fn>, 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<typename _Fn, typename... _Args>
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<byte, equal_to<void>>
: 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<typename _Fn>
_GLIBCXX20_CONSTEXPR
inline auto
--
2.31.1
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2021-10-21 21:57 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-10-21 21:57 [committed] libstdc++: Add Doxygen comments to contents of <functional> Jonathan Wakely
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).