20 General utilities library [utilities]

20.14 Function objects [function.objects]

20.14.14 Function object binders [func.bind]

This subclause describes a uniform mechanism for binding arguments of callable objects.

20.14.14.1 Class template is_bind_expression [func.bind.isbind]

namespace std {
  template<class T> struct is_bind_expression;  // see below
}

The class template is_bind_expression can be used to detect function objects generated by bind.

The function template bind uses is_bind_expression to detect subexpressions.

Specializations of the is_bind_expression template shall meet the Cpp17UnaryTypeTrait requirements ([meta.rqmts]).

The implementation provides a definition that has a base characteristic of true_type if T is a type returned from bind, otherwise it has a base characteristic of false_type.

A program may specialize this template for a program-defined type T to have a base characteristic of true_type to indicate that T should be treated as a subexpression in a bind call.

20.14.14.2 Class template is_placeholder [func.bind.isplace]

namespace std {
  template<class T> struct is_placeholder;      // see below
}

The class template is_placeholder can be used to detect the standard placeholders _1, _2, and so on.

The function template bind uses is_placeholder to detect placeholders.

Specializations of the is_placeholder template shall meet the Cpp17UnaryTypeTrait requirements ([meta.rqmts]).

The implementation provides a definition that has the base characteristic of integral_constant<int, J> if T is the type of std::placeholders::_J, otherwise it has a base characteristic of integral_constant<int, 0>.

A program may specialize this template for a program-defined type T to have a base characteristic of integral_constant<int, N> with N > 0 to indicate that T should be treated as a placeholder type.

20.14.14.3 Function template bind [func.bind.bind]

In the text that follows:

(1.1)
g is a value of the result of a bind invocation,
(1.2)
FD is the type decay_t<F>,
(1.3)
fd is an lvalue that is a target object of g ([func.def]) of type FD direct-non-list-initialized with std::forward<F>(f),
(1.4)
$T_{i}$ is the $i^{th}$ type in the template parameter pack BoundArgs,
(1.5)
${TD}_{i}$ is the type decay_t< $T_{i}$ >,
(1.6)
$t_{i}$ is the $i^{th}$ argument in the function parameter pack bound_args,
(1.7)
${td}_{i}$ is a bound argument entity of g ([func.def]) of type ${TD}_{i}$ direct-non-list-initialized with std::forward< $T_{i}$ >( $t_{i}$ ),
(1.8)
$U_{j}$ is the $j^{th}$ deduced type of the UnBoundArgs&&... parameter of the argument forwarding call wrapper, and
(1.9)
$u_{j}$ is the $j^{th}$ argument associated with $U_{j}$ .

🔗

template<class F, class... BoundArgs>
  constexpr unspecified bind(F&& f, BoundArgs&&... bound_args);
template<class R, class F, class... BoundArgs>
  constexpr unspecified bind(F&& f, BoundArgs&&... bound_args);

Mandates: is_constructible_v<FD, F> is true.

For each

T_{i}

in BoundArgs, is_constructible_v<

{TD}_{i}

T_{i}

> is true.

Preconditions: FD and each

{TD}_{i}

meet the Cpp17MoveConstructible and Cpp17Destructible requirements.

INVOKE(fd,

w_{1}

w_{2}

, …,

w_{N}

) ([func.require]) is a valid expression for some values

w_{1}

w_{2}

, …,

w_{N}

, where N has the value sizeof...(bound_args).

Returns: An argument forwarding call wrapper g ([func.require]).

A program that attempts to invoke a volatile-qualified g is ill-formed.

When g is not volatile-qualified, invocation of g(

u_{1}

u_{2}

, …,

u_{M}

) is expression-equivalent ([defns.expression-equivalent]) to

INVOKE(static_cast< $V_{fd}$ >( $v_{fd}$ ),
       static_cast< $V_{1}$ >( $v_{1}$ ), static_cast< $V_{2}$ >( $v_{2}$ ), …, static_cast< $V_{N}$ >( $v_{N}$ ))

for the first overload, and

INVOKE<R>(static_cast< $V_{fd}$ >( $v_{fd}$ ),
          static_cast< $V_{1}$ >( $v_{1}$ ), static_cast< $V_{2}$ >( $v_{2}$ ), …, static_cast< $V_{N}$ >( $v_{N}$ ))

for the second overload, where the values and types of the target argument

v_{fd}

and of the bound arguments

v_{1}

v_{2}

, …,

v_{N}

are determined as specified below.

Throws: Any exception thrown by the initialization of the state entities of g.

[ Note

If all of FD and

{TD}_{i}

meet the requirements of Cpp17CopyConstructible, then the return type meets the requirements of Cpp17CopyConstructible.

— end note

]

The values of the bound arguments

v_{1}

v_{2}

, …,

v_{N}

and their corresponding types

V_{1}

V_{2}

, …,

V_{N}

depend on the types

{TD}_{i}

derived from the call to bind and the cv-qualifiers cv of the call wrapper g as follows:

(7.1)
if ${TD}_{i}$ is reference_wrapper<T>, the argument is ${td}_{i}$ .get() and its type $V_{i}$ is T&;
(7.2)
if the value of is_bind_expression_v< ${TD}_{i}$ > is true, the argument is
```
static_cast<cv  ${TD}_{i}$ &>( ${td}_{i}$ )(std::forward< $U_{j}$ >( $u_{j}$ )...)
```
and its type $V_{i}$ is invoke_result_t<cv ${TD}_{i}$ &, $U_{j}$ ...>&&;
(7.3)
if the value j of is_placeholder_v< ${TD}_{i}$ > is not zero, the argument is std::forward< $U_{j}$ >( $u_{j}$ ) and its type $V_{i}$ is $U_{j}$ &&;
(7.4)
otherwise, the value is ${td}_{i}$ and its type $V_{i}$ is cv ${TD}_{i}$ &.

The value of the target argument

v_{fd}

is fd and its corresponding type

V_{fd}

is cv FD&.

20.14.14.4 Placeholders [func.bind.place]

namespace std::placeholders {
  // M is the implementation-defined number of placeholders
  see below _1;
  see below _2;
              .
              .
              .
  see below _M;
}

All placeholder types meet the Cpp17DefaultConstructible and Cpp17CopyConstructible requirements, and their default constructors and copy/move constructors are constexpr functions that do not throw exceptions.

It is implementation-defined whether placeholder types meet the Cpp17CopyAssignable requirements, but if so, their copy assignment operators are constexpr functions that do not throw exceptions.

Placeholders should be defined as:

inline constexpr unspecified _1{};

If they are not, they are declared as:

extern unspecified _1;

20 General utilities library [utilities]

20.14 Function objects [function.objects]

20.14.14 Function object binders [func.bind]

20.14.14.1 Class template is_­bind_­expression [func.bind.isbind]

20.14.14.2 Class template is_­placeholder [func.bind.isplace]

20.14.14.3 Function template bind [func.bind.bind]

20.14.14.4 Placeholders [func.bind.place]

20.14.14.1 Class template is_bind_expression [func.bind.isbind]

20.14.14.2 Class template is_placeholder [func.bind.isplace]