20 General utilities library [utilities]

20.9 Function objects [function.objects]

1

A function object type is an object type ([basic.types]) that can be the type of the postfix-expression in a function call ([expr.call], [over.match.call]).231 A function object is an object of a function object type. In the places where one would expect to pass a pointer to a function to an algorithmic template (Clause [algorithms]), the interface is specified to accept a function object. This not only makes algorithmic templates work with pointers to functions, but also enables them to work with arbitrary function objects.

2

Header <functional> synopsis

namespace std {
  // [depr.base], base (deprecated):
  template <class Arg, class Result> struct unary_function;
  template <class Arg1, class Arg2, class Result> struct binary_function;

  // [refwrap], reference_wrapper:
  template <class T> class reference_wrapper;

  template <class T> reference_wrapper<T> ref(T&) noexcept;
  template <class T> reference_wrapper<const T> cref(const T&) noexcept;
  template <class T> void ref(const T&&) = delete;
  template <class T> void cref(const T&&) = delete;

  template <class T> reference_wrapper<T> ref(reference_wrapper<T>) noexcept;
  template <class T> reference_wrapper<const T> cref(reference_wrapper<T>) noexcept;

  // [arithmetic.operations], arithmetic operations:
  template <class T = void> struct plus;
  template <class T = void> struct minus;
  template <class T = void> struct multiplies;
  template <class T = void> struct divides;
  template <class T = void> struct modulus;
  template <class T = void> struct negate;
  template <> struct plus<void>;
  template <> struct minus<void>;
  template <> struct multiplies<void>;
  template <> struct divides<void>;
  template <> struct modulus<void>;
  template <> struct negate<void>;

  // [comparisons], comparisons:
  template <class T = void> struct equal_to;
  template <class T = void> struct not_equal_to;
  template <class T = void> struct greater;
  template <class T = void> struct less;
  template <class T = void> struct greater_equal;
  template <class T = void> struct less_equal;
  template <> struct equal_to<void>;
  template <> struct not_equal_to<void>;
  template <> struct greater<void>;
  template <> struct less<void>;
  template <> struct greater_equal<void>;
  template <> struct less_equal<void>;

  // [logical.operations], logical operations:
  template <class T = void> struct logical_and;
  template <class T = void> struct logical_or;
  template <class T = void> struct logical_not;
  template <> struct logical_and<void>;
  template <> struct logical_or<void>;
  template <> struct logical_not<void>;

  // [bitwise.operations], bitwise operations:
  template <class T = void> struct bit_and;
  template <class T = void> struct bit_or;
  template <class T = void> struct bit_xor;
  template <class T = void> struct bit_not;
  template <> struct bit_and<void>;
  template <> struct bit_or<void>;
  template <> struct bit_xor<void>;
  template <> struct bit_not<void>;

  // [negators], negators:
  template <class Predicate> class unary_negate;
  template <class Predicate>
    constexpr unary_negate<Predicate> not1(const Predicate&);
  template <class Predicate> class binary_negate;
  template <class Predicate>
    constexpr binary_negate<Predicate> not2(const Predicate&);

  // [func.bind], bind:
  template<class T> struct is_bind_expression;
  template<class T> struct is_placeholder;

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

  namespace placeholders {
    // M is the implementation-defined number of placeholders
    extern unspecified _1;
    extern unspecified _2;
                .
                .
                .
    extern unspecified _M;
  }

  // [depr.lib.binders], binders (deprecated):
  template <class Fn> class binder1st;
  template <class Fn, class T>
    binder1st<Fn> bind1st(const Fn&, const T&);
  template <class Fn> class binder2nd;
  template <class Fn, class T>
    binder2nd<Fn> bind2nd(const Fn&, const T&);

  // [depr.function.pointer.adaptors], adaptors (deprecated):
  template <class Arg, class Result> class pointer_to_unary_function;
  template <class Arg, class Result>
    pointer_to_unary_function<Arg,Result> ptr_fun(Result (*)(Arg));
  template <class Arg1, class Arg2, class Result>
    class pointer_to_binary_function;
  template <class Arg1, class Arg2, class Result>
    pointer_to_binary_function<Arg1,Arg2,Result>
      ptr_fun(Result (*)(Arg1,Arg2));

  // [depr.member.pointer.adaptors], adaptors (deprecated):
  template<class S, class T> class mem_fun_t;
  template<class S, class T, class A> class mem_fun1_t;
  template<class S, class T>
      mem_fun_t<S,T> mem_fun(S (T::*f)());
  template<class S, class T, class A>
      mem_fun1_t<S,T,A> mem_fun(S (T::*f)(A));
  template<class S, class T> class mem_fun_ref_t;
  template<class S, class T, class A> class mem_fun1_ref_t;
  template<class S, class T>
      mem_fun_ref_t<S,T> mem_fun_ref(S (T::*f)());
  template<class S, class T, class A>
      mem_fun1_ref_t<S,T,A> mem_fun_ref(S (T::*f)(A));

