Namespaces
Variants
Views
Actions

std::bind_front, std::bind_back

From cppreference.com
< cpp‎ | utility‎ | functional
 
 
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++23)
(C++11)
(C++17)

Elementary string conversions
(C++17)
(C++17)
 
Function objects
Function wrappers
(C++11)
(C++11)
Partial function application
bind_frontbind_back
(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)
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)
 
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:

Contents

[edit] 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.

[edit] 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).

[edit] Exceptions

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

[edit] 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.

[edit] Example

#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

[edit] See also

(C++11)
binds one or more arguments to a function object
(function template) [edit]
(C++11)
creates a function object out of a pointer to a member
(function template) [edit]