C++ Reference ยท Memory and Utilities
C++ std::function class template
Reference for C++ std::function: store lambdas, function pointers and functors behind one type, bad_function_call, target(), cost, and when to avoid it.
std::function<R(Args...)>, declared in <functional>, is a general-purpose wrapper that can hold any copyable callable with a matching signature: a free function, a lambda (even one with captures), a functor, a member function pointer or a std::bind result. The concrete type is hidden behind the signature, which is called type erasure.
That makes it the standard way to store callbacks, event handlers and strategy objects in a member variable or container. The price is a possible heap allocation and an indirect call per invocation.
std::function<int(int, int)> op = [](int a, int b) { return a + b; }; int r = op(2, 3); // 5
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
template<class R, class... Args> class function<R(Args...)>; function() noexcept; function(nullptr_t) noexcept; template<class F> function(F f); R operator()(Args... args) const; explicit operator bool() const noexcept; template<class T> T* target() noexcept; const type_info& target_type() const noexcept;
| Member | Description |
|---|---|
operator() |
Calls the target with args and returns its result converted to R. |
operator bool |
true if a target is stored. |
target<T>() |
Pointer to the stored callable if its exact type is T, otherwise nullptr. |
target_type() |
typeid of the stored callable (typeid(void) if empty). |
swap, assign, = nullptr |
Replace or clear the target. |
Returns: the target's result. Errors: calling an empty std::function throws std::bad_function_call. The constructor may throw bad_alloc for large callables.
Usage notes
- Copyable only: the stored callable must be copy constructible, so a lambda capturing a
std::unique_ptrcannot be stored. C++23 offersstd::move_only_functionfor that. - Cost: callables larger than a small internal buffer (often 16 bytes in libstdc++) are heap-allocated. Calls go through an indirection that the optimizer usually cannot inline. For templates, take the callable as a template parameter (
template<class F>) or useautoparameters to avoid this. - Parameter passing: accept
std::functionbyconst&or by value when you store it; use a template parameter orstd::function_ref(C++26, not available here) when you only call it. - Signature conversions: the stored callable only has to be callable with the arguments and return something convertible to
R. Astd::function<void(int)>can wrap a callable that returns a value; the value is discarded. - Constness:
operator()isconst, but the target may modify its own state if it ismutable. Calling the samestd::functionfrom several threads is a data race for such targets. - Dangling captures: capturing a local by reference and calling the function after the local dies is undefined behavior.
- Recursion: a lambda cannot refer to itself, but you can store it in a
std::functioncaptured by reference. In C++23 use an explicitthisparameter instead; it is faster. - Wrapping a function pointer or
std::reference_wrappertarget does not allocate.