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:
parent
aba938d6c3
commit
828176ba49
@ -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>
|
||||
{
|
||||
|
Loading…
Reference in New Issue
Block a user