Function objects

A function object is any object for which the function call operator is defined. C++ provides many built-in function objects as well as support for creation and manipulation of new function objects.

[edit] Function invocation

The exposition-only operation INVOKE(f, arg_0, arg_1, arg_2, ..., arg_N) is defined as follows:

Let type Obj be the unqualified type of arg_0 (i.e., std::remove_cv <std::remove_reference <decltype(arg_0)>::type>::type)

If f is a pointer to member function of class C, then INVOKE(f, obj, arg_1, arg_2, ..., arg_N) is equivalent to:

If std::is_same <C, Obj>::value || std::is_base_of <C, Obj>::value is true

(obj.*f)(arg_1, arg_2, ..., arg_N) (invoke the member function on the object).

If Obj is a specialization of std::reference_wrapper

(obj.get().*f)(arg_1, arg_2, ..., arg_N) (invoke the member function on the specially referred object).

Otherwise

((*obj).*f)(arg_1, arg_2, ..., arg_N) (invoke the member function on the dereferenced object).

Otherwise, if N == 0 and f is a pointer to data member of class C, then INVOKE(mptr, obj) is equivalent to:

If std::is_same <C, Obj>::value || std::is_base_of <C, Obj>::value is true

obj.*mptr (access the data member of the object).

If Obj is a specialization of std::reference_wrapper

obj.get().*mptr (access the data member of the specially referred object).

Otherwise

(*obj).*mptr (access the data member of the dereferenced object).

Otherwise

INVOKE(f, arg_0, arg_1, arg_2, ..., arg_N) is equivalent to f(arg_0, arg_1, arg_2, ..., arg_N) (invoke the callable).

The exposition-only operation INVOKE<R>(f, arg_0, arg_1, arg_2, ..., arg_N) is defined as follows:

If R is (possibly cv-qualified) void

static_cast<void>(INVOKE(f, arg_0, arg_1, arg_2, ..., arg_N)).

Otherwise

INVOKE(f, arg_0, arg_1, arg_2, ..., arg_N) implicitly converted to R.

Let type Actual be decltype(INVOKE(f, arg_0, arg_1, arg_2, ..., arg_N))

If std::reference_converts_from_temporary_v <R, Actual> is true

INVOKE<R>(f, arg_0, arg_1, arg_2, ..., arg_N) is ill-formed.

(since C++23)

(since C++11)

std::invoke and std::invoke_r(since C++23) can invoke any Callable object with given arguments according to the rules of INVOKE and INVOKE<R>(since C++23).

invokeinvoke_r

(C++17)(C++23)

invokes any Callable object with given arguments and possibility to specify return type(since C++23)
(function template) [edit]

[edit] Function wrappers

These polymorphic wrapper classes provide support for storing arbitrary function objects.

function

(C++11)

copyable wrapper of any copy constructible callable object
(class template) [edit]

move_only_function

(C++23)

move-only wrapper of any callable object that supports qualifiers in a given call signature
(class template) [edit]

copyable_function

(C++26)

copyable wrapper of any copy constructible callable object that supports qualifiers in a given call signature
(class template) [edit]

function_ref

(C++26)

non-owning wrapper of any callable object
(class template) [edit]

bad_function_call

(C++11)

the exception thrown when invoking an empty std::function
(class) [edit]

mem_fn

(C++11)

creates a function object out of a pointer to a member
(function template) [edit]

[edit] Identity

std::identity is the identity function object: it returns its argument unchanged.

identity

(C++20)

function object that returns its argument unchanged
(class) [edit]

[edit] Partial function application

std::bind_front and std::bind provide support for partial function application, i.e. binding arguments to functions to produce new functions.

bind_frontbind_back

(C++20)(C++23)

bind a variable number of arguments, in order, to a function object
(function template) [edit]

bind

(C++11)

binds one or more arguments to a function object
(function template) [edit]

is_bind_expression

(C++11)

indicates that an object is std::bind expression or can be used as one
(class template) [edit]

is_placeholder

(C++11)

indicates that an object is a standard placeholder or can be used as one
(class template) [edit]

Defined in namespace std::placeholders

_1, _2, _3, _4, ...

(C++11)

placeholders for the unbound arguments in a std::bind expression
(constant) [edit]

[edit] Negators

std::not_fn creates a function object that negates the result of the callable object passed to it.

not_fn

(C++17)

creates a function object that returns the complement of the result of the function object it holds
(function template) [edit]

[edit] Searchers

Searchers implementing several string searching algorithms are provided and can be used either directly or with std::search .

default_searcher

(C++17)

standard C++ library search algorithm implementation
(class template) [edit]

boyer_moore_searcher

(C++17)

Boyer-Moore search algorithm implementation
(class template) [edit]

boyer_moore_horspool_searcher

(C++17)

Boyer-Moore-Horspool search algorithm implementation
(class template) [edit]

[edit] Reference wrappers

Reference wrappers allow reference arguments to be stored in copyable function objects:

reference_wrapper

(C++11)

CopyConstructible and CopyAssignable reference wrapper
(class template) [edit]

refcref

(C++11)(C++11)

creates a std::reference_wrapper with a type deduced from its argument
(function template) [edit]

unwrap_referenceunwrap_ref_decay

(C++20)(C++20)

get the reference type wrapped in std::reference_wrapper
(class template) [edit]

Transparent function objects

Associative containers and unordered associative containers (since C++20) provide heterogeneous lookup and erasure(since C++23) operations, but they are only enabled if the supplied function object type T is transparent : the qualified identifier T::is_transparent is valid and denotes a type.