  template <class S, class T> class const_mem_fun_t;
  template <class S, class T, class A> class const_mem_fun1_t;
  template <class S, class T>
    const_mem_fun_t<S,T> mem_fun(S (T::*f)() const);
  template <class S, class T, class A>
    const_mem_fun1_t<S,T,A> mem_fun(S (T::*f)(A) const);
  template <class S, class T> class const_mem_fun_ref_t;
  template <class S, class T, class A> class const_mem_fun1_ref_t;
  template <class S, class T>
    const_mem_fun_ref_t<S,T> mem_fun_ref(S (T::*f)() const);
  template <class S, class T, class A>
    const_mem_fun1_ref_t<S,T,A> mem_fun_ref(S (T::*f)(A) const);

  // [func.memfn], member function adaptors:
  template<class R, class T> unspecified mem_fn(R T::*);

  // [func.wrap] polymorphic function wrappers:
  class bad_function_call;

  template<class> class function; // undefined
  template<class R, class... ArgTypes> class function<R(ArgTypes...)>;

  template<class R, class... ArgTypes>
    void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&);

  template<class R, class... ArgTypes>
    bool operator==(const function<R(ArgTypes...)>&, nullptr_t);
  template<class R, class... ArgTypes>
    bool operator==(nullptr_t, const function<R(ArgTypes...)>&);
  template<class R, class... ArgTypes>
    bool operator!=(const function<R(ArgTypes...)>&, nullptr_t);
  template<class R, class... ArgTypes>
    bool operator!=(nullptr_t, const function<R(ArgTypes...)>&);

  // [unord.hash], hash function primary template:
  template <class T> struct hash;

  // Hash function specializations
  template <> struct hash<bool>;
  template <> struct hash<char>;
  template <> struct hash<signed char>;
  template <> struct hash<unsigned char>;
  template <> struct hash<char16_t>;
  template <> struct hash<char32_t>;
  template <> struct hash<wchar_t>;
  template <> struct hash<short>;
  template <> struct hash<unsigned short>;
  template <> struct hash<int>;
  template <> struct hash<unsigned int>;
  template <> struct hash<long>;
  template <> struct hash<long long>;
  template <> struct hash<unsigned long>;
  template <> struct hash<unsigned long long>;

  template <> struct hash<float>;
  template <> struct hash<double>;
  template <> struct hash<long double>;

  template<class T> struct hash<T*>;
}
3

[ Example: If a C++ program wants to have a by-element addition of two vectors a and b containing double and put the result into a, it can do:

transform(a.begin(), a.end(), b.begin(), a.begin(), plus<double>());

 — end example ]

4

[ Example: To negate every element of a:

transform(a.begin(), a.end(), a.begin(), negate<double>());

 — end example ]

5

[ Note: To enable adaptors and other components to manipulate function objects that take one or two arguments many of the function objects in this clause correspondingly provide typedefs argument_type and result_type for function objects that take one argument and first_argument_type, second_argument_type, and result_type for function objects that take two arguments.  — end note ]

230)

Such a type is a function pointer or a class type which has a member operator() or a class type which has a conversion to a pointer to function.

20.9.1 Definitions [func.def]

1

The following definitions apply to this Clause:

2

A call signature is the name of a return type followed by a parenthesized comma-separated list of zero or more argument types.

3

A callable type is a function object type ([function.objects]) or a pointer to member.

4

A callable object is an object of a callable type.

5

A call wrapper type is a type that holds a callable object and supports a call operation that forwards to that object.

6

A call wrapper is an object of a call wrapper type.

7

A target object is the callable object held by a call wrapper.

20.9.2 Requirements [func.require]

1

Define INVOKE(f, t1, t2, ..., tN) as follows:

  • (1.1)

    (t1.*f)(t2, ..., tN) when f is a pointer to a member function of a class T and t1 is an object of type T or a reference to an object of type T or a reference to an object of a type derived from T;

  • (1.2)

    ((*t1).*f)(t2, ..., tN) when f is a pointer to a member function of a class T and t1 is not one of the types described in the previous item;

  • (1.3)

    t1.*f when N == 1 and f is a pointer to member data of a class T and t1 is an object of type T or a reference to an object of type T or a reference to an object of a type derived from T;

  • (1.4)

    (*t1).*f when N == 1 and f is a pointer to member data of a class T and t1 is not one of the types described in the previous item;

  • (1.5)

    f(t1, t2, ..., tN) in all other cases.

2

Define INVOKE(f, t1, t2, ..., tN, R) as INVOKE(f, t1, t2, ..., tN) implicitly converted to R.

3

