23 General utilities library [utilities]

23.14 Function objects [function.objects]

23.14.11 Function object binders [func.bind]

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

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

Instantiations of the is_­bind_­expression template shall meet the UnaryTypeTrait requirements. The implementation shall provide a definition that has a base characteristic of true_­type if T is a type returned from bind, otherwise it shall have a base characteristic of false_­type. A program may specialize this template for a user-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.

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

Instantiations of the is_­placeholder template shall meet the UnaryTypeTrait requirements. The implementation shall provide a definition that has the base characteristic of integral_­constant<int, J> if T is the type of std​::​placeholders​::​_­J, otherwise it shall have a base characteristic of integral_­constant<int, 0>. A program may specialize this template for a user-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.

23.14.11.3 Function template bind [func.bind.bind]

In the text that follows:

  • FD is the type decay_­t<F>,

  • fd is an lvalue of type FD constructed from std​::​forward<F>(f),

  • Ti is the ith type in the template parameter pack BoundArgs,

  • TDi is the type decay_­t<Ti>,

  • ti is the ith argument in the function parameter pack bound_­args,

  • tdi is an lvalue of type TDi constructed from std​::​forward<Ti>(ti),

  • Uj is the jth deduced type of the UnBoundArgs&&... parameter of the forwarding call wrapper, and

  • uj is the jth argument associated with Uj.

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

Requires: is_­constructible_­v<FD, F> shall be true. For each Ti in BoundArgs, is_­constructible_­v<TDi, Ti> shall be true. INVOKE(fd, w1, w2, …, wN) ([func.require]) shall be a valid expression for some values w1, w2, …, wN, where N has the value sizeof...(bound_­args). The cv-qualifiers cv of the call wrapper g, as specified below, shall be neither volatile nor const volatile.

Returns: A forwarding call wrapper g. The effect of g(u1, u2, …, uM) shall be

INVOKE(fd, std::forward<V1>(v1), std::forward<V2>(v2), …, std::forward<VN>(vN))

where the values and types of the bound arguments v1, v2, …, vN are determined as specified below. The copy constructor and move constructor of the forwarding call wrapper shall throw an exception if and only if the corresponding constructor of FD or of any of the types TDi throws an exception.

Throws: Nothing unless the construction of fd or of one of the values tdi throws an exception.

Remarks: The return type shall satisfy the requirements of MoveConstructible. If all of FD and TDi satisfy the requirements of CopyConstructible, then the return type shall satisfy the requirements of CopyConstructible. [Note: This implies that all of FD and TDi are MoveConstructible. end note]

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

Requires: is_­constructible_­v<FD, F> shall be true. For each Ti in BoundArgs, is_­constructible_­v<TDi, Ti> shall be true. INVOKE(fd, w1, w2, …, wN) shall be a valid expression for some values w1, w2, …, wN, where N has the value sizeof...(bound_­args). The cv-qualifiers cv of the call wrapper g, as specified below, shall be neither volatile nor const volatile.

Returns: A forwarding call wrapper g. The effect of g(u1, u2, …, uM) shall be

INVOKE<R>(fd, std::forward<V1>(v1), std::forward<V2>(v2), …, std::forward<VN>(vN))

where the values and types of the bound arguments v1, v2, …, vN are determined as specified below. The copy constructor and move constructor of the forwarding call wrapper shall throw an exception if and only if the corresponding constructor of FD or of any of the types TDi throws an exception.

Throws: Nothing unless the construction of fd or of one of the values tdi throws an exception.

Remarks: The return type shall satisfy the requirements of MoveConstructible. If all of FD and TDi satisfy the requirements of CopyConstructible, then the return type shall satisfy the requirements of CopyConstructible. [Note: This implies that all of FD and TDi are MoveConstructible. end note]

The values of the bound arguments v1, v2, …, vN and their corresponding types V1, V2, …, VN depend on the types TDi derived from the call to bind and the cv-qualifiers cv of the call wrapper g as follows:

  • if TDi is reference_­wrapper<T>, the argument is tdi.get() and its type Vi is T&;

  • if the value of is_­bind_­expression_­v<TDi> is true, the argument is tdi(std​::​forward<Uj>(uj)...) and its type Vi is invoke_­result_­t<TDi cv &, Uj...>&&;

  • if the value j of is_­placeholder_­v<TDi> is not zero, the argument is std​::​forward<Uj>(uj) and its type Vi is Uj&&;

  • otherwise, the value is tdi and its type Vi is TDi cv &.

23.14.11.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 shall be DefaultConstructible and CopyConstructible, and their default constructors and copy/move constructors shall not throw exceptions. It is implementation-defined whether placeholder types are CopyAssignable. CopyAssignable placeholders' copy assignment operators shall not throw exceptions.

Placeholders should be defined as:

inline constexpr unspecified _1{};

If they are not, they shall be declared as:

extern unspecified _1;