22 General utilities library [utilities]

22.10 Function objects [function.objects]

22.10.15 Function object binders [func.bind]

22.10.15.1 General [func.bind.general]

Subclause [func.bind] describes a uniform mechanism for binding arguments of callable objects.

22.10.15.2 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.

22.10.15.3 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 ([func.bind.place]).

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.

22.10.15.4 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 1:

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&.

22.10.15.5 Placeholders [func.bind.place]

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

The number M of placeholders is implementation-defined.

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;

Placeholders are freestanding items ([freestanding.item]).