If a call wrapper ([func.def]) has a weak result type the type of its member type result_type is based on the type T of the wrapper's target object ([func.def]):

  • (3.1)

    if T is a pointer to function type, result_type shall be a synonym for the return type of T;

  • (3.2)

    if T is a pointer to member function, result_type shall be a synonym for the return type of T;

  • (3.3)

    if T is a class type with a member type result_type, then result_type shall be a synonym for T::result_type;

  • (3.4)

    otherwise result_type shall not be defined.

4

Every call wrapper ([func.def]) shall be MoveConstructible. A simple call wrapper is a call wrapper that is CopyConstructible and CopyAssignable and whose copy constructor, move constructor, and assignment operator do not throw exceptions. A forwarding call wrapper is a call wrapper that can be called with an arbitrary argument list and delivers the arguments to the wrapped callable object as references. This forwarding step shall ensure that rvalue arguments are delivered as rvalue-references and lvalue arguments are delivered as lvalue-references. [ Note: In a typical implementation forwarding call wrappers have an overloaded function call operator of the form

template<class... UnBoundArgs>
R operator()(UnBoundArgs&&... unbound_args) cv-qual;

 — end note ]

20.9.3 Class template reference_wrapper [refwrap]

namespace std {
  template <class T> class reference_wrapper {
  public :
    // types
    typedef T type;
    typedef see below result_type;               // not always defined
    typedef see below argument_type;             // not always defined
    typedef see below first_argument_type;       // not always defined
    typedef see below second_argument_type;      // not always defined

    // construct/copy/destroy
    reference_wrapper(T&) noexcept;
    reference_wrapper(T&&) = delete;     // do not bind to temporary objects
    reference_wrapper(const reference_wrapper& x) noexcept;

    // assignment
    reference_wrapper& operator=(const reference_wrapper& x) noexcept;

    // access
    operator T& () const noexcept;
    T& get() const noexcept;

    // invocation
    template <class... ArgTypes>
    result_of_t<T&(ArgTypes&&...)>
    operator() (ArgTypes&&...) const;
  };
}
1

reference_wrapper<T> is a CopyConstructible and CopyAssignable wrapper around a reference to an object or function of type T.

2

reference_wrapper<T> has a weak result type ([func.require]). If T is a function type, result_type shall be a synonym for the return type of T.

3

The template specialization reference_wrapper<T> shall define a nested type named argument_type as a synonym for T1 only if the type T is any of the following:

  • (3.1)

    a function type or a pointer to function type taking one argument of type T1

  • (3.2)

    a pointer to member function R T0::f cv (where cv represents the member function's cv-qualifiers); the type T1 is cv T0*

  • (3.3)

    a class type with a member type argument_type; the type T1 is T::argument_type.

4

The template instantiation reference_wrapper<T> shall define two nested types named first_argument_type and second_argument_type as synonyms for T1 and T2, respectively, only if the type T is any of the following:

  • (4.1)

    a function type or a pointer to function type taking two arguments of types T1 and T2

  • (4.2)

    a pointer to member function R T0::f(T2) cv (where cv represents the member function's cv-qualifiers); the type T1 is cv T0*

  • (4.3)

    a class type with member types first_argument_type and second_argument_type; the type T1 is T::first_argument_type and the type T2 is T::second_argument_type.

20.9.3.1 reference_wrapper construct/copy/destroy [refwrap.const]

reference_wrapper(T& t) noexcept;

1

Effects: Constructs a reference_wrapper object that stores a reference to t.

reference_wrapper(const reference_wrapper& x) noexcept;

2

Effects: Constructs a reference_wrapper object that stores a reference to x.get().

20.9.3.2 reference_wrapper assignment [refwrap.assign]

reference_wrapper& operator=(const reference_wrapper& x) noexcept;

1

Postconditions: *this stores a reference to x.get().

20.9.3.3 reference_wrapper access [refwrap.access]

operator T& () const noexcept;

1

Returns: The stored reference.

T& get() const noexcept;

2

Returns: The stored reference.

20.9.3.4 reference_wrapper invocation [refwrap.invoke]

template <class... ArgTypes> result_of_t<T&(ArgTypes&&... )> operator()(ArgTypes&&... args) const;

1

Returns: INVOKE(get(), std::forward<ArgTypes>(args)...). ([func.require])

2

Remark: operator() is described for exposition only. Implementations are not required to provide an actual reference_wrapper::operator(). Implementations are permitted to support reference_wrapper function invocation through multiple overloaded operators or through other means.

20.9.3.5 reference_wrapper helper functions [refwrap.helpers]

template <class T> reference_wrapper<T> ref(T& t) noexcept;

1

Returns: reference_wrapper<T>(t)

template <class T> reference_wrapper<T> ref(reference_wrapper<T> t) noexcept;

2

Returns: ref(t.get())

template <class T> reference_wrapper<const T> cref(const T& t) noexcept;

3

Returns: reference_wrapper <const T>(t)

template <class T> reference_wrapper<const T> cref(reference_wrapper<T> t) noexcept;

4

Returns: cref(t.get());

20.9.4 Arithmetic operations [arithmetic.operations]

1

The library provides basic function object classes for all of the arithmetic operators in the language ([expr.mul], [expr.add]).

template <class T = void> struct plus { constexpr T operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef T result_type; };

2

operator() returns x + y.

template <class T = void> struct minus { constexpr T operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef T result_type; };

3

operator() returns x - y.

template <class T = void> struct multiplies { constexpr T operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef T result_type; };

4

operator() returns x * y.

template <class T = void> struct divides { constexpr T operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef T result_type; };

5

operator() returns x / y.

template <class T = void> struct modulus { constexpr T operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef T result_type; };

6

operator() returns x % y.

template <class T = void> struct negate { constexpr T operator()(const T& x) const; typedef T argument_type; typedef T result_type; };

7

operator() returns -x.

template <> struct plus<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) + std::forward<U>(u)); typedef unspecified is_transparent; };

