View source for cpp/utility/functional/bind front

{{cpp/title|bind_front|bind_back}}
{{cpp/utility/functional/navbar}}
{{dcl begin}}
{{dcl header|functional}}
{{dcl h|{{tt|std::bind_front}}}}
{{dcla|num=1|since=c++20|
template< class F, class... Args >
constexpr /* unspecified */ bind_front( F&& f, Args&&... args );
}}
{{dcla|num=2|since=c++26|
template< auto ConstFn, class... Args >
constexpr /* unspecified */ bind_front( Args&&... args );
}}
{{dcl h|{{tt|std::bind_back}}}}
{{dcla|num=3|since=c++23|
template< class F, class... Args >
constexpr /* unspecified */ bind_back( F&& f, Args&&... args );
}}
{{dcla|num=4|since=c++26|
template< auto ConstFn, class... Args >
constexpr /* unspecified */ bind_back( Args&&... args );
}}
{{dcl end}}

Function templates {{tt|std::bind_front}} and {{tt|std::bind_back}} generate a perfect forwarding call wrapper which allows to invoke the callable target with its {{v|1,2}} first or {{v|3,4}} last {{c|sizeof...(Args)}} parameters bound to {{c|args}}.

@1,3@ The call wrapper holds a copy of the target callable object {{c|f}}.
@2,4@ The call wrapper does not hold a callable target (it is statically determined).

@1@ {{c|std::bind_front(f, bound_args...)(call_args...)}} is [[cpp/language/expressions#Expression-equivalence|expression-equivalent]] to
@@ {{c|std::invoke(f, bound_args..., call_args...)}}.

@2@ {{c|std::bind_front<ConstFn>(bound_args...)(call_args...)}} is [[cpp/language/expressions#Expression-equivalence|expression-equivalent]] to
@@ {{c|std::invoke(ConstFn, bound_args..., call_args...)}}.

@3@ {{c|std::bind_back(f, bound_args...)(call_args...)}} is [[cpp/language/expressions#Expression-equivalence|expression-equivalent]] to
@@ {{c|std::invoke(f, call_args..., bound_args...)}}.

@4@ {{c|std::bind_back<ConstFn>(bound_args...)(call_args...)}} is [[cpp/language/expressions#Expression-equivalence|expression-equivalent]] to
@@ {{c|std::invoke(ConstFn, call_args..., bound_args...)}}.

The following conditions must be {{c/core|true}}, otherwise the program is ill-formed:

* {{v|1,3}} {{c|std::is_constructible_v<std::decay_t<F>, F>}},
* {{v|1,3}} {{c|std::is_move_constructible_v<std::decay_t<F>>}},
* {{v|2,4}} If {{c|decltype(ConstFn)}} is a pointer or a pointer-to-member then {{tt|ConstFn}} is not a null pointer,
* {{c|(std::is_constructible_v<std::decay_t<Args>, Args> && ...)}},
* {{c|(std::is_move_constructible_v<std::decay_t<Args>> && ...)}}.

===Parameters===
{{par begin}}
{{par|f|{{named req|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}}
{{par|args|list of the arguments to bind to the {{vl|1,2}} first or {{vl|3,4}} last {{c|sizeof...(Args)}} parameters of the callable target}}
{{par hreq}}
{{par req named|{{c|std::decay_t<F>}}|MoveConstructible}}
{{par req named|{{c|std::decay_t<Args>...}}|MoveConstructible}}
{{par req named|{{c|decltype(ConstFn)}}|Callable}}
{{par end}}

===Return value===
A function object (the call wrapper) of type {{tt|T}} that is unspecified, except that the types of objects returned by two calls to {{tt|std::bind_front}} or {{tt|std::bind_back}} with the same arguments are the same.

Let {{tti|bind-partial}} be either {{tt|std::bind_front}} or {{tt|std::bind_back}}.

The returned object has the following properties:
{{member|''{{small|bind-partial}} return type''|2=

====Member objects====
The returned object behaves as if it holds:
@1,3@ A member object {{tt|fd}} of type {{c|std::decay_t<F>}} direct-non-list-initialized from {{c|std::forward<F>(f)}}, and
@1-4@ An {{lc|std::tuple}} object {{tt|tup}} constructed with {{c|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 {{tti|bind-partial}} behaves as if its copy/move constructors perform a memberwise copy/move. It is {{named req|CopyConstructible}} if all of its member objects (specified above) are {{named req/core|CopyConstructible}}, and is {{named req|MoveConstructible}} otherwise.

====Member function {{tt|operator()}}====
Given an object {{tt|G}} obtained from an earlier call to {{vl|1,3}} {{tt|''bind-partial''(f, args...)}} or {{vl|2,4}} {{tt|''bind-partial''<ConstFn>(args...)}}, when a glvalue {{tt|g}} designating {{tt|G}} is invoked in a function call expression {{c|g(call_args...)}}, an invocation of the stored object takes place, as if by:
@1@ {{c|std::invoke(g.fd, std::get<Ns>(g.tup)..., call_args...)}}, when {{tti|bind-partial}} is {{tt|std::bind_front}},
@2@ {{c|std::invoke(ConstFn, std::get<Ns>(g.tup)..., call_args...)}}, when {{tti|bind-partial}} is {{tt|std::bind_front}},
@3@ {{c|std::invoke(g.fd, call_args..., std::get<Ns>(g.tup)...)}}, when {{tti|bind-partial}} is {{tt|std::bind_back}},
@4@ {{c|std::invoke(ConstFn, call_args..., std::get<Ns>(g.tup)...)}}, when {{tti|bind-partial}} is {{tt|std::bind_back}},

where
:* {{tt|Ns}} is an integer pack {{tt|0, 1, ..., (sizeof...(Args) - 1)}},
:* {{tt|g}} is an lvalue in the {{lc|std::invoke}} expression if it is an lvalue in the call expression, and is an rvalue otherwise. Thus {{c|std::move(g)(call_args...)}} can move the bound arguments into the call, where {{c|g(call_args...)}} would copy.

The program is ill-formed if {{tt|g}} has volatile-qualified type.

The member {{c|operator()}} is {{ltt|cpp/language/noexcept}} if the {{lc|std::invoke}} expression it calls is noexcept (in other words, it preserves the exception specification of the underlying call operator).
}}

===Exceptions===
@1,3@ Throw any exception thrown by calling the constructor of the stored function object.
@1-4@ Throw any exception thrown by calling the constructor of any of the bound arguments.

===Notes===
These function templates are intended to replace {{lc|std::bind}}. Unlike {{tt|std::bind}}, they do not support arbitrary argument rearrangement and have no special treatment for nested bind-expressions or {{lc|std::reference_wrapper}}s. 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 {{lc|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 {{lc|std::shared_ptr}} and {{lc|std::unique_ptr}}) to an object whose member will be accessed.

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

Typically, binding arguments to a function or a member function using {{vl|1}} {{tt|std::bind_front}} and {{vl|3}} {{tt|std::bind_back}} requires storing a function pointer along with the arguments, even though the language knows precisely which function to call without a need to dereference the pointer. To guarantee "zero cost" in those cases, C++26 introduces the versions {{vl|2,4}} (that accept the callable object as an argument for {{lsd|cpp/language/template parameters#Non-type template parameter}}).

{{ftm begin|sort=yes}}
{{ftm|std=C++20|value=201907L|__cpp_lib_bind_front|rowspan="2"|{{tt|std::bind_front}}, {{vl|1}}}}
{{ftm|std=C++26|value=202306L|-|Allow passing callable objects as non-type template arguments to {{tt|std::bind_front}}, {{vl|2}}}}
{{ftm|std=C++23|value=202202L|__cpp_lib_bind_back|rowspan="2"|{{tt|std::bind_back}}, {{vl|3}}}}
{{ftm|std=C++26|value=202306L|-|Allow passing callable objects as non-type template arguments to {{tt|std::bind_back}}, {{vl|4}}}}
{{ftm end}}

===Possible implementation===
{{eq impl
|title1=(2) bind_front|ver1=2|1=
namespace detail
{
    template<class T, class U>
    struct copy_const
        : std::conditional<std::is_const_v<T>, U const, U> {};

    template<class T, class U,
             class X = typename copy_const<std::remove_reference_t<T>, U>::type>
    struct copy_value_category
        : std::conditional<std::is_lvalue_reference_v<T&&>, X&, X&&> {};

    template <class T, class U>
    struct type_forward_like
        : copy_value_category<T, std::remove_reference_t<U>> {};

    template <class T, class U>
    using type_forward_like_t = typename type_forward_like<T, U>::type;
}

template<auto ConstFn, class... Args>
constexpr auto bind_front(Args&&... args)
{
    using F = decltype(ConstFn);

    if constexpr (std::is_pointer_v<F> or std::is_member_pointer_v<F>)
        static_assert(ConstFn != nullptr);

    return
        [... bound_args(std::forward<Args>(args))]<class Self, class... T>
        (
            this Self&&, T&&... call_args
        )
        noexcept
        (
            std::is_nothrow_invocable_v<F,
                detail::type_forward_like_t<Self, std::decay_t<Args>>..., T...>
        )
        -> std::invoke_result_t<F,
                detail::type_forward_like_t<Self, std::decay_t<Args>>..., T...>
        {
            return std::invoke(ConstFn, std::forward_like<Self>(bound_args)...,
                               std::forward<T>(call_args)...);
        };
}
|title2=(4) bind_back|ver2=4|2=
namespace detail { /* is the same as above */ }

template<auto ConstFn, class... Args>
constexpr auto bind_back(Args&&... args)
{
    using F = decltype(ConstFn);

    if constexpr (std::is_pointer_v<F> or std::is_member_pointer_v<F>)
        static_assert(ConstFn != nullptr);

    return
        [... bound_args(std::forward<Args>(args))]<class Self, class... T>
        (
            this Self&&, T&&... call_args
        )
        noexcept
        (
            std::is_nothrow_invocable_v<F,
                detail::type_forward_like_t<Self, T..., std::decay_t<Args>>...>
        )
        -> std::invoke_result_t<F,
                detail::type_forward_like_t<Self, T..., std::decay_t<Args>>...>
        {
            return std::invoke(ConstFn, std::forward<T>(call_args)...,
                               std::forward_like<Self>(bound_args)...);
        };
}

}}

===Example===
{{example
|code=
#include <cassert>
#include <functional>

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);
    assert(fifty_minus(3) == 47); // equivalent to: minus(50, 3) == 47

    auto member_minus = std::bind_front(&S::minus, S{50});
    assert(member_minus(3) == 47); //: S tmp{50}; tmp.minus(3) == 47

    // 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);
    assert(forty_plus(7) == 47); // equivalent to: plus(40, 7) == 47

#if __cpp_lib_bind_front >= 202306L
    auto fifty_minus_cpp26 = std::bind_front<minus>(50);
    assert(fifty_minus_cpp26(3) == 47);

    auto member_minus_cpp26 = std::bind_front<&S::minus>(S{50});
    assert(member_minus_cpp26(3) == 47);

    auto forty_plus_cpp26 = std::bind_front<plus>(40);
    assert(forty_plus(7) == 47);
#endif

#if __cpp_lib_bind_back >= 202202L
    auto madd = [](int a, int b, int c) { return a * b + c; };
    auto mul_plus_seven = std::bind_back(madd, 7);
    assert(mul_plus_seven(4, 10) == 47); //: madd(4, 10, 7) == 47
#endif

#if __cpp_lib_bind_back >= 202306L
    auto mul_plus_seven_cpp26 = std::bind_back<madd>(7);
    assert(mul_plus_seven_cpp26(4, 10) == 47);
#endif
}
}}

===References===
{{ref std c++26}}
{{ref std|title=Function templates bind_front and bind_back|id=func.bind.partial|section=TBD}}
{{ref std end}}
{{ref std c++23}}
{{ref std|title=Function templates bind_front and bind_back|id=func.bind.partial|section=22.10.14}}
{{ref std end}}
{{ref std c++20}}
{{ref std|title=Function template bind_front|id=func.bind.front|section=20.14.14}}
{{ref std end}}

===See also===
{{dsc begin}}
{{dsc inc|cpp/utility/functional/dsc bind}}
{{dsc inc|cpp/utility/functional/dsc mem_fn}}
{{dsc end}}

{{langlinks|es|ja|ru|zh}}