std::forward_like(3)

NAME
std::forward_like - std::forward_like

Synopsis
   Defined in header <utility>
   template< class T, class U > (since C++23)
   [[nodiscard]] constexpr auto&& forward_like( U&& x ) noexcept;
   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 an lvalue
       reference type. Otherwise, the return type is an rvalue reference type.
   If T is not a referenceable type, the program is ill-formed.

Parameters
   x - a value needs to be forwarded like type T

Return value
   A reference to x of the type determined as above.

Notes
   Like std::forward, std::move, and std::as_const, std::forward_like is a type cast
   that only influences the value category of an expression, or potentially adds
   const-qualification.
   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.
   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>(Owner) does, assuming Owner is a std::tuple<Member>.
     * 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 used for std::forward_like.
     Feature-test macro Value Std Feature
   __cpp_lib_forward_like 202207L (C++23) std::forward_like

Possible implementation
   template<class T, class U>
   [[nodiscard]] 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);
       }
   }

Example
// Run this code
 #include <cstddef>
 #include <iostream>
 #include <memory>
 #include <optional>
 #include <type_traits>
 #include <utility>
 #include <vector>
 struct TypeTeller
 {
     void operator()(this auto&& self)
     {
         using SelfType = decltype(self);
         using UnrefSelfType = std::remove_reference_t<SelfType>;
         if constexpr (std::is_lvalue_reference_v<SelfType>)
         {
             if constexpr (std::is_const_v<UnrefSelfType>)
                 std::cout << "const lvalue\n";
             else
                 std::cout << "mutable lvalue\n";
         }
         else
         {
             if constexpr (std::is_const_v<UnrefSelfType>)
                 std::cout << "const rvalue\n";
             else
                 std::cout << "mutable rvalue\n";
         }
     }
 };
 struct FarStates
 {
     std::unique_ptr<TypeTeller> ptr;
     std::optional<TypeTeller> opt;
     std::vector<TypeTeller> container;
     auto&& from_opt(this auto&& self)
     {
         return std::forward_like<decltype(self)>(self.opt.value());
         // It is OK to use std::forward<decltype(self)>(self).opt.value(),
         // because std::optional provides suitable accessors.
     }
     auto&& operator[](this auto&& self, std::size_t i)
     {
         return std::forward_like<decltype(self)>(self.container.at(i));
         // It is not so good to use std::forward<decltype(self)>(self)[i], because
         // containers do not provide rvalue subscript access, although they could.
     }
     auto&& from_ptr(this auto&& self)
     {
         if (!self.ptr)
             throw std::bad_optional_access{};
         return std::forward_like<decltype(self)>(*self.ptr);
         // It is not good to use *std::forward<decltype(self)>(self).ptr, because
         // std::unique_ptr<TypeTeller> always dereferences to a non-const lvalue.
     }
 };
 int main()
 {
     FarStates my_state
     {
         .ptr{std::make_unique<TypeTeller>()},
         .opt{std::in_place, TypeTeller{}},
         .container{std::vector<TypeTeller>(1)},
     };
     my_state.from_ptr()();
     my_state.from_opt()();
     my_state[0]();
     std::cout << '\n';
     std::as_const(my_state).from_ptr()();
     std::as_const(my_state).from_opt()();
     std::as_const(my_state)[0]();
     std::cout << '\n';
     std::move(my_state).from_ptr()();
     std::move(my_state).from_opt()();
     std::move(my_state)[0]();
     std::cout << '\n';
     std::move(std::as_const(my_state)).from_ptr()();
     std::move(std::as_const(my_state)).from_opt()();
     std::move(std::as_const(my_state))[0]();
     std::cout << '\n';
 }

Output:
 mutable lvalue
 mutable lvalue
 mutable lvalue
 const lvalue
 const lvalue
 const lvalue
 mutable rvalue
 mutable rvalue
 mutable rvalue
 const rvalue
 const rvalue
 const rvalue

See also
   move obtains an rvalue reference
   (C++11) (function template)
   forward forwards a function argument
   (C++11) (function template)
   as_const obtains a reference to const to its argument
   (C++17) (function template)