8

operator() returns std::forward<T>(t) + std::forward<U>(u).

template <> struct minus<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) - std::forward<U>(u)); typedef unspecified is_transparent; };

9

operator() returns std::forward<T>(t) - std::forward<U>(u).

template <> struct multiplies<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) * std::forward<U>(u)); typedef unspecified is_transparent; };

10

operator() returns std::forward<T>(t) * std::forward<U>(u).

template <> struct divides<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) / std::forward<U>(u)); typedef unspecified is_transparent; };

11

operator() returns std::forward<T>(t) / std::forward<U>(u).

template <> struct modulus<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) % std::forward<U>(u)); typedef unspecified is_transparent; };

12

operator() returns std::forward<T>(t) % std::forward<U>(u).

template <> struct negate<void> { template <class T> constexpr auto operator()(T&& t) const -> decltype(-std::forward<T>(t)); typedef unspecified is_transparent; };

13

operator() returns -std::forward<T>(t).

20.9.5 Comparisons [comparisons]

1

The library provides basic function object classes for all of the comparison operators in the language ([expr.rel], [expr.eq]).

template <class T = void> struct equal_to { constexpr bool operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef bool result_type; };

2

operator() returns x == y.

template <class T = void> struct not_equal_to { constexpr bool operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef bool result_type; };

3

operator() returns x != y.

template <class T = void> struct greater { constexpr bool operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef bool result_type; };

4

operator() returns x > y.

template <class T = void> struct less { constexpr bool operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef bool result_type; };

5

operator() returns x < y.

template <class T = void> struct greater_equal { constexpr bool operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef bool result_type; };

6

operator() returns x >= y.

template <class T = void> struct less_equal { constexpr bool operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef bool result_type; };

7

operator() returns x <= y.

template <> struct equal_to<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) == std::forward<U>(u)); typedef unspecified is_transparent; };

8

operator() returns std::forward<T>(t) == std::forward<U>(u).

template <> struct not_equal_to<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) != std::forward<U>(u)); typedef unspecified is_transparent; };

9

operator() returns std::forward<T>(t) != std::forward<U>(u).

template <> struct greater<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) > std::forward<U>(u)); typedef unspecified is_transparent; };

10

operator() returns std::forward<T>(t) > std::forward<U>(u).

template <> struct less<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) < std::forward<U>(u)); typedef unspecified is_transparent; };

11

operator() returns std::forward<T>(t) < std::forward<U>(u).

template <> struct greater_equal<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) >= std::forward<U>(u)); typedef unspecified is_transparent; };

12

operator() returns std::forward<T>(t) >= std::forward<U>(u).

template <> struct less_equal<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) <= std::forward<U>(u)); typedef unspecified is_transparent; };

13

operator() returns std::forward<T>(t) <= std::forward<U>(u).

14

For templates greater, less, greater_equal, and less_equal, the specializations for any pointer type yield a total order, even if the built-in operators <, >, <=, >= do not.

20.9.6 Logical operations [logical.operations]

1

The library provides basic function object classes for all of the logical operators in the language ([expr.log.and], [expr.log.or], [expr.unary.op]).

template <class T = void> struct logical_and { constexpr bool operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef bool result_type; };

2

operator() returns x && y.

template <class T = void> struct logical_or { constexpr bool operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef bool result_type; };

3

operator() returns x || y.

template <class T = void> struct logical_not { constexpr bool operator()(const T& x) const; typedef T argument_type; typedef bool result_type; };

4

operator() returns !x.

template <> struct logical_and<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) && std::forward<U>(u)); typedef unspecified is_transparent; };

5

operator() returns std::forward<T>(t) && std::forward<U>(u).

