libstdc++: Improve doxygen comments in <bits/stl_function.h>

Add notes about deprecation and modern replacements. Fix bogus
"memory_adaptors" group name. Use markdown for formatting.

Signed-off-by: Jonathan Wakely <jwakely@redhat.com>

libstdc++-v3/ChangeLog:

	* include/bits/stl_function.h: Improve doxygen comments.
This commit is contained in:
Jonathan Wakely 2021-08-18 12:18:35 +01:00
parent aba938d6c3
commit 828176ba49

View File

@ -66,40 +66,52 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 20.3.1 base classes
/** @defgroup functors Function Objects
* @ingroup utilities
* @ingroup utilities
*
* Function objects, or @e functors, are objects with an @c operator()
* Function objects, or _functors_, are objects with an `operator()`
* defined and accessible. They can be passed as arguments to algorithm
* templates and used in place of a function pointer. Not only is the
* resulting expressiveness of the library increased, but the generated
* code can be more efficient than what you might write by hand. When we
* refer to @a functors, then, generally we include function pointers in
* refer to _functors_, then, generally we include function pointers in
* the description as well.
*
* Often, functors are only created as temporaries passed to algorithm
* calls, rather than being created as named variables.
*
* Two examples taken from the standard itself follow. To perform a
* by-element addition of two vectors @c a and @c b containing @c double,
* and put the result in @c a, use
* by-element addition of two vectors `a` and `b` containing `double`,
* and put the result in `a`, use
* \code
* transform (a.begin(), a.end(), b.begin(), a.begin(), plus<double>());
* \endcode
* To negate every element in @c a, use
* To negate every element in `a`, use
* \code
* transform(a.begin(), a.end(), a.begin(), negate<double>());
* \endcode
* The addition and negation functions will be inlined directly.
* The addition and negation functions will usually be inlined directly.
*
* The standard functors are derived from structs named @c unary_function
* and @c binary_function. These two classes contain nothing but typedefs,
* to aid in generic (template) programming. If you write your own
* functors, you might consider doing the same.
* An _adaptable function object_ is one which provides nested typedefs
* `result_type` and either `argument_type` (for a unary function) or
* `first_argument_type` and `second_argument_type` (for a binary function).
* Those typedefs are used by function object adaptors such as `bind2nd`.
* The standard library provides two class templates, `unary_function` and
* `binary_function`, which define those typedefs and so can be used as
* base classes of adaptable function objects.
*
* Since C++11 the use of function object adaptors has been superseded by
* more powerful tools such as lambda expressions, `function<>`, and more
* powerful type deduction (using `auto` and `decltype`). The helpers for
* defining adaptable function objects are deprecated since C++11, and no
* longer part of the standard library since C++17. However, they are still
* defined and used by libstdc++ after C++17, as a conforming extension.
*
* @{
*/
/**
* This is one of the @link functors functor base classes@endlink.
* Helper for defining adaptable unary function objects.
* @deprecated Deprecated in C++11, no longer in the standard since C++17.
*/
template<typename _Arg, typename _Result>
struct unary_function
@ -112,7 +124,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
};
/**
* This is one of the @link functors functor base classes@endlink.
* Helper for defining adaptable binary function objects.
* @deprecated Deprecated in C++11, no longer in the standard since C++17.
*/
template<typename _Arg1, typename _Arg2, typename _Result>
struct binary_function
@ -129,12 +142,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/** @} */
// 20.3.2 arithmetic
/** @defgroup arithmetic_functors Arithmetic Classes
* @ingroup functors
/** @defgroup arithmetic_functors Arithmetic Function Object Classes
* @ingroup functors
*
* Because basic math often needs to be done during an algorithm,
* the library provides functors for those operations. See the
* documentation for @link functors the base classes@endlink
* The library provides function objects for basic arithmetic operations.
* See the documentation for @link functors function objects @endlink
* for examples of their use.
*
* @{
@ -166,6 +179,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
template<typename _Tp>
struct plus : public binary_function<_Tp, _Tp, _Tp>
{
/// Returns the sum
_GLIBCXX14_CONSTEXPR
_Tp
operator()(const _Tp& __x, const _Tp& __y) const
@ -319,7 +333,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 20.3.3 comparisons
/** @defgroup comparison_functors Comparison Classes
* @ingroup functors
* @ingroup functors
*
* The library provides six wrapper functors for all the basic comparisons
* in C++, like @c <.
@ -763,10 +777,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 20.3.4 logical operations
/** @defgroup logical_functors Boolean Operations Classes
* @ingroup functors
* @ingroup functors
*
* Here are wrapper functors for Boolean operations: @c &&, @c ||,
* and @c !.
* The library provides function objects for the logical operations:
* `&&`, `||`, and `!`.
*
* @{
*/
@ -971,30 +985,33 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 20.3.5 negators
/** @defgroup negators Negators
* @ingroup functors
* @ingroup functors
*
* The functions @c not1 and @c not2 each take a predicate functor
* and return an instance of @c unary_negate or
* @c binary_negate, respectively. These classes are functors whose
* @c operator() performs the stored predicate function and then returns
* the negation of the result.
* The function templates `not1` and `not2` are function object adaptors,
* which each take a predicate functor and wrap it in an instance of
* `unary_negate` or `binary_negate`, respectively. Those classes are
* functors whose `operator()` evaluates the wrapped predicate function
* and then returns the negation of the result.
*
* For example, given a vector of integers and a trivial predicate,
* \code
* struct IntGreaterThanThree
* : public std::unary_function<int, bool>
* {
* bool operator() (int x) { return x > 3; }
* bool operator() (int x) const { return x > 3; }
* };
*
* std::find_if (v.begin(), v.end(), not1(IntGreaterThanThree()));
* \endcode
* The call to @c find_if will locate the first index (i) of @c v for which
* <code>!(v[i] > 3)</code> is true.
* The call to `find_if` will locate the first index (i) of `v` for which
* `!(v[i] > 3)` is true.
*
* The not1/unary_negate combination works on predicates taking a single
* argument. The not2/binary_negate combination works on predicates which
* take two arguments.
* argument. The not2/binary_negate combination works on predicates taking
* two arguments.
*
* @deprecated Deprecated in C++17, no longer in the standard since C++20.
* Use `not_fn` instead.
*
* @{
*/
@ -1055,24 +1072,26 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 20.3.7 adaptors pointers functions
/** @defgroup pointer_adaptors Adaptors for pointers to functions
* @ingroup functors
* @ingroup functors
*
* The advantage of function objects over pointers to functions is that
* the objects in the standard library declare nested typedefs describing
* their argument and result types with uniform names (e.g., @c result_type
* from the base classes @c unary_function and @c binary_function).
* their argument and result types with uniform names (e.g., `result_type`
* from the base classes `unary_function` and `binary_function`).
* Sometimes those typedefs are required, not just optional.
*
* Adaptors are provided to turn pointers to unary (single-argument) and
* binary (double-argument) functions into function objects. The
* long-winded functor @c pointer_to_unary_function is constructed with a
* function pointer @c f, and its @c operator() called with argument @c x
* returns @c f(x). The functor @c pointer_to_binary_function does the same
* thing, but with a double-argument @c f and @c operator().
* long-winded functor `pointer_to_unary_function` is constructed with a
* function pointer `f`, and its `operator()` called with argument `x`
* returns `f(x)`. The functor `pointer_to_binary_function` does the same
* thing, but with a double-argument `f` and `operator()`.
*
* The function @c ptr_fun takes a pointer-to-function @c f and constructs
* The function `ptr_fun` takes a pointer-to-function `f` and constructs
* an instance of the appropriate functor.
*
* @deprecated Deprecated in C++11, no longer in the standard since C++17.
*
* @{
*/
/// One of the @link pointer_adaptors adaptors for function pointers@endlink.
@ -1182,8 +1201,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
};
// 20.3.8 adaptors pointers members
/** @defgroup memory_adaptors Adaptors for pointers to members
* @ingroup functors
/** @defgroup ptrmem_adaptors Adaptors for pointers to members
* @ingroup functors
*
* There are a total of 8 = 2^3 function objects in this family.
* (1) Member functions taking no arguments vs member functions taking
@ -1192,13 +1211,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* (3) Const vs non-const member function.
*
* All of this complexity is in the function objects themselves. You can
* ignore it by using the helper function mem_fun and mem_fun_ref,
* ignore it by using the helper function `mem_fun` and `mem_fun_ref`,
* which create whichever type of adaptor is appropriate.
*
* @deprecated Deprecated in C++11, no longer in the standard since C++17.
* Use `mem_fn` instead.
*
* @{
*/
/// One of the @link memory_adaptors adaptors for member
/// pointers@endlink.
/// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp>
class mem_fun_t : public unary_function<_Tp*, _Ret>
{
@ -1215,8 +1236,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)();
};
/// One of the @link memory_adaptors adaptors for member
/// pointers@endlink.
/// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp>
class const_mem_fun_t : public unary_function<const _Tp*, _Ret>
{
@ -1233,8 +1253,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)() const;
};
/// One of the @link memory_adaptors adaptors for member
/// pointers@endlink.
/// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp>
class mem_fun_ref_t : public unary_function<_Tp, _Ret>
{
@ -1251,8 +1270,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)();
};
/// One of the @link memory_adaptors adaptors for member
/// pointers@endlink.
/// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp>
class const_mem_fun_ref_t : public unary_function<_Tp, _Ret>
{
@ -1269,8 +1287,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)() const;
};
/// One of the @link memory_adaptors adaptors for member
/// pointers@endlink.
/// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp, typename _Arg>
class mem_fun1_t : public binary_function<_Tp*, _Arg, _Ret>
{
@ -1287,8 +1304,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)(_Arg);
};
/// One of the @link memory_adaptors adaptors for member
/// pointers@endlink.
/// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp, typename _Arg>
class const_mem_fun1_t : public binary_function<const _Tp*, _Arg, _Ret>
{
@ -1305,8 +1321,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)(_Arg) const;
};
/// One of the @link memory_adaptors adaptors for member
/// pointers@endlink.
/// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp, typename _Arg>
class mem_fun1_ref_t : public binary_function<_Tp, _Arg, _Ret>
{
@ -1323,8 +1338,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ret (_Tp::*_M_f)(_Arg);
};
/// One of the @link memory_adaptors adaptors for member
/// pointers@endlink.
/// One of the @link ptrmem_adaptors adaptors for member pointers@endlink.
template<typename _Ret, typename _Tp, typename _Arg>
class const_mem_fun1_ref_t : public binary_function<_Tp, _Arg, _Ret>
{