Function objects

From cppreference.com
< cpp‎ | utility
 
 
Utilities library
General utilities
Date and time
Function objects
Formatting library (C++20)
(C++11)
Relational operators (deprecated in C++20)
Integer comparison functions
(C++20)(C++20)(C++20)   
(C++20)
Swap and type operations
(C++14)
(C++11)
(C++11)
(C++11)
(C++17)
Common vocabulary types
(C++11)
(C++17)
(C++17)
(C++17)
(C++11)
(C++17)
(C++23)
Elementary string conversions
(C++17)
(C++17)
 
Function objects
Function wrappers
(C++11)
(C++11)
Partial function application
(C++20)(C++23)
(C++11)
Function invocation
(C++17)(C++23)
Identity function object
(C++20)
Reference wrappers
(C++11)(C++11)
Transparent operator wrappers
(C++14)
(C++14)
(C++14)
(C++14)  
(C++14)
(C++14)
(C++14)
(C++14)
(C++14)
(C++14)
(C++14)
(C++14)
(C++14)

Negators
(C++17)
Searchers
Constrained comparators
Old binders and adaptors
(until C++17*)
(until C++17*)
(until C++17*)
(until C++17*)
(until C++17*)(until C++17*)(until C++17*)(until C++17*)
(until C++20*)
(until C++20*)
(until C++17*)(until C++17*)
(until C++17*)(until C++17*)

(until C++17*)
(until C++17*)(until C++17*)(until C++17*)(until C++17*)
(until C++20*)
(until C++20*)
 

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.

Function invocation

The exposition-only operation INVOKE(f, t1, t2, ..., tN) is defined as follows, given the type T1 as std::remove_cv<std::remove_reference<decltype(t1)>::type>::type:

  • (t1.*f)(t2, ..., tN) if std::is_same<T, T1>::value || std::is_base_of<T, T1>::value is true.
  • (t1.get().*f)(t2, ..., tN) if T1 is a specialization of std::reference_wrapper.
  • ((*t1).*f)(t2, ..., tN) if T1 does not satisfy the previous two conditions.
  • Otherwise, INVOKE(f, t1, t2, ..., tN) is equivalent to f(t1, t2, ..., tN) (that is, f is a FunctionObject).

The exposition-only operation INVOKE<R>(f, t1, t2, ..., tN) is defined as static_cast<void>(INVOKE(f, t1, t2, ..., tN)) if R is (possibly cv-qualified) void, otherwise INVOKE(f, t1, t2, ..., tN) implicitly converted to R.

If std::reference_converts_from_temporary_v
<R, decltype(INVOKE(f, t1, t2, ..., tN))>
is true, INVOKE<R>(f, t1, t2, ..., tN) 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).

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

Function wrappers

std::function provides support for storing arbitrary function objects.

(C++11)
wraps callable object of any copy constructible type with specified function call signature
(class template)
wraps callable object of any type with specified function call signature
(class template)
refinement of std::move_only_function that wraps callable object of any copy constructible type
(class template)
non-owning reference to any callable object with specified function call signature
(class template)
the exception thrown when invoking an empty std::function
(class)
(C++11)
creates a function object out of a pointer to a member
(function template)

Identity

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

(C++20)
function object that returns its argument unchanged
(class)

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.

(C++20)(C++23)
bind a variable number of arguments, in order, to a function object
(function template)
(C++11)
binds one or more arguments to a function object
(function template)
indicates that an object is std::bind expression or can be used as one
(class template)
indicates that an object is a standard placeholder or can be used as one
(class template)
Defined in namespace std::placeholders
placeholders for the unbound arguments in a std::bind expression
(constant)

Negators

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

(C++17)
creates a function object that returns the complement of the result of the function object it holds
(function template)

Searchers

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

standard C++ library search algorithm implementation
(class template)
Boyer-Moore search algorithm implementation
(class template)
Boyer-Moore-Horspool search algorithm implementation
(class template)

Reference wrappers

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

CopyConstructible and CopyAssignable reference wrapper
(class template)
(C++11)(C++11)
creates a std::reference_wrapper with a type deduced from its argument
(function template)
get the reference type wrapped in std::reference_wrapper
(class template)

