Forwarding references and perfect forwarding

A logging factory that takes const std::string& copies every name it is given, even a temporary it could have moved, and one that takes std::string&& rejects a named string. A forwarding referenceforwarding reference: A reference written auto&&, or T&& in a template whose T is deduced, that binds to anything: it becomes an lvalue reference for a named variable and an rvalue reference for a temporary. More in “C++ auto, decltype and type aliases” accepts both: a parameter written T&&, where T is a template parameter deduced from the call, as in template <typename T> void f(T&& x), or a variable declared auto&&. For an lvalue, T is deduced as an lvalue reference, and reference collapsingreference collapsing: The rule that turns a reference to a reference, formed through a template parameter or an alias, into one reference: an lvalue reference wins whenever one is involved, and only && combined with && stays &&. With T = std::string&, T&& is std::string&. turns T&& into an lvalue reference too; for an rvalue, T is the plain type and the parameter is an rvalue referencervalue reference: A reference declared with &&, such as int&& r, that binds to temporaries and other objects about to expire but never to a named variable. Unlike a const reference, it lets you change the object it names. More in “C++ references: lifetime extension and dangling”. Inside the function the parameter has a name, so it is an lvalue, and std::forward<T>(x) casts it back to the category the caller used. Doing that for every argument is perfect forwardingperfect forwarding: Passing each argument of a wrapper on with the value category the caller gave it, through a forwarding reference and std::forward<T>, so that the wrapped call copies lvalues and moves rvalues exactly as a direct call would.: emplace_back and std::make_unique hand their arguments to a constructor as if the caller had called it directly, copying lvalues and moving rvalues.

T&& is a forwarding reference only when T is deduced

The rule is narrow. The parameter must be exactly T&&, with no const, and T must be deduced from this very call. Forwarding references are the parameters of function templates written like that, and auto&& variables. Everything else spelled with && is an ordinary rvalue reference that accepts only rvalues:

• const T&& is an rvalue reference to const, because the const breaks the rule.
• std::vector<T>&& is an rvalue reference to a vector, because the parameter is not T&& itself.
• void push(T&& item) inside template <typename T> class Queue is an rvalue reference, because T was fixed when the class was instantiated, not deduced by the call.

Step through the tests with each declaration:

The program below calls template <typename T> void show(T&&) with four arguments and prints what T and the parameter became:

// What T becomes in template <typename T> void show(T&& x), for four kinds of argument, and what T&& collapses to.
#include <print>
#include <string>
#include <utility>

template <typename T> constexpr const char* name = "?";
template <> constexpr const char* name<std::string> = "std::string";
template <> constexpr const char* name<std::string&> = "std::string&";
template <> constexpr const char* name<std::string&&> = "std::string&&";
template <> constexpr const char* name<const std::string> = "const std::string";
template <> constexpr const char* name<const std::string&> = "const std::string&";
template <> constexpr const char* name<const std::string&&> = "const std::string&&";

template <typename T>
void show(const char* call, T&&) {
    std::println("{:<26} T = {:<20} parameter = {}", call, name<T>, name<T&&>);
}

std::string make() { return "made"; }

int main() {
    std::string s = "text";
    const std::string c = "constant";
    show("show(s)", s);
    show("show(c)", c);
    show("show(std::move(s))", std::move(s));
    show("show(make())", make());
}

from session import run

run("""
clang++ -std=c++23 -Wall -Wextra deduce.cpp -o deduce && ./deduce
g++-16 -std=c++23 -Wall -Wextra deduce.cpp -o deduce-gcc
./deduce > clang.txt && ./deduce-gcc > gcc.txt && diff clang.txt gcc.txt && echo "GCC deduces the same"
""")

$ clang++ -std=c++23 -Wall -Wextra deduce.cpp -o deduce && ./deduce
show(s)                    T = std::string&         parameter = std::string&
show(c)                    T = const std::string&   parameter = const std::string&
show(std::move(s))         T = std::string          parameter = std::string&&
show(make())               T = std::string          parameter = std::string&&
$ g++-16 -std=c++23 -Wall -Wextra deduce.cpp -o deduce-gcc
$ ./deduce > clang.txt && ./deduce-gcc > gcc.txt && diff clang.txt gcc.txt && echo "GCC deduces the same"
GCC deduces the same

For the lvalue s, T is std::string&, and the const lvalue c keeps its const in T. For the xvalue std::move(s) and the prvalue make(), T is plain std::string, and the parameter is std::string&&. That asymmetry, a reference in T only for lvalues, is how the function can later tell what it was given.

Reference collapsing gives the parameter its type

T&& with T = std::string& would be a reference to a reference, which C++ does not allow you to write. When such a type arises through a template parameter or an alias, the standard collapses it into one reference, and an lvalue reference wins whenever one is involved. In the table, U stands for any type, such as std::string:

Only an rvalue reference combined with an rvalue reference stays an rvalue reference. The “parameter” column of the run above is this table applied to the deduced T: for show(c), T is const std::string&, so T&& collapses to const std::string&. The same table explains auto&&: in auto&& y = s;, auto is deduced as std::string&, so y is a std::string& bound to s.

std::forward restores the caller’s value category

std::forward<T>(x) is defined as static_cast<T&&>(x). When T is std::string&, that collapses to std::string& and the result is an lvalue; when T is std::string, the result is an xvalue that can be moved from, as the two columns of the diagram show:

You always write the template argument, because std::forward must not deduce it: the information lives in T, not in the type of x. A factory that forwards a pack of arguments passes each one on with its own category:

// make_logged<T>(args...) passes its arguments on to T's constructor exactly as it received them, and each
// constructor of Badge prints which one ran.
#include <print>
#include <string>
#include <utility>

struct Badge {
    std::string name;
    int level = 0;
    Badge(const std::string& n) : name(n) { std::println("    Badge(const std::string&): copied the name"); }
    Badge(std::string&& n) : name(std::move(n)) { std::println("    Badge(std::string&&): moved the name"); }
    Badge(const std::string& n, int l) : name(n), level(l) { std::println("    Badge(const std::string&, int)"); }
};

template <typename T, typename... Args>
T make_logged(Args&&... args) {
    std::println("make_logged with {} argument(s)", sizeof...(args));
    return T(std::forward<Args>(args)...);
}

int main() {
    std::string name = "Asha Rao";
    Badge a = make_logged<Badge>(name);              // an lvalue: copied
    Badge b = make_logged<Badge>(std::move(name));   // an xvalue: moved
    Badge c = make_logged<Badge>(std::string("Ravi"));
    Badge d = make_logged<Badge>(a.name, 3);
    std::println("a = {}, b = {}, c = {}, d = {} (level {}); name is now \"{}\"", a.name, b.name, c.name, d.name, d.level, name);
}

from session import run

run("""
clang++ -std=c++23 -Wall -Wextra make_logged.cpp -o make_logged && ./make_logged
g++-16 -std=c++23 -Wall -Wextra make_logged.cpp -o make_logged-gcc
./make_logged > clang.txt && ./make_logged-gcc > gcc.txt && diff clang.txt gcc.txt && echo "GCC prints the same"
""")

$ clang++ -std=c++23 -Wall -Wextra make_logged.cpp -o make_logged && ./make_logged
make_logged with 1 argument(s)
    Badge(const std::string&): copied the name
make_logged with 1 argument(s)
    Badge(std::string&&): moved the name
make_logged with 1 argument(s)
    Badge(std::string&&): moved the name
make_logged with 2 argument(s)
    Badge(const std::string&, int)
a = Asha Rao, b = Asha Rao, c = Ravi, d = Asha Rao (level 3); name is now ""
$ g++-16 -std=c++23 -Wall -Wextra make_logged.cpp -o make_logged-gcc
$ ./make_logged > clang.txt && ./make_logged-gcc > gcc.txt && diff clang.txt gcc.txt && echo "GCC prints the same"
GCC prints the same

Step through the four calls:

make_logged<Badge>(name) reached the constructor that copies, and make_logged<Badge>(std::move(name)) the one that moves, so name ended up empty, as it would with Badge(std::move(name)) written directly. A temporary went to the moving constructor, and two arguments went to the two-parameter constructor. Perfect forwarding is exactly that: make_logged adds a log line and changes nothing about which constructor runs. It is also how emplace_back, std::make_unique and std::invoke pass on what they receive. Rule F.19 of the C++ Core Guidelines puts it in one line: pass “forward” parameters as TP&& and only std::forward them.

Where forwarding goes wrong, and where it is used

• std::move on a forwarding reference moves from the caller’s lvalue too, so the caller’s object is emptied.
• Forwarding twice passes an rvalue on twice, so the second receiver gets a moved-from object.
• A greedy forwarding constructor matches a non-const object better than the copy constructor does.
• An overload next to a forwarding template loses arguments of nearby types, such as a short passed to an int overload, to the template.
• emplace_back forwards constructor arguments into the vector’s own storage, so no temporary is built first.
• decltype(auto) makes a call wrapper return exactly the type the wrapped call returns, references included.
• auto&& in a range-for loop binds to every element type, including the proxy objects of std::vector<bool>.
• A generic lambda with an auto&& parameter has a forwarding reference too, but no template parameter to name in std::forward<T>.

Practise: deduce, collapse, forward

Questions on deduction, collapsing and std::forward follow, weakest idea first; a missed one returns before the end.

Four forwarding bugs reproduced, with their fixes Pro: opens with a Pro, Premium or Ultimate pass

Forwarding in real code: emplace, call wrappers and auto&& Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

Key takeaways

• T&& with T deduced by the call, and auto&&, are forwarding references: they bind to lvalues and rvalues alike.
• For an lvalue argument T is an lvalue reference; reference collapsing turns T&& into an lvalue reference.
• A parameter passed on by name is an lvalue; std::forward<T>(x) restores the category the caller passed.
• Perfect forwarding passes every argument on unchanged, so a wrapper reaches the same constructor as a direct call.
• const T&&, std::vector<T>&& and T&& in a class template’s member function are ordinary rvalue references.