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.
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> struct plus;
template <class T> struct minus;
template <class T> struct multiplies;
template <class T> struct divides;
template <class T> struct modulus;
template <class T> struct negate;
// [comparisons], comparisons:
template <class T> struct equal_to;
template <class T> struct not_equal_to;
template <class T> struct greater;
template <class T> struct less;
template <class T> struct greater_equal;
template <class T> struct less_equal;
// [logical.operations], logical operations:
template <class T> struct logical_and;
template <class T> struct logical_or;
template <class T> struct logical_not;
// [bitwise.operations], bitwise operations:
template <class T> struct bit_and;
template <class T> struct bit_or;
template <class T> struct bit_xor;
// [negators], negators:
template <class Predicate> class unary_negate;
template <class Predicate>
unary_negate<Predicate> not1(const Predicate&);
template <class Predicate> class binary_negate;
template <class Predicate>
binary_negate<Predicate> not2(const Predicate&);
// [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::*);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::*)(Args...));
template<class R, class T, class... Args>
unspecified mem_fn(R (T::*)(Args...) const);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::*)(Args...) volatile);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::*)(Args...) const volatile);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::*)(Args...) &);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::*)(Args...) const &);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::*)(Args...) volatile &);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::*)(Args...) const volatile &);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::*)(Args...) &&);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::*)(Args...) const &&);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::*)(Args...) volatile &&);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::*)(Args...) const volatile &&);
// [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 base 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*>;
}
[ 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 ]
[ Example: To negate every element of a:
transform(a.begin(), a.end(), a.begin(), negate<double>());
— end example ]
To enable adaptors and other components to manipulate function objects that take one or two arguments it is required that the function objects 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.
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.
The following definitions apply to this Clause:
A call signature is the name of a return type followed by a parenthesized comma-separated list of zero or more argument types.
A callable type is a function object type ([function.objects]) or a pointer to member.
A callable object is an object of a callable type.
A call wrapper type is a type that holds a callable object and supports a call operation that forwards to that object.
A call wrapper is an object of a call wrapper type.
A target object is the callable object held by a call wrapper.
Define INVOKE(f, t1, t2, ..., tN) as follows:
(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;
((*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;
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;
(*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;
f(t1, t2, ..., tN) in all other cases.
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]):
if T is a pointer to function type, result_type shall be a synonym for the return type of T;
if T is a pointer to member function, result_type shall be a synonym for the return type of T;
if T is a class type with a member type result_type, then result_type shall be a synonym for T::result_type;
otherwise result_type shall not be defined.
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 ]
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<T>& x) noexcept;
// assignment
reference_wrapper& operator=(const reference_wrapper<T>& x) noexcept;
// access
operator T& () const noexcept;
T& get() const noexcept;
// invocation
template <class... ArgTypes>
typename result_of<T&(ArgTypes&&...)>::type
operator() (ArgTypes&&...) const;
};
}
reference_wrapper<T> is a CopyConstructible and CopyAssignable wrapper around a reference to an object or function of type T.
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.
The template instantiation 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:
a function type or a pointer to function type taking one argument of type T1
a pointer to member function R T0::f cv (where cv represents the member function's cv-qualifiers); the type T1 is cv T0*
a class type with a member type argument_type; the type T1 is T::argument_type.
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:
a function type or a pointer to function type taking two arguments of types T1 and T2
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*
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.
reference_wrapper(T& t) noexcept;
Effects: Constructs a reference_wrapper object that stores a reference to t.
reference_wrapper(const reference_wrapper<T>& x) noexcept;
Effects: Constructs a reference_wrapper object that stores a reference to x.get().
reference_wrapper& operator=(const reference_wrapper<T>& x) noexcept;
Postconditions: *this stores a reference to x.get().
operator T& () const noexcept;
Returns: The stored reference.
Returns: The stored reference.
template <class... ArgTypes>
typename result_of<T&(ArgTypes&&... )>::type
operator()(ArgTypes&&... args) const;
Returns: INVOKE(get(), std::forward<ArgTypes>(args)...). ([func.require])
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.
template <class T> reference_wrapper<T> ref(T& t) noexcept;
Returns: reference_wrapper<T>(t)
template <class T> reference_wrapper<T> ref(reference_wrapper<T>t) noexcept;
Returns: ref(t.get())
template <class T> reference_wrapper<const T> cref(const T& t) noexcept;
Returns: reference_wrapper <const T>(t)
template <class T> reference_wrapper<const T> cref(reference_wrapper<T> t) noexcept;
Returns: cref(t.get());
The library provides basic function object classes for all of the arithmetic operators in the language ([expr.mul], [expr.add]).
template <class T> struct plus {
T operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef T result_type;
};
operator() returns x + y.
template <class T> struct minus {
T operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef T result_type;
};
operator() returns x - y.
template <class T> struct multiplies {
T operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef T result_type;
};
operator() returns x * y.
template <class T> struct divides {
T operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef T result_type;
};
operator() returns x / y.
template <class T> struct modulus {
T operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef T result_type;
};
operator() returns x % y.
template <class T> struct negate {
T operator()(const T& x) const;
typedef T argument_type;
typedef T result_type;
};
operator() returns -x.
The library provides basic function object classes for all of the comparison operators in the language ([expr.rel], [expr.eq]).
template <class T> struct equal_to {
bool operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef bool result_type;
};
operator() returns x == y.
template <class T> struct not_equal_to {
bool operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef bool result_type;
};
operator() returns x != y.
template <class T> struct greater {
bool operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef bool result_type;
};
operator() returns x > y.
template <class T> struct less {
bool operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef bool result_type;
};
operator() returns x < y.
template <class T> struct greater_equal {
bool operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef bool result_type;
};
operator() returns x >= y.
template <class T> struct less_equal {
bool operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef bool result_type;
};
operator() returns x <= y.
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.
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> struct logical_and {
bool operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef bool result_type;
};
operator() returns x && y.
template <class T> struct logical_or {
bool operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef bool result_type;
};
operator() returns x || y.
template <class T> struct logical_not {
bool operator()(const T& x) const;
typedef T argument_type;
typedef bool result_type;
};
operator() returns !x.
The library provides basic function object classes for all of the bitwise operators in the language ([expr.bit.and], [expr.or], [expr.xor]).
template <class T> struct bit_and {
T operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef T result_type;
};
operator() returns x & y.
template <class T> struct bit_or {
T operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef T result_type;
};
operator() returns x | y.
template <class T> struct bit_xor {
T operator()(const T& x, const T& y) const;
typedef T first_argument_type;
typedef T second_argument_type;
typedef T result_type;
};
operator() returns x ^ y.
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:
explicit unary_negate(const Predicate& pred);
bool operator()(const typename Predicate::argument_type& x) const;
typedef typename Predicate::argument_type argument_type;
typedef bool result_type;
};
operator() returns !pred(x).
template <class Predicate>
unary_negate<Predicate> not1(const Predicate& pred);
Returns: unary_negate<Predicate>(pred).
template <class Predicate>
class binary_negate {
public:
explicit binary_negate(const Predicate& pred);
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;
};
operator() returns !pred(x,y).
template <class Predicate>
binary_negate<Predicate> not2(const Predicate& pred);
Returns: binary_negate<Predicate>(pred).
The function template bind returns an object that binds a callable object passed as an argument to additional arguments.
This subclause describes a uniform mechanism for binding arguments of callable objects.
namespace std {
template<class T> struct is_bind_expression
: integral_constant<bool, see below> { };
}
is_bind_expression can be used to detect function objects generated by bind. bind uses is_bind_expression to detect subexpressions. Users may specialize this template to indicate that a type should be treated as a subexpression in a bind call.
If T is a type returned from bind, is_bind_expression<T> shall be publicly derived from integral_constant<bool, true>, otherwise from integral_constant<bool, false>.
is_placeholder can be used to detect the standard placeholders _1, _2, and so on. bind uses is_placeholder to detect placeholders. Users may specialize this template to indicate a placeholder type.
If T is the type of std::placeholders::_J, is_placeholder<T> shall be publicly derived from integral_constant<int, J>, otherwise from integral_constant<int, 0>.
In the text that follows, the following names have the following meanings:
FD is the type decay<F>::type,
fd is an lvalue of type FD constructed from std::forward<F>(f),
Ti is the ith type in the template parameter back BoundArgs,
TiD is the type decay<Ti>::type,
ti is the ith argument in the function parameter pack bound_args,
tid is an lvalue of type TiD 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<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).
Returns: A forwarding call wrapper g with a weak result type ([func.require]). The effect of g(u1, u2, ..., uM) shall be INVOKE(fd, v1, v2, ..., vN, result_of<FD cv (V1, V2, ..., VN)>::type), 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.
Throws: Nothing unless the construction of fd or of one of the values tid throws an exception.
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);
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).
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, v1, v2, ..., 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.
Throws: Nothing unless the construction of fd or of one of the values tid throws an exception.
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 ]
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:
if TiD is reference_wrapper<T>, the argument is tid.get() and its type Vi is T&;
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<TiD cv (Uj...)>::type;
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&&;
otherwise, the value is tid and its type Vi is TiD cv &.
namespace std {
namespace placeholders {
// M is the implementation-defined number of placeholders
extern unspecified _1;
extern unspecified _2;
.
.
.
extern unspecified _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.
template<class R, class T>
unspecified mem_fn(R T::* pm);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::* pm)(Args...));
template<class R, class T, class... Args>
unspecified mem_fn(R (T::* pm)(Args...) const);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::* pm)(Args...) volatile);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::* pm)(Args...) const volatile);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::* pm)(Args...) &);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::* pm)(Args...) const &);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::* pm)(Args...) volatile &);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::* pm)(Args...) const volatile &);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::* pm)(Args...) &&);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::* pm)(Args...) const &&);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::* pm)(Args...) volatile &&);
template<class R, class T, class... Args>
unspecified mem_fn(R (T::* pm)(Args...) const volatile &&);
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.
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.
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.
Throws: Nothing.
This subclause describes a polymorphic wrapper class that encapsulates arbitrary callable objects.
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
Effects: constructs a bad_function_call object.
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; // iff sizeof...(ArgTypes) == 1 and
// the type in ArgTypes is T1
typedef T1 first_argument_type; // iff sizeof...(ArgTypes) == 2 and
// ArgTypes contains T1 and T2
typedef T2 second_argument_type; // iff 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 <typename T> T* target() noexcept;
template <typename 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 { };
}
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.
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]).
The function class template is a call wrapper ([func.def]) whose call signature ([func.def]) is R(ArgTypes...).
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;
Postconditions: !*this.
function(nullptr_t) noexcept;
template <class A> function(allocator_arg_t, const A& a, nullptr_t) noexcept;
Postconditions: !*this.
function(const function& f);
template <class A> function(allocator_arg_t, const A& a, const function& f);
Postconditions: !*this if !f; otherwise, *this targets a copy of f.target().
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);
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);
Requires: F shall be CopyConstructible. f shall be Callable ([func.wrap.func]) for argument types ArgTypes and return type R. The copy constructor and destructor of A shall not throw exceptions.
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 ]
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);
Effects: function(f).swap(*this);
Returns: *this
function& operator=(function&& f);
Effects: Replaces the target of *this with the target of f.
Returns: *this
function& operator=(nullptr_t);
Effects: If *this != NULL, destroys the target of this.
Postconditions: !(*this).
Returns: *this
template<class F> function& operator=(F&& f);
Effects: function(std::forward<F>(f)).swap(*this);
Returns: *this
template<class F> function& operator=(reference_wrapper<F> f) noexcept;
Effects: function(f).swap(*this);
Returns: *this
Effects: If *this != NULL, destroys the target of this.
void swap(function& other) noexcept;
Effects: interchanges the targets of *this and other.
template<class F, class A>
void assign(F&& f, const A& a);
Effects: function(allocator_arg, a, std::forward<F>(f)).swap(*this)
explicit operator bool() const noexcept;
Returns: true if *this has a target, otherwise false.
R operator()(ArgTypes... args) const
Effects: INVOKE(f, std::forward<ArgTypes>(args)..., R) ([func.require]), where f is the target object ([func.def]) of *this.
Returns: Nothing if R is void, otherwise the return value of INVOKE(f, std::forward<ArgTypes>(args)..., R).
Throws: bad_function_call if !*this; otherwise, any exception thrown by the wrapped callable object.
const std::type_info& target_type() const noexcept;
Returns: If *this has a target of type T, typeid(T); otherwise, typeid(void).
template<typename T> T* target() noexcept;
template<typename T> const T* target() const noexcept;
Requires: T shall be a type that is Callable ([func.wrap.func]) for parameter types ArgTypes and return type R.
Returns: If target_type() == typeid(T) a pointer to the stored function target; otherwise a null pointer.
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;
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;
Returns: (bool) f.
template<class R, class... ArgTypes>
void swap(function<R(ArgTypes...)>& f1, function<R(ArgTypes...)>& f2);
Effects: f1.swap(f2);
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>, the instantiation hash<Key> shall:
satisfy the Hash requirements ([hash.requirements]), with Key as the function call argument type, the DefaultConstructible requirements (Table [defaultconstructible]), the CopyAssignable requirements (Table [copyassignable]),
be swappable ([swappable.requirements]) for lvalues,
provide two nested types result_type and argument_type which shall be synonyms for size_t and Key, respectively,
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;
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*>;
Requires: the template specializations shall meet the requirements of class template hash ([unord.hash]).