template <> struct logical_or<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) || std::forward<U>(u)); typedef unspecified is_transparent; };

6

operator() returns std::forward<T>(t) || std::forward<U>(u).

template <> struct logical_not<void> { template <class T> constexpr auto operator()(T&& t) const -> decltype(!std::forward<T>(t)); typedef unspecified is_transparent; };

7

operator() returns !std::forward<T>(t).

20.9.7 Bitwise operations [bitwise.operations]

1

The library provides basic function object classes for all of the bitwise operators in the language ([expr.bit.and], [expr.or], [expr.xor], [expr.unary.op]).

template <class T = void> struct bit_and { constexpr T operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef T result_type; };

2

operator() returns x & y.

template <class T = void> struct bit_or { constexpr T operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef T result_type; };

3

operator() returns x | y.

template <class T = void> struct bit_xor { constexpr T operator()(const T& x, const T& y) const; typedef T first_argument_type; typedef T second_argument_type; typedef T result_type; };

4

operator() returns x ^ y.

template <class T = void> struct bit_not { constexpr T operator()(const T& x) const; typedef T argument_type; typedef T result_type; };

5

operator() returns ~x.

template <> struct bit_and<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) & std::forward<U>(u)); typedef unspecified is_transparent; };

6

operator() returns std::forward<T>(t) & std::forward<U>(u).

template <> struct bit_or<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) | std::forward<U>(u)); typedef unspecified is_transparent; };

7

operator() returns std::forward<T>(t) | std::forward<U>(u).

template <> struct bit_xor<void> { template <class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) ^ std::forward<U>(u)); typedef unspecified is_transparent; };

8

operator() returns std::forward<T>(t) ^ std::forward<U>(u).

template <> struct bit_not<void> { template <class T> constexpr auto operator()(T&& t) const -> decltype(~std::forward<T>(t)); typedef unspecified is_transparent; };

9

operator() returns ~std::forward<T>(t).

20.9.8 Negators [negators]

1

Negators not1 and not2 take a unary and a binary predicate, respectively, and return their complements ([expr.unary.op]).

template <class Predicate> class unary_negate { public: constexpr explicit unary_negate(const Predicate& pred); constexpr bool operator()(const typename Predicate::argument_type& x) const; typedef typename Predicate::argument_type argument_type; typedef bool result_type; };

2

operator() returns !pred(x).

template <class Predicate> constexpr unary_negate<Predicate> not1(const Predicate& pred);

3

Returns: unary_negate<Predicate>(pred).

template <class Predicate> class binary_negate { public: constexpr explicit binary_negate(const Predicate& pred); constexpr bool operator()(const typename Predicate::first_argument_type& x, const typename Predicate::second_argument_type& y) const; typedef typename Predicate::first_argument_type first_argument_type; typedef typename Predicate::second_argument_type second_argument_type; typedef bool result_type; };

4

operator() returns !pred(x,y).

template <class Predicate> constexpr binary_negate<Predicate> not2(const Predicate& pred);

5

Returns: binary_negate<Predicate>(pred).

20.9.9 Function object binders [func.bind]

1

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

20.9.9.1 Class template is_bind_expression [func.bind.isbind]

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

is_bind_expression can be used to detect function objects generated by bind. bind uses is_bind_expression to detect subexpressions.

2

Instantiations of the is_bind_expression template shall meet the UnaryTypeTrait requirements ([meta.rqmts]). The implementation shall provide a definition that has a BaseCharacteristic of true_type if T is a type returned from bind, otherwise it shall have a BaseCharacteristic of false_type. A program may specialize this template for a user-defined type T to have a BaseCharacteristic of true_type to indicate that T should be treated as a subexpression in a bind call.

20.9.9.2 Class template is_placeholder [func.bind.isplace]

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

is_placeholder can be used to detect the standard placeholders _1, _2, and so on. bind uses is_placeholder to detect placeholders.

2

Instantiations of the is_placeholder template shall meet the UnaryTypeTrait requirements ([meta.rqmts]). The implementation shall provide a definition that has the BaseCharacteristic of integral_constant<int, J> if T is the type of std::placeholders::_J, otherwise it shall have a BaseCharacteristic of integral_constant<int, 0>. A program may specialize this template for a user-defined type T to have a BaseCharacteristic of integral_constant<int, N> with N > 0 to indicate that T should be treated as a placeholder type.

20.9.9.3 Function template bind [func.bind.bind]

1

In the text that follows, the following names have the following meanings:

  • (1.1)

    FD is the type decay_t<F>,

  • (1.2)

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

  • (1.3)

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

  • (1.4)

    TiD is the type decay_t<Ti>,

  • (1.5)

    ti is the ith argument in the function parameter pack bound_args,

  • (1.6)

    tid is an lvalue of type TiD constructed from std::forward<Ti>(ti),

  • (1.7)

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

  • (1.8)

    uj is the jth argument associated with Uj.

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

