Namespaces
Variants
Views
Actions

Function objects

From cppreference.com
< cpp‎ | utility
 
 
Utilities library
Language support
Type support (basic types, RTTI)
Library feature-test macros (C++20)
Dynamic memory management
Program utilities
Coroutine support (C++20)
Variadic functions
Debugging support
(C++26)
Three-way comparison
(C++20)
(C++20)(C++20)(C++20)
(C++20)(C++20)(C++20)
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 invocation
(C++17)(C++23)
Identity function object
(C++20)
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)

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++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.

Contents

[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)

  • (obj.*f)(arg_1, arg_2, ..., arg_N) (invoke the member function on the object).
  • (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).
  • obj.*mptr (access the data member of the object).
  • 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))

  • 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).

(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

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) [edit]
wraps callable object of any type with specified function call signature
(class template) [edit]
refinement of std::move_only_function that wraps callable object of any copy constructible type
(class template) [edit]
non-owning reference to any callable object with specified function call signature
(class template) [edit]
the exception thrown when invoking an empty std::function
(class) [edit]
(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.

(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.

(C++20)(C++23)
bind a variable number of arguments, in order, to a function object
(function template) [edit]
(C++11)
binds one or more arguments to a function object
(function template) [edit]
indicates that an object is std::bind expression or can be used as one
(class template) [edit]
indicates that an object is a standard placeholder or can be used as one
(class template) [edit]
Defined in namespace std::placeholders
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.

(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.

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

[edit] Reference wrappers

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

CopyConstructible and CopyAssignable reference wrapper
(class template) [edit]
(C++11)(C++11)
creates a std::reference_wrapper with a type deduced from its argument
(function template) [edit]
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 defines 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
function object implementing x + y
(class template) [edit]
function object implementing x + y deducing parameter and return types
(class template specialization) [edit]
function object implementing x - y
(class template) [edit]
function object implementing x - y deducing parameter and return types
(class template specialization) [edit]
function object implementing x * y
(class template) [edit]
function object implementing x * y deducing parameter and return types
(class template specialization) [edit]
function object implementing x / y
(class template) [edit]
function object implementing x / y deducing parameter and return types
(class template specialization) [edit]
function object implementing x % y
(class template) [edit]
function object implementing x % y deducing parameter and return types
(class template specialization) [edit]
function object implementing -x
(class template) [edit]
function object implementing -x deducing parameter and return types
(class template specialization) [edit]
Comparisons
function object implementing x == y
(class template) [edit]
function object implementing x == y deducing parameter and return types
(class template specialization) [edit]
function object implementing x != y
(class template) [edit]
function object implementing x != y deducing parameter and return types
(class template specialization) [edit]
function object implementing x > y
(class template) [edit]
function object implementing x > y deducing parameter and return types
(class template specialization) [edit]
function object implementing x < y
(class template) [edit]
function object implementing x < y deducing parameter and return types
(class template specialization) [edit]
function object implementing x >= y
(class template) [edit]
function object implementing x >= y deducing parameter and return types
(class template specialization) [edit]
function object implementing x <= y
(class template) [edit]
function object implementing x <= y deducing parameter and return types
(class template specialization) [edit]
Logical operations
function object implementing x && y
(class template) [edit]
function object implementing x && y deducing parameter and return types
(class template specialization) [edit]
function object implementing x || y
(class template) [edit]
function object implementing x || y deducing parameter and return types
(class template specialization) [edit]
function object implementing !x
(class template) [edit]
function object implementing !x deducing parameter and return types
(class template specialization) [edit]
Bitwise operations
function object implementing x & y
(class template) [edit]
function object implementing x & y deducing parameter and return types
(class template specialization) [edit]
function object implementing x | y
(class template) [edit]
function object implementing x | y deducing parameter and return types
(class template specialization) [edit]
function object implementing x ^ y
(class template) [edit]
function object implementing x ^ y deducing parameter and return types
(class template specialization) [edit]
(C++14)
function object implementing ~x
(class template) [edit]
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.

constrained function object implementing x == y
(class) [edit]
constrained function object implementing x != y
(class) [edit]
constrained function object implementing x < y
(class) [edit]
constrained function object implementing x > y
(class) [edit]
constrained function object implementing x <= y
(class) [edit]
constrained function object implementing x >= y
(class) [edit]
constrained function object implementing x <=> y
(class) [edit]
(since C++20)


Old binders and adaptors

Several utilities that provided early functional support are deprecated and removed:

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

[edit] 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 2149 C++98 function objects taking one or two arguments were required to
provide nested types to denote the argument and result types
not required
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