std::bind_front, std::bind_back

From cppreference.com
< cpp‎ | utility‎ | functional
 
C++
 
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++20)
(C++14)
(C++11)
(C++23)
(C++11)
(C++23)
(C++11)
(C++11)
(C++17)
Common vocabulary types
(C++11)
(C++17)
(C++17)
(C++17)
(C++11)
(C++11)
(C++17)
(C++17)
(C++23)
Elementary string conversions
(C++17)
(C++17)
(C++17)
 
Function objects
Function wrappers
(C++11)
(C++23)
(C++11)
(C++11)
Partial function application
bind_frontbind_back
(C++20)(C++23)
(C++11)
(C++11)
(C++11)
(C++11)
Function invocation
(C++17)(C++23)
Identity function object
(C++20)
Reference wrappers
(C++11)
(C++11)(C++11)
(C++20)(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)
(C++14)
(C++14)
(C++14)
(C++14)
(C++14)
(C++14)
Negators
(C++17)
Searchers
(C++17)
(C++17)
(C++17)
Constrained comparators
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
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++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)
 
Defined in header <functional>
template <class F, class... Args>
constexpr /*unspecified*/ bind_front( F&& f, Args&&... args );
 (1) (since C++20)
template <class F, class... Args>
constexpr /*unspecified*/ bind_back( F&& f, Args&&... args );
 (2) (since C++23)

Function templates bind_front and bind_back generate a forwarding call wrapper for f. Calling this wrapper is equivalent to invoking f with its (1) first or (2) last sizeof...(Args) parameters bound to args.

In other words:

  • std::bind_front(f, bound_args...)(call_args...) is equivalent to std::invoke(f, bound_args..., call_args...).
  • std::bind_back(f, bound_args...)(call_args...) is equivalent to std::invoke(f, call_args..., bound_args...).

The program is ill-formed if any of the following is false:

Parameters

f - Callable object (function object, pointer to function, reference to function, pointer to member function, or pointer to data member) that will be bound to some arguments
args - list of the arguments to bind to the (1) first or (2) last sizeof...(Args) parameters of f
Type requirements
-
std::decay_t<F> and each type in std::decay_t<Args>... must meet the requirements of MoveConstructible.

Return value

A function object of type T that is unspecified, except that the types of objects returned by two calls to std::bind_front or std::bind_back with the same arguments are the same.

The returned object (call wrapper) has the following properties:

bind-partial return type

Let bind-partial be either std::bind_front or std::bind_back.

Member objects

The returned object behaves as if it holds a member object fd of type std::decay_t<F> direct-non-list-initialized from std::forward<F>(f), and an std::tuple object tup constructed with std::tuple<std::decay_t<Args>...>(std::forward<Args>(args)...), except that the returned object's assignment behavior is unspecified and the names are for exposition only.

Constructors

The return type of bind-partial behaves as if its copy/move constructors perform a memberwise copy/move. It is CopyConstructible if all of its member objects (specified above) are CopyConstructible, and is MoveConstructible otherwise.

Member function operator()

Given an object G obtained from an earlier call to bind-partial(f, args...), when a glvalue g designating G is invoked in a function call expression g(call_args...), an invocation of the stored object takes place, as if by

  • std::invoke(g.fd, std::get<Ns>(g.tup)..., call_args...), when bind-partial is std::bind_front, or by
  • std::invoke(g.fd, call_args..., std::get<Ns>(g.tup)...), when bind-partial is std::bind_back, where
  • Ns is an integer pack 0, 1, ..., (sizeof...(Args) - 1)
  • g is an lvalue in the std::invoke expression if it is an lvalue in the call expression, and is an rvalue otherwise. Thus std::move(g)(call_args...) can move the bound arguments into the call, where g(call_args...) would copy.

The program is ill-formed if g has volatile-qualified type.

The member operator() is noexcept if the std::invoke expression it calls is noexcept (in other words, it preserves the exception specification of the underlying call operator).

Exceptions

Only throws if construction of stored function object or any of the bound arguments throws.

Notes

These function templates are intended to replace std::bind. Unlike std::bind, they do not support arbitrary argument rearrangement and have no special treatment for nested bind-expressions or std::reference_wrappers. On the other hand, they pay attention to the value category of the call wrapper object and propagate exception specification of the underlying call operator.

As described in std::invoke, when invoking a pointer to non-static member function or pointer to non-static data member, the first argument has to be a reference or pointer (including, possibly, smart pointer such as std::shared_ptr and std::unique_ptr) to an object whose member will be accessed.

The arguments to std::bind_front or std::bind_back are copied or moved, and are never passed by reference unless wrapped in std::ref or std::cref.

Feature-test macro: __cpp_lib_bind_front
Feature-test macro: __cpp_lib_bind_back

Example

Run this code
#include <functional>
#include <iostream>
 
int minus(int a, int b)
{
    return a - b;
}
 
struct S
{
    int val;
    int minus(int arg) const noexcept { return val - arg; }
};
 
int main()
{
    auto fifty_minus = std::bind_front(minus, 50);
    std::cout << fifty_minus (3) << '\n'; // equivalent to `minus(50, 3)`
 
    auto member_minus = std::bind_front(&S::minus, S{50});
    std::cout << member_minus (3) << '\n'; // equivalent to `S tmp{50}; tmp.minus(3)`
 
    // noexcept-specification is preserved!
    static_assert(! noexcept(fifty_minus (3)));
    static_assert(noexcept(member_minus (3)));
 
    // binding of a lambda
    auto plus = [](int a, int b) { return a + b; };
    auto forty_plus = std::bind_front(plus, 40);
    std::cout << forty_plus(7) << '\n'; // equivalent to `plus(40, 7)`
 
    #ifdef __cpp_lib_bind_back
    auto madd = [](int a, int b, int c) { return a * b + c; };
    auto mul_plus_seven = std::bind_back(madd, 7);
    std::cout << mul_plus_seven(4, 10) << '\n'; // equivalent to `madd(4, 10, 7)`
    #endif
}

Possible output: 

47
47
47
47

See also

(C++11)
 binds one or more arguments to a function object
(function template)
(C++11)
 creates a function object out of a pointer to a member
(function template)
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/utility/functional/bind_front&oldid=140602"