2

Requires: is_constructible<FD, F>::value shall be true. For each Ti in BoundArgs, is_constructible<TiD, Ti>::value shall be true. INVOKE (fd, w1, w2, ..., wN) ([func.require]) shall be a valid expression for some values w1, w2, ..., wN, where N == sizeof...(bound_args).

3

Returns: A forwarding call wrapper g with a weak result type ([func.require]). The effect of g(u1, u2, ..., uM) shall be INVOKE(fd, std::forward<V1>(v1), std::forward<V2>(v2), ..., std::forward<VN>(vN), result_of_t<FD cv & (V1, V2, ..., VN)>), where cv represents the cv-qualifiers of g and 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 TiD throws an exception.

4

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

5

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

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

6

Requires: is_constructible<FD, F>::value shall be true. For each Ti in BoundArgs, is_constructible<TiD, Ti>::value shall be true. INVOKE(fd, w1, w2, ..., wN) shall be a valid expression for some values w1, w2, ..., wN, where N == sizeof...(bound_args).

7

Returns: A forwarding call wrapper g with a nested type result_type defined as a synonym for R. The effect of g(u1, u2, ..., uM) shall be INVOKE(fd, std::forward<V1>(v1), std::forward<V2>(v2), ..., std::forward<VN>(vN), R), 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 TiD throws an exception.

8

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

9

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

10

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

  • (10.1)

    if TiD is reference_wrapper<T>, the argument is tid.get() and its type Vi is T&;

  • (10.2)

    if the value of is_bind_expression<TiD>::value is true, the argument is tid(std::forward<Uj>(uj)...) and its type Vi is result_of_t<TiD cv & (Uj&&...)>&&;

  • (10.3)

    if the value j of is_placeholder<TiD>::value is not zero, the argument is std::forward<Uj>(uj) and its type Vi is Uj&&;

  • (10.4)

    otherwise, the value is tid and its type Vi is TiD cv &.

20.9.9.4 Placeholders [func.bind.place]

namespace std {
  namespace placeholders {
    // M is the implementation-defined number of placeholders
    extern unspecified _1;
    extern unspecified _2;
                .
                .
                .
    extern unspecified _M;
  }
}
1

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.

20.9.10 Function template mem_fn [func.memfn]

template<class R, class T> unspecified mem_fn(R T::* pm);

1

Returns: A simple call wrapper ([func.def]) fn such that the expression fn(t, a2, ..., aN) is equivalent to INVOKE(pm, t, a2, ..., aN) ([func.require]). fn shall have a nested type result_type that is a synonym for the return type of pm when pm is a pointer to member function.

2

The simple call wrapper shall define two nested types named argument_type and result_type as synonyms for cv T* and Ret, respectively, when pm is a pointer to member function with cv-qualifier cv and taking no arguments, where Ret is pm's return type.

3

The simple call wrapper shall define three nested types named first_argument_type, second_argument_type, and result_type as synonyms for cv T*, T1, and Ret, respectively, when pm is a pointer to member function with cv-qualifier cv and taking one argument of type T1, where Ret is pm's return type.

4

Throws: Nothing.

20.9.11 Polymorphic function wrappers [func.wrap]

1

This subclause describes a polymorphic wrapper class that encapsulates arbitrary callable objects.

20.9.11.1 Class bad_function_call [func.wrap.badcall]

1

An exception of type bad_function_call is thrown by function::operator() ([func.wrap.func.inv]) when the function wrapper object has no target.

namespace std {
  class bad_function_call : public std::exception {
  public:
    // [func.wrap.badcall.const], constructor:
    bad_function_call() noexcept;
  };
} // namespace std

20.9.11.1.1 bad_function_call constructor [func.wrap.badcall.const]

bad_function_call() noexcept;

1

Effects: constructs a bad_function_call object.

20.9.11.2 Class template function [func.wrap.func]

namespace std {
  template<class> class function; // undefined

  template<class R, class... ArgTypes>
  class function<R(ArgTypes...)> {
  public:
    typedef R result_type;
    typedef T1 argument_type;           // only if sizeof...(ArgTypes) == 1 and
                                        // the type in ArgTypes is T1
    typedef T1 first_argument_type;     // only if sizeof...(ArgTypes) == 2 and
                                        // ArgTypes contains T1 and T2
    typedef T2 second_argument_type;    // only if sizeof...(ArgTypes) == 2 and
                                        // ArgTypes contains T1 and T2

    // [func.wrap.func.con], construct/copy/destroy:
    function() noexcept;
    function(nullptr_t) noexcept;
    function(const function&);
    function(function&&);
    template<class F> function(F);
    template<class A> function(allocator_arg_t, const A&) noexcept;
    template<class A> function(allocator_arg_t, const A&,
      nullptr_t) noexcept;
    template<class A> function(allocator_arg_t, const A&,
      const function&);
    template<class A> function(allocator_arg_t, const A&,
      function&&);
    template<class F, class A> function(allocator_arg_t, const A&, F);