All transparent function object types in the standard library define a nested type is_transparent. However, user-defined transparent function object types do not need to directly provide is_transparent as a nested type: it can be defined in a base class, as long as T::is_transparent satisfies the transparent requirement stated above.

(since C++14)

[edit] Operator function objects

C++ defines the following function objects that represent common arithmetic and logical operations.

The void specializations deduce their parameter types and return types from their arguments, they are all transparent.

(since C++14)

Arithmetic operations

plus

function object implementing x + y
(class template) [edit]

plus<void>

(C++14)

function object implementing x + y deducing parameter and return types
(class template specialization) [edit]

minus

function object implementing x - y
(class template) [edit]

minus<void>

(C++14)

function object implementing x - y deducing parameter and return types
(class template specialization) [edit]

multiplies

function object implementing x * y
(class template) [edit]

multiplies<void>

(C++14)

function object implementing x * y deducing parameter and return types
(class template specialization) [edit]

divides

function object implementing x / y
(class template) [edit]

divides<void>

(C++14)

function object implementing x / y deducing parameter and return types
(class template specialization) [edit]

modulus

function object implementing x % y
(class template) [edit]

modulus<void>

(C++14)

function object implementing x % y deducing parameter and return types
(class template specialization) [edit]

negate

function object implementing -x
(class template) [edit]

negate<void>

(C++14)

function object implementing -x deducing parameter and return types
(class template specialization) [edit]

Comparisons

equal_to

function object implementing x == y
(class template) [edit]

equal_to<void>

(C++14)

function object implementing x == y deducing parameter and return types
(class template specialization) [edit]

not_equal_to

function object implementing x != y
(class template) [edit]

not_equal_to<void>

(C++14)

function object implementing x != y deducing parameter and return types
(class template specialization) [edit]

greater

function object implementing x > y
(class template) [edit]

greater<void>

(C++14)

function object implementing x > y deducing parameter and return types
(class template specialization) [edit]

less

function object implementing x < y
(class template) [edit]

less<void>

(C++14)

function object implementing x < y deducing parameter and return types
(class template specialization) [edit]

greater_equal

function object implementing x >= y
(class template) [edit]

greater_equal<void>

(C++14)

function object implementing x >= y deducing parameter and return types
(class template specialization) [edit]

less_equal

function object implementing x <= y
(class template) [edit]

less_equal<void>

(C++14)

function object implementing x <= y deducing parameter and return types
(class template specialization) [edit]

Logical operations

logical_and

function object implementing x && y
(class template) [edit]

logical_and<void>

(C++14)

function object implementing x && y deducing parameter and return types
(class template specialization) [edit]

logical_or

function object implementing x || y
(class template) [edit]

logical_or<void>

(C++14)

function object implementing x || y deducing parameter and return types
(class template specialization) [edit]

logical_not

function object implementing !x
(class template) [edit]

logical_not<void>

(C++14)

function object implementing !x deducing parameter and return types
(class template specialization) [edit]

Bitwise operations

bit_and

function object implementing x & y
(class template) [edit]

bit_and<void>

(C++14)

function object implementing x & y deducing parameter and return types
(class template specialization) [edit]

bit_or

function object implementing x | y
(class template) [edit]

bit_or<void>

(C++14)

function object implementing x | y deducing parameter and return types
(class template specialization) [edit]

bit_xor

function object implementing x ^ y
(class template) [edit]

bit_xor<void>

(C++14)

function object implementing x ^ y deducing parameter and return types
(class template specialization) [edit]

bit_not

(C++14)

function object implementing ~x
(class template) [edit]

bit_not<void>

(C++14)

function object implementing ~x deducing parameter and return types
(class template specialization) [edit]

Constrained comparison function objects

The following comparison function objects are constrained.

The equality operators (ranges::equal_to and ranges::not_equal_to) require the types of the arguments to satisfy equality_comparable_with.
The relational operators (ranges::less, ranges::greater, ranges::less_equal, and ranges::greater_equal) require the types of the arguments to satisfy totally_ordered_with.
The three-way comparison operator (compare_three_way) requires the type to model three_way_comparable_with.

All these function objects are transparent.

ranges::equal_to

(C++20)

constrained function object implementing x == y
(class) [edit]

ranges::not_equal_to

(C++20)

constrained function object implementing x != y
(class) [edit]

ranges::less

(C++20)

constrained function object implementing x < y
(class) [edit]

ranges::greater

(C++20)

constrained function object implementing x > y
(class) [edit]

ranges::less_equal

(C++20)

constrained function object implementing x <= y
(class) [edit]

ranges::greater_equal

(C++20)

constrained function object implementing x >= y
(class) [edit]

compare_three_way

(C++20)

constrained function object implementing x <=> y
(class) [edit]

(since C++20)

Helper items

Following exposition-only items are used for several components in the standard library but they are not part of the interface of the standard library.

template< class Fn, class... Args >

concept /*callable*/ =
requires (Fn&& fn, Args&&... args) {
std::forward <Fn>(fn)(std::forward <Args>(args)...);

};

(1) (exposition only*)

template< class Fn, class... Args >

concept /*nothrow-callable*/ =
/*callable*/<Fn, Args...> &&
requires (Fn&& fn, Args&&... args) {
{ std::forward <Fn>(fn)(std::forward <Args>(args)...) } noexcept;

};

(2) (exposition only*)

template< class Fn, class... Args >
using /*call-result-t*/ = decltype(std::declval <Fn>()(std::declval <Args>()...));

(3) (exposition only*)

template< const auto& T >
using /*decayed-typeof*/ = decltype(auto(T));

(4) (exposition only*)

(since C++26)