# std::bind_front, std::bind_back

From cppreference.com
< cpp‎ | utility‎ | functional

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 `std::bind_front` and `std::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:

- std::is_constructible_v<std::decay_t<F>, F>
- std::is_move_constructible_v<std::decay_t<F>>
- (std::is_constructible_v<std::decay_t<Args>, Args> && ...)
- (std::is_move_constructible_v<std::decay_t<Args>> && ...)

### 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 | Value | Std | Comment
--- | --- | --- | ---
`__cpp_lib_bind_front` | 201907L | (C++20) | `std::bind_front`
`__cpp_lib_bind_back` | 202202L | (C++23) | `std::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

bind (C++11) | binds one or more arguments to a function object (function template)
mem_fn (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=152114"