    function& operator=(const function&);
    function& operator=(function&&);
    function& operator=(nullptr_t);
    template<class F> function& operator=(F&&);
    template<class F> function& operator=(reference_wrapper<F>) noexcept;

    ~function();

    // [func.wrap.func.mod], function modifiers:
    void swap(function&) noexcept;
    template<class F, class A> void assign(F&&, const A&);

    // [func.wrap.func.cap], function capacity:
    explicit operator bool() const noexcept;

    // [func.wrap.func.inv], function invocation:
    R operator()(ArgTypes...) const;

    // [func.wrap.func.targ], function target access:
    const std::type_info& target_type() const noexcept;
    template<class T>       T* target() noexcept;
    template<class T> const T* target() const noexcept;

  };

  // [func.wrap.func.nullptr], Null pointer comparisons:
  template <class R, class... ArgTypes>
    bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;

  template <class R, class... ArgTypes>
    bool operator==(nullptr_t, const function<R(ArgTypes...)>&) noexcept;

  template <class R, class... ArgTypes>
    bool operator!=(const function<R(ArgTypes...)>&, nullptr_t) noexcept;

  template <class R, class... ArgTypes>
    bool operator!=(nullptr_t, const function<R(ArgTypes...)>&) noexcept;

  // [func.wrap.func.alg], specialized algorithms:
  template <class R, class... ArgTypes>
    void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&);

  template<class R, class... ArgTypes, class Alloc>
    struct uses_allocator<function<R(ArgTypes...)>, Alloc>
      : true_type { };
}
1

The function class template provides polymorphic wrappers that generalize the notion of a function pointer. Wrappers can store, copy, and call arbitrary callable objects ([func.def]), given a call signature ([func.def]), allowing functions to be first-class objects.

2

A callable object f of type F is Callable for argument types ArgTypes and return type R if the expression INVOKE(f, declval<ArgTypes>()..., R), considered as an unevaluated operand (Clause [expr]), is well formed ([func.require]).

3

The function class template is a call wrapper ([func.def]) whose call signature ([func.def]) is R(ArgTypes...).

20.9.11.2.1 function construct/copy/destroy [func.wrap.func.con]

1

When any function constructor that takes a first argument of type allocator_arg_t is invoked, the second argument shall have a type that conforms to the requirements for Allocator (Table [allocator.requirements]). A copy of the allocator argument is used to allocate memory, if necessary, for the internal data structures of the constructed function object.

function() noexcept; template <class A> function(allocator_arg_t, const A& a) noexcept;

2

Postconditions: !*this.

function(nullptr_t) noexcept; template <class A> function(allocator_arg_t, const A& a, nullptr_t) noexcept;

3

Postconditions: !*this.

function(const function& f); template <class A> function(allocator_arg_t, const A& a, const function& f);

4

Postconditions: !*this if !f; otherwise, *this targets a copy of f.target().

5

Throws: shall not throw exceptions if f's target is a callable object passed via reference_wrapper or a function pointer. Otherwise, may throw bad_alloc or any exception thrown by the copy constructor of the stored callable object. [ Note: Implementations are encouraged to avoid the use of dynamically allocated memory for small callable objects, for example, where f's target is an object holding only a pointer or reference to an object and a member function pointer.  — end note ]

function(function&& f); template <class A> function(allocator_arg_t, const A& a, function&& f);

6

Effects: If !f, *this has no target; otherwise, move-constructs the target of f into the target of *this, leaving f in a valid state with an unspecified value.

template<class F> function(F f); template <class F, class A> function(allocator_arg_t, const A& a, F f);

7

Requires: F shall be CopyConstructible.

8

Remarks: These constructors shall not participate in overload resolution unless f is Callable ([func.wrap.func]) for argument types ArgTypes... and return type R.

9

Postconditions: !*this if any of the following hold:

  • (9.1)

    f is a null function pointer value.

  • (9.2)

    f is a null member pointer value.

  • (9.3)

    F is an instance of the function class template, and !f.

10

