Functional (C++)

In the context of the programming language C++, <functional> refers to a header file that is part of the C++ Standard Library and provides a set of predefined class templates for function objects, including operations for arithmetic, comparisons, and logic. Instances of these class templates are C++ classes that define a function call operator, and the instances of these classes can be called as if they were functions. It is possible to perform very sophisticated operations without writing a new function object, simply by combining predefined function objects and function object adaptors.

The class template std::function provided by C++11 is a general-purpose polymorphic function wrapper. Instances of std::function<> can store, copy, and invoke any callable target—functions, lambda expressions (expressions defining anonymous functions), bind expressions (instances of function adapters that transform functions to other functions of smaller arity by providing values for some of the arguments), or other function objects.

The algorithms provided by the C++ Standard Library do not require function objects of more than two arguments. Function objects that return Boolean values are an important special case. A unary function whose return type is bool is called a predicate, and a binary function whose return type is bool is called a binary predicate.

Adaptable function objects

In general, a function object has restrictions on the type of its argument. The type restrictions need not be simple, though: operator() may be overloaded or may be a member template. Similarly, there need be no way for a program to determine what those restrictions are. An adaptable function object, however, does specify what the argument and return types are, and provides nested typedefs so that those types can be named and used in programs. If a type F is a model of an adaptable generator, then it must define F::result_type. Similarly, if G is a model of the adaptable unary function, it must define G::argument_type and G::result_type, and if H is a model of the adaptable binary function, it must define H::first_argument_type, H::second_argument_type, and H::result_type.

The C++ Standard Library provided base classes std::unary_function<A, T> and std::binary_function<A, B, T> to simplify the definition of adaptable unary functions and adaptable binary functions; these were deprecated in C++11 and removed in C++17, instead recommending using std::function<> or concepts.

Adaptable function objects are important, because they can be used by function object adaptors: function objects that transform or manipulate other function objects. The C++ Standard Library provides many different function object adaptors, such as std::unary_negate<Pred> (that returns the logical complement of the value returned by a particular adaptable predicate).

Predefined function objects

The C++ Standard Library includes in the header file <functional> many different predefined function objects, including arithmetic operations (std::plus<T>, std::minus<T>, std::multiplies<T>, std::divides<T>, std::modulus<T>, and std::negate<T>), comparisons (std::equal_to<T>, std::not_equal_to<T>, std::greater<T>, std::less<T>, std::greater_equal<T>, and std::less_equal<T>), and logical operations (std::logical_and<T>, std::logical_or<T>, and std::logical_not<T>).

Placeholders

Within the <functional> header, objects _1, _2, _3, up to an implementation-defined _N, act as placeholder objects used in std::bind() (a functional adapter used to generate new callable functions by binding specific arguments of an existing function) to define positions of unbound arguments. Their type is not specified by the standard, but std::is_placeholder<T> may be used to check if the template parameter T is a placeholder; if so, it derives from std::integral_constant<int, N>.

• In GCC libstdc++, this maximum _N is 29.
• In Clang/LLVM libc++, this maximum _N is 10.
• In MSVC STL, this maximum _N is 20.

Examples

Function wrappers can be used to make calls to ordinary functions or to functions objects created by lambda expressions.

import std;

using std::function;
using std::string;

using namespace std::placeholders;

// Define a template function 
void printValue(auto value) {
    std::println("{}", value);
}

int main() {
    // A function wrapper to a function 
    function<void(int)> a = printValue<int>;
    a(2015);

    // A function wrapper to a function pointer
    function<void(int)> b = &printValue<int>;
    b(2016);

    // A function wrapper to a lambda function.
    function<void(int)> c = [](int value) -> void {
        std::println("{}", value);
    };
    c(2017);

    // A function wrapper generated by std::bind().
    // Pass a pre-defined parameter when binding.
    function<void()> d = std::bind(printValue<string>, "PI is");
    d();

    // A function wrapper generated by std::bind().
    // Pass a parameter when calling the function.
    function<void(float)> e = std::bind(printValue<float>, _1);
    e(3.14159);
}

Function wrappers also can be used to access member variables and member functions of classes.

import std;

using std::function;

using namespace std::placeholders;

template <typename T>
class Box {
public:
    // intentionally left public
    T value;

    explicit Box(T value): 
        value{value} {}

    void print() { 
        std::println("{}", value); 
    }

    void printAfterAdd(T value) { 
        std::println("{}", this->value + value); 
    }
};

int main() {
    // A function wrapper to a member variable of a class
    Box<int> x{2016};
    function<int(Box<int>&)> a = &Box<int>::value;
    std::println("{}", a(x));

    // A function wrapper to member function without parameter passing 
    Box<float> y{2016.1};
    function<void(Box<float>&)> b = &Box<float>::print;
    b(y);

    // A function wrapper to member function with passing a parameter
    function<void(Box<float>&, float)> c = &Box<float>::printAfterAdd;
    c(y, 0.1);

    // A function wrapper to member function generated by std::bind
    function<void(float)> d = std::bind(
        &Box<float>::printAfterAdd,
        &y, 
        _1
    );
    d(0.2);
}

External links

• C++ reference for standard function objects