std::forward_like

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros(C++20)

Language support library

Concepts library(C++20)

Diagnostics library

Memory management library

Metaprogramming library(C++11)

General utilities library

Containers library

Iterators library

Ranges library(C++20)

Algorithms library

Strings library

Text processing library

Numerics library

Date and time library

Input/output library

Filesystem library(C++17)

Concurrency support library(C++11)

Execution control library(C++26)

Technical specifications

Symbols index

External libraries

 

Utilities library

Language support Type support (basic types, RTTI) Library feature-test macros(C++20) Program utilities Variadic functions initializer_list (C++11) is_constant_evaluated (C++20) is_within_lifetime (C++26) source_location (C++20) Coroutine support(C++20) Contract support(C++26) Three-way comparison three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)   is_eqis_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

General utilities Function objects Bit manipulation(C++20) bitset hash (C++11) Relational operators(deprecated in C++20) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= Integer comparison functions cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)   cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Swap and type operations swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Common vocabulary types pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23)

 

Defined in header <utility>
template<class T, class U > constexprauto&& 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 conststd::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>constexprauto&& forward_like(U&& x)noexcept{constexprbool is_adding_const =std::is_const_v<std::remove_reference_t<T>>;ifconstexpr(std::is_lvalue_reference_v<T&&>){ifconstexpr(is_adding_const)returnstd::as_const(x);elsereturnstatic_cast<U&>(x);}else{ifconstexpr(is_adding_const)return std::move(std::as_const(x));elsereturn 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>;ifconstexpr(std::is_lvalue_reference_v<SelfType>){ifconstexpr(std::is_const_v<UnrefSelfType>)std::cout<<"const lvalue\n";elsestd::cout<<"mutable lvalue\n";}else{ifconstexpr(std::is_const_v<UnrefSelfType>)std::cout<<"const rvalue\n";elsestd::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)throwstd::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 (C++11)	converts the argument to an xvalue (function template)
forward (C++11)	forwards a function argument and use the type template argument to preserve its value category (function template)
as_const (C++17)	obtains a reference to const to its argument (function template)