Otherwise, *this targets a copy of f initialized with std::move(f). [ Note: Implementations are encouraged to avoid the use of dynamically allocated memory for small callable objects, for example, where f's target is an object holding only a pointer or reference to an object and a member function pointer.  — end note ]

11

Throws: shall not throw exceptions when f is a function pointer or a reference_wrapper<T> for some T. Otherwise, may throw bad_alloc or any exception thrown by F's copy or move constructor.

function& operator=(const function& f);

12

Effects: function(f).swap(*this);

13

Returns: *this

function& operator=(function&& f);

14

Effects: Replaces the target of *this with the target of f.

15

Returns: *this

function& operator=(nullptr_t);

16

Effects: If *this != nullptr, destroys the target of this.

17

Postconditions: !(*this).

18

Returns: *this

template<class F> function& operator=(F&& f);

19

Effects: function(std::forward<F>(f)).swap(*this);

20

Returns: *this

21

Remarks: This assignment operator shall not participate in overload resolution unless declval<typename decay<F>::type&>() is Callable ([func.wrap.func]) for argument types ArgTypes... and return type R.

template<class F> function& operator=(reference_wrapper<F> f) noexcept;

22

Effects: function(f).swap(*this);

23

Returns: *this

~function();

24

Effects: If *this != nullptr, destroys the target of this.

20.9.11.2.2 function modifiers [func.wrap.func.mod]

void swap(function& other) noexcept;

1

Effects: interchanges the targets of *this and other.

template<class F, class A> void assign(F&& f, const A& a);

2

Effects: function(allocator_arg, a, std::forward<F>(f)).swap(*this)

20.9.11.2.3 function capacity [func.wrap.func.cap]

explicit operator bool() const noexcept;

1

Returns: true if *this has a target, otherwise false.

20.9.11.2.4 function invocation [func.wrap.func.inv]

R operator()(ArgTypes... args) const

1

Effects: INVOKE(f, std::forward<ArgTypes>(args)..., R) ([func.require]), where f is the target object ([func.def]) of *this.

2

Returns: Nothing if R is void, otherwise the return value of INVOKE(f, std::forward<ArgTypes>(args)..., R).

3

Throws: bad_function_call if !*this; otherwise, any exception thrown by the wrapped callable object.

20.9.11.2.5 function target access [func.wrap.func.targ]

const std::type_info& target_type() const noexcept;

1

Returns: If *this has a target of type T, typeid(T); otherwise, typeid(void).

template<class T> T* target() noexcept; template<class T> const T* target() const noexcept;

2

Requires: T shall be a type that is Callable ([func.wrap.func]) for parameter types ArgTypes and return type R.

3

Returns: If target_type() == typeid(T) a pointer to the stored function target; otherwise a null pointer.

20.9.11.2.6 null pointer comparison operators [func.wrap.func.nullptr]

template <class R, class... ArgTypes> bool operator==(const function<R(ArgTypes...)>& f, nullptr_t) noexcept; template <class R, class... ArgTypes> bool operator==(nullptr_t, const function<R(ArgTypes...)>& f) noexcept;

1

Returns: !f.

template <class R, class... ArgTypes> bool operator!=(const function<R(ArgTypes...)>& f, nullptr_t) noexcept; template <class R, class... ArgTypes> bool operator!=(nullptr_t, const function<R(ArgTypes...)>& f) noexcept;

2

Returns: (bool) f.

20.9.11.2.7 specialized algorithms [func.wrap.func.alg]

template<class R, class... ArgTypes> void swap(function<R(ArgTypes...)>& f1, function<R(ArgTypes...)>& f2);

1

Effects: f1.swap(f2);

20.9.12 Class template hash [unord.hash]

1

The unordered associative containers defined in [unord] use specializations of the class template hash as the default hash function. For all object types Key for which there exists a specialization hash<Key>, and for all enumeration types ([dcl.enum]) Key, the instantiation hash<Key> shall:

  • (1.1)

    satisfy the Hash requirements ([hash.requirements]), with Key as the function call argument type, the DefaultConstructible requirements (Table [defaultconstructible]), the CopyAssignable requirements (Table [copyassignable]),

  • (1.2)

    be swappable ([swappable.requirements]) for lvalues,

  • (1.3)

    provide two nested types result_type and argument_type which shall be synonyms for size_t and Key, respectively,

  • (1.4)

    satisfy the requirement that if k1 == k2 is true, h(k1) == h(k2) is also true, where h is an object of type hash<Key> and k1 and k2 are objects of type Key;

  • (1.5)

    satisfy the requirement that the expression h(k), where h is an object of type hash<Key> and k is an object of type Key, shall not throw an exception unless hash<Key> is a user-defined specialization that depends on at least one user-defined type.

template <> struct hash<bool>; template <> struct hash<char>; template <> struct hash<signed char>; template <> struct hash<unsigned char>; template <> struct hash<char16_t>; template <> struct hash<char32_t>; template <> struct hash<wchar_t>; template <> struct hash<short>; template <> struct hash<unsigned short>; template <> struct hash<int>; template <> struct hash<unsigned int>; template <> struct hash<long>; template <> struct hash<unsigned long>; template <> struct hash<long long>; template <> struct hash<unsigned long long>; template <> struct hash<float>; template <> struct hash<double>; template <> struct hash<long double>; template <class T> struct hash<T*>;

2

The template specializations shall meet the requirements of class template hash ([unord.hash]).