NAME¶

std::function::function - std::function::function

Synopsis¶

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

function( std::allocator_arg_t, const Alloc& (7) (since C++11)
alloc, (removed in C++17)

std::nullptr_t ) noexcept;
template< class Alloc > (4)

function( std::allocator_arg_t, const Alloc& (8) (since C++11)
alloc, (removed in C++17)

const function& other );
template< class Alloc >

function( std::allocator_arg_t, const Alloc& (9) (since C++11)
alloc, (removed in C++17)

function&& other );
template< class F, class Alloc > (since C++11)
function( std::allocator_arg_t, const Alloc& (10) (removed in C++17)
alloc, F f );

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

1-2) Creates an empty function.
3-4) Copies (3) or moves (4) the target of other to the target of *this. If other is
empty, *this will be empty after the call too. For (4), other is in a valid but
unspecified state after the call.
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 after
the call. This constructor does not participate in overload resolution unless the
target type is not same as function, and its lvalue is Callable for argument types
Args... and return type R. The program is ill-formed if the target type is not
copy-constructible or initialization of the target is ill-formed.
6-10) Same as (1-5) except that alloc is used to allocate memory for any internal
data structures that the 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¶

-
std::decay<F>::type must meet the requirements of Callable and CopyConstructible.
-
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 (until C++20)
exception thrown by the constructor used to copy or move the stored
callable object.

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¶

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.

Example¶

This section is incomplete
Reason: no example

Defect reports

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

DR Applied to Behavior as published Correct behavior
LWG 2132 C++11 constructor taking a Callable object might be constrained
ambiguous
LWG 2774 C++11 constructor taking a Callable performed an eliminated
additional move

See also¶

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