Operator function objects

C++ defines several function objects that represent common arithmetic and logical operations:

Arithmetic operations
function object implementing x + y
(class template)
function object implementing x - y
(class template)
function object implementing x * y
(class template)
function object implementing x / y
(class template)
function object implementing x % y
(class template)
function object implementing -x
(class template)
Comparisons
function object implementing x == y
(class template)
function object implementing x != y
(class template)
function object implementing x > y
(class template)
function object implementing x < y
(class template)
function object implementing x >= y
(class template)
function object implementing x <= y
(class template)
Logical operations
function object implementing x && y
(class template)
function object implementing x || y
(class template)
function object implementing !x
(class template)
Bitwise operations
function object implementing x & y
(class template)
function object implementing x | y
(class template)
function object implementing x ^ y
(class template)
(C++14)
function object implementing ~x
(class template)

Constrained comparison function objects

C++20 defines a set of constrained comparison function objects. The equality operators (ranges::equal_to and ranges::not_equal_to) require the types of the arguments to model equality_comparable_with. The relational operators (ranges::less, ranges::greater, ranges::less_equal, and ranges::greater_equal) require the types of the arguments to model totally_ordered_with. The three-way comparison operator (compare_three_way) requires the type to model three_way_comparable_with.

function object implementing x == y
(class)
function object implementing x != y
(class)
function object implementing x < y
(class)
function object implementing x > y
(class)
function object implementing x <= y
(class)
function object implementing x >= y
(class)
function object implementing x <=> y
(class)

Old binders and adaptors

Several utilities that provided early functional support are deprecated in C++11 and removed in C++17 (old negators are deprecated in C++17 and removed in C++20):

Base
(deprecated in C++11)(removed in C++17)
adaptor-compatible unary function base class
(class template)
(deprecated in C++11)(removed in C++17)
adaptor-compatible binary function base class
(class template)
Binders
(deprecated in C++11)(removed in C++17)
function object holding a binary function and one of its arguments
(class template)
(deprecated in C++11)(removed in C++17)
binds one argument to a binary function
(function template)
Function adaptors
(deprecated in C++11)(removed in C++17)
adaptor-compatible wrapper for a pointer to unary function
(class template)
(deprecated in C++11)(removed in C++17)
adaptor-compatible wrapper for a pointer to binary function
(class template)
(deprecated in C++11)(removed in C++17)
creates an adaptor-compatible function object wrapper from a pointer to function
(function template)
(deprecated in C++11)(removed in C++17)
wrapper for a pointer to nullary or unary member function, callable with a pointer to object
(class template)
(deprecated in C++11)(removed in C++17)
creates a wrapper from a pointer to member function, callable with a pointer to object
(function template)
wrapper for a pointer to nullary or unary member function, callable with a reference to object
(class template)
(deprecated in C++11)(removed in C++17)
creates a wrapper from a pointer to member function, callable with a reference to object
(function template)
(deprecated in C++17)(removed in C++20)
wrapper function object returning the complement of the unary predicate it holds
(class template)
(deprecated in C++17)(removed in C++20)
wrapper function object returning the complement of the binary predicate it holds
(class template)
(deprecated in C++17)(removed in C++20)
constructs custom std::unary_negate object
(function template)
(deprecated in C++17)(removed in C++20)
constructs custom std::binary_negate object
(function template)

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 185 C++98 using function objects improved the program efficiency removed the claim
LWG 660 C++98 function objects for bitwise operations are missing added
LWG 2219 C++11 INVOKE did not handle std::reference_wrapper correctly handles correctly
LWG 2420 C++11 INVOKE<R> did not discard the return value if R is void discards the return value in this case
LWG 2926
(P0604R0)
C++11 the syntax of the INVOKE operation with a return
type R was INVOKE(f, t1, t2, ..., tN, R)
changed to
INVOKE<R>(f, t1, t2, ..., tN)
LWG 3655 C++11 INVOKE did not handle unions correctly
due to the resolution of LWG issue 2219
handles correctly