TeamHeptaMirrors/gcc
1
0
Fork 1
mirror of https://github.com/gcc-mirror/gcc.git synced 2026-05-06 14:59:39 +02:00
Code Issues Packages Projects Releases Wiki Activity

libstdc++: Add Doxygen comments to contents of <functional>

Browse Source 
libstdc++-v3/ChangeLog:

	* include/bits/mofunc_impl.h: Add doxygen comments.
	* include/std/functional: Likewise.
This commit is contained in:
Jonathan Wakely
2021-10-21 17:44:47 +01:00
parent 6667d5feb9
commit 5a5d7c2c80
2 changed files with 119 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
libstdc++-v3/include/bits/mofunc_impl.h
View File

@@ -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; }

94
libstdc++-v3/include/std/functional
View File

@@ -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