22 General utilities library [utilities]

22.10 Function objects [function.objects]

22.10.17 Polymorphic function wrappers [func.wrap]

22.10.17.3 Class template function [func.wrap.func]

22.10.17.3.1 General [func.wrap.func.general]

namespace std { template<class R, class... ArgTypes> class function<R(ArgTypes...)> { public: using result_type = R; // [func.wrap.func.con], construct/copy/destroy function() noexcept; function(nullptr_t) noexcept; function(const function&); function(function&&) noexcept; template<class F> function(F&&); function& operator=(const function&); function& operator=(function&&); function& operator=(nullptr_t) noexcept; 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; // [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 type_info& target_type() const noexcept; template<class T> T* target() noexcept; template<class T> const T* target() const noexcept; }; template<class R, class... ArgTypes> function(R(*)(ArgTypes...)) -> function<R(ArgTypes...)>; template<class F> function(F) -> function<see below>; }

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]).

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

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

[Note 1:

The types deduced by the deduction guides for function might change in future revisions of C++.

— end note]

22.10.17.3.2 Constructors and destructor [func.wrap.func.con]

🔗

function() noexcept;

Postconditions: !*this.

🔗

function(nullptr_t) noexcept;

Postconditions: !*this.

🔗

function(const function& f);

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

Throws: Nothing if f's target is a specialization of reference_wrapper or a function pointer.

Otherwise, may throw bad_alloc or any exception thrown by the copy constructor of the stored callable object.

Recommended practice: Implementations should 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.

🔗

function(function&& f) noexcept;

Postconditions: If !f, *this has no target; otherwise, the target of *this is equivalent to the target of f before the construction, and f is in a valid state with an unspecified value.

🔗

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

Let FD be decay_t<F>.

Constraints:

(9.1)
is_same_v<remove_cvref_t<F>, function> is false, and
(9.2)
FD is Lvalue-Callable ([func.wrap.func]) for argument types ArgTypes... and return type R.

Mandates:

(10.1)
is_copy_constructible_v<FD> is true, and
(10.2)
is_constructible_v<FD, F> is true.

Preconditions: FD meets the Cpp17CopyConstructible requirements.

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

(12.1)
f is a null function pointer value.
(12.2)
f is a null member pointer value.
(12.3)
remove_cvref_t<F> is a specialization of the function class template, and !f is true.

Otherwise, *this has a target object of type FD direct-non-list-initialized with std::forward<F>(f).

Throws: Nothing if FD is a specialization of reference_wrapper or a function pointer type.

Otherwise, may throw bad_alloc or any exception thrown by the initialization of the target object.

Recommended practice: Implementations should avoid the use of dynamically allocated memory for small callable objects, for example, where f refers to an object holding only a pointer or reference to an object and a member function pointer.

🔗

template<class F> function(F) -> function<see below>;

Constraints: &F::operator() is well-formed when treated as an unevaluated operand and either

(16.1)
F::operator() is a non-static member function and decltype(&F::operator()) is either of the form R(G::*)(A...) cv & $_{o p t}$ noexcept $_{o p t}$ or of the form R(*)(G, A...) noexcept $_{o p t}$ for a type G, or
(16.2)
F::operator() is a static member function and decltype(&F::operator()) is of the form R(*)(A...) noexcept $_{o p t}$ .

Remarks: The deduced type is function<R(A...)>.

[Example 1: void f() { int i{5}; function g = [&](double) { return i; }; // deduces function<int(double)> } — end example]

🔗

function& operator=(const function& f);

Effects: As if by 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) noexcept;

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

Postconditions: !(*this).

Returns: *this.

🔗

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

Constraints: decay_t<F> is Lvalue-Callable ([func.wrap.func]) for argument types ArgTypes... and return type R.

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

Returns: *this.

🔗

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

Effects: As if by: function(f).swap(*this);

Returns: *this.

🔗

~function();

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

22.10.17.3.3 Modifiers [func.wrap.func.mod]

🔗

void swap(function& other) noexcept;

Effects: Interchanges the target objects of *this and other.

22.10.17.3.4 Capacity [func.wrap.func.cap]

🔗

explicit operator bool() const noexcept;

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

22.10.17.3.5 Invocation [func.wrap.func.inv]

🔗

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

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

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

22.10.17.3.6 Target access [func.wrap.func.targ]

🔗

const type_info& target_type() const noexcept;

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;

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

22.10.17.3.7 Null pointer comparison operator functions [func.wrap.func.nullptr]

🔗

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

Returns: !f.

22.10.17.3.8 Specialized algorithms [func.wrap.func.alg]

🔗

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

Effects: As if by: f1.swap(f2);