std::forward

 

C++

Language

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

 

Utilities library

Type support (basic types, RTTI, type traits)

Dynamic memory management

Error handling

Program utilities

Variadic functions

Date and time

Function objects

initializer_list (C++11)

bitset

hash (C++11)

Relational operators

rel_ops::operator!= rel_ops::operator> rel_ops::operator<= rel_ops::operator>=

Pairs and tuples

pair

tuple (C++11)

piecewise_construct_t (C++11)

piecewise_construct (C++11)

Swap, forward and move

swap

forward (C++11)

move (C++11)

move_if_noexcept (C++11)

declval (C++11)

 

Defined in header <utility>
template< class T > T&& forward( typename std::remove_reference<T>::type& t );	(1)	(since C++11)
template< class T > T&& forward( typename std::remove_reference<T>::type&& t );	(2)	(since C++11)

When used according to the following recipe in a function template, forwards the argument to another function exactly as it was passed to the calling function.

template<typename T>
wrapper(T&& arg) {
  foo(std::forward<T>(arg));
}

• If a call to wrapper() passes an rvalue std::string, then T is deduced to std::string (not std::string&, const std::string&, or std::string&&), and std::forward ensures that an rvalue reference is passed to foo.
• If a call to wrapper() passes a const lvalue std::string, then T is deduced to const std::string&, and std::forward ensures that a const lvalue reference is passed to foo.
• If a call to wrapper() passes a non-const lvalue std::string, then T is deduced to std::string&, and std::forward ensures that a non-const lvalue reference is passed to foo.

Notes

Attempting to forward an rvalue as an lvalue, such as by instantiating the form 2) with lvalue reference type T, is a compile-time error.

Parameters

t

-

the object to be forwarded

Return value

static_cast<T&&>(t)

Exceptions

noexcept specification:  

noexcept

  (since C++11)

Example

This example demonstrates perfect forwarding of the parameter of the function make_unique() to the argument of the constructor of class T

#include <iostream>
#include <memory>
#include <utility>
 
struct A {
    A(int&& n) { std::cout << "rvalue overload, n=" << n << "\n"; }
    A(int& n)  { std::cout << "lvalue overload, n=" << n << "\n"; }
};
 
template<class T, class U>
std::unique_ptr<T> make_unique(U&& u)
{
    return std::unique_ptr<T>(new T(std::forward<U>(u)));
}
 
int main()
{
    std::unique_ptr<A> p1 = make_unique<A>(2); // rvalue
    int i = 1;
    std::unique_ptr<A> p2 = make_unique<A>(i); // lvalue
}

Output:

rvalue overload, n=2
lvalue overload, n=1

Complexity

Constant

See also

move (C++11)	obtains an rvalue reference (function template)
move_if_noexcept (C++11)	obtains an rvalue reference if the move constructor does not throw (function template)