std::function::function(3)

💖 NAME 💖

bestie, this is std::function::function(3) — the constructor page for std::function, straight out of the C++ Standard Libary. It's giving "build me a function object from a bunch of different sources," and honestly? iconic.

---

📖 Synopsis

Here's the whole overload lineup, no cap:

function() noexcept;
function( std::nullptr_t ) noexcept;
function( const function& other );
function( function&& other );
function( function&& other ) noexcept;
template< class F >
function( F&& f );
template< class Alloc >
function( std::allocator_arg_t, const Alloc& alloc ) noexcept;
template< class Alloc >
function( std::allocator_arg_t, const Alloc& alloc, std::nullptr_t ) noexcept;
template< class Alloc >
function( std::allocator_arg_t, const Alloc& alloc, const function& other );
template< class Alloc >
function( std::allocator_arg_t, const Alloc& alloc, function&& other );
template< class F, class Alloc >
function( std::allocator_arg_t, const Alloc& alloc, F f );

• (1) function() noexcept; — since C++11
• (2) function( std::nullptr_t ) noexcept; — since C++11
• (3) function( const function& other ); — since C++11
• (4) function( function&& other ); — since C++11, until C++20; and function( function&& other ) noexcept; — since C++20
• (5) template< class F > function( F&& f ); — since C++11
• (6) template< class Alloc > function( std::allocator_arg_t, const Alloc& alloc ) noexcept; — since C++11, removed in C++17
• (7) template< class Alloc > function( std::allocator_arg_t, const Alloc& alloc, std::nullptr_t ) noexcept; — since C++11, removed in C++17
• (8) template< class Alloc > function( std::allocator_arg_t, const Alloc& alloc, const function& other ); — since C++11, removed in C++17
• (9) template< class Alloc > function( std::allocator_arg_t, const Alloc& alloc, function&& other ); — since C++11, removed in C++17
• (10) template< class F, class Alloc > function( std::allocator_arg_t, const Alloc& alloc, F f ); — since C++11, removed in C++17

---

💅 DESCRIPTION

Constructs a std::function from a variety of sources. Periodt.

• Overloads (1), (2): Creates an empty std::function. Empty empty. No target, no drama.
• Overload (3): Copies the target of other to the target of *this. If other is empty, *this will be empty right after the call too.
• Overload (4): Moves the target of other to the target of *this. If other is empty, *this will be empty right after the call too. And heads up: other is in a valid but unspecified state right after the call.
• Overload (5): Initializes the target with std::forward<F>(f). The target is of type std::decay<F>::type. If f is a null pointer to function, a null pointer to member, or an empty value of some std::function specialization, *this will be empty right after the call. This overload participates in overload resolution only if all following conditions are satisfied:
  • std::is_same_v<std::remove_cvref_t<F>, std::function<R(Args...)> (since C++23) is false.
  • An lvalue of type std::decay<F>::type is callable for argument types Args... and return type R.
• If std::is_copy_constructible_v<std::decay_t<F>> or std::is_constructible_v<std::decay_t<F>, F> is false, the program is (since C++23) ill-formed.
• If F is not CopyConstructible, the behavior is undefined.
• Overloads (6)–(10): Same as (1)–(5) except that alloc is used to allocate memory for any internal data structures that the std::function might use.

When the target is a function pointer or a std::reference_wrapper, small object optimization is guaranteed, that is, these targets are always directly stored inside the std::function object, no dynamic allocation takes place. Other large objects may be constructed in dynamic allocated storage and accessed by the std::function object through a pointer.

---

🎀 Parameters

• other — the function object used to initialize *this
• f — a callable object used to initialize *this
• alloc — an Allocator used for internal memory allocation

---

🧚 Type requirements

• Alloc must meet the requirements of Allocator.

---

😭 Exceptions

• 3, 8, 9) Does not throw if other's target is a function pointer or a std::reference_wrapper, otherwise may throw std::bad_alloc or any exception thrown by the constructor used to copy or move the stored callable object.
• 4) Does not throw if other's target is a function pointer or a std::reference_wrapper, otherwise may throw std::bad_alloc or any exception thrown by the constructor used to copy or move the stored callable object. (until C++20)
• 5, 10) Does not throw if f is a function pointer or a std::reference_wrapper, otherwise may throw std::bad_alloc or any exception thrown by the copy constructor of the stored callable object.

---

💀 Notes

ngl, std::function's allocator support was poorly specified and inconsistently implemented. Some implementations do not provide overloads (6-10) at all, some provide the overloads but ignore the supplied allocator argument, and some provide the overloads and use the supplied allocator for construction but not when the std::function is reassigned. As a result, allocator support was removed in C++17. It's giving messy, and not in the cute way.

---

🌸 Example

This section is incomplete.

Reason: no example.

---

🔥 Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• LWG 2132 — Applied to: C++11 — Behavior as published: overloads (5,10) might be ambiguous — Correct behavior: constrained
• LWG 2774 — Applied to: C++11 — Behavior as published: (5,10) performed an additional move — Correct behavior: eliminated

---

👑 See also

• constructor — constructs a new std::move_only_function object (C++23) (public member function of std::move_only_function)

---

🍓 Category

• Todo no example

---

Source/version/date vibes: http://cppreference.com, 2024.06.10, and this was std::function::function(3) — bye bestie, go construct something cute 💖✨