std::forward_like

From cppreference.com
< cpp‎ | utility
 
 
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)
forward_like
(C++23)
(C++11)
(C++17)
Common vocabulary types
(C++11)
(C++17)
(C++17)
(C++17)
(C++11)
(C++17)
(C++23)
Elementary string conversions
(C++17)
(C++17)
 
Defined in header <utility>
template< class T, class U >
constexpr auto&& forward_like( U&& x ) noexcept;
(since C++23)

Returns a reference to x which has similar properties to T&&.

The return type is determined as below:

  1. If std::remove_reference_t<T> is a const-qualified type, then the referenced type of the return type is const std::remove_reference_t<U>. Otherwise, the referenced type is std::remove_reference_t<U>.
  2. If T&& is an lvalue reference type, then the return type is also a lvalue reference type. Otherwise, the return type is an rvalue reference type.

The program is ill-formed if T&& is not a valid type.

Parameters

x - a value needs to be forwarded like type T

Return value

A reference to x of the type determined as above.

Notes

As std::forward and std::move, std::forward_like is a type cast that only influences the value category of an expression.

When m is an actual member and thus o.m a valid expression, this is usually spelled as std::forward<decltype(o)>(o).m in C++20 code.

When o.m is not a valid expression, i.e. members of lambda closures, one needs std::forward_like</*see below*/>(m).

This leads to three possible models, called merge, tuple, and language.

  • merge: merge the const qualifiers, and adopt the value category of the Owner.
  • tuple: what std::get<0>(std::tuple<Member> Owner) does.
  • language: what std::forward<decltype(Owner)>(o).m does.

The main scenario that std::forward_like caters to is adapting “far” objects. Neither the tuple nor the language scenarios do the right thing for that main use-case, so the merge model is proposed.

Because we need two explicit template parameters, the definition (2) is compatible with calling it just std::forward, so we could use std::forward<decltype(o), decltype(m)>(m) instead of the longer std::forward_like<decltype(o), decltype(m)>(m) in these cases. This orthogonalizes the interface, which eases teaching. If forwarding members, just supply both.

Feature-test macro: __cpp_lib_forward_like

Possible implementation

template<class T, class U>
constexpr auto&& forward_like(U&& x) noexcept
{
    constexpr bool is_adding_const = std::is_const_v<std::remove_reference_t<T>>;
    if constexpr (std::is_lvalue_reference_v<T&&>) {
        if constexpr (is_adding_const) {
            return std::as_const(x);
        }
        else {
            return static_cast<U&>(x)
        }
    }
    else {
        if constexpr (is_adding_const) {
            return std::move(std::as_const(x));
        }
        else {
            return std::move(x);
        }
    }
}

Examples

Consider the task of calling an arbitrary function object f by perfect forwarding one argument from a non-member function. This is trivial if the argument being forwarded is taken as a forwarding reference.

template <typename F, typename X>
void call(F&& f, X&& x)
{
    std::forward<F>(f)(std::forward<X>(x));
}
 
int main()
{
    // lvalue
    int i{0};
    call([](int&){ }, i);
 
    // rvalue
    call([](int&&){ }, 0);
}

Now assume that the object that must be forwarded to f is stored in some sort of wrapper. This is not an uncommon situation when writing generic utility functions or algorithms that accept containers as arguments.

struct wrapper { int _data; };
 
template <typename F, typename Wrapper>
void call(F&& f, Wrapper&& w)
{
    std::forward<F>(f)(/* ??? */);
}
 
int main()
{
    // lvalue
    wrapper i{0};
    call([](int&){ }, i);
 
    // rvalue
    call([](int&&){ }, wrapper{0});
}

In order to correctly forward the non-static data member _data with the same value category as the parent wrapper, std::forward is not enough. The desired behavior is as follows:

  • If an lvalue is passed to call as w, f(w._data) must be invoked.
  • If an rvalue is passed to call as w, f(std::move(w._data)) must be invoked.

This is the same idea behind std::forward, with the difference that the type of the forwarded object doesn't have to match the explicitly-provided template argument. That's what std::forward_like is.

template <typename F, typename Wrapper>
void call(F&& f, Wrapper&& w)
{
    std::forward<F>(f)(std::forward_like<Wrapper>(w._data));
}

See also

(C++11)
obtains an rvalue reference
(function template)
(C++11)
forwards a function argument
(function template)
(C++17)
obtains a reference to const to its argument
(function template)