Declares a named variable as a reference, that is, an alias to an already-existing object or function.

[edit]Syntax

A reference variable declaration is any simple declaration whosedeclarator has the form

A reference is required to be initialized to refer to a valid object or function: seereference initialization.

The type “reference to (possibly cv-qualified)void” cannot be formed.

Reference types cannot becv-qualified at the top level; there is no syntax for that in declaration, and if a qualification is added to a typedef-name ordecltype specifier,(since C++11) ortype template parameter, it is ignored.

References are not objects; they do not necessarily occupy storage, although the compiler may allocate storage if it is necessary to implement the desired semantics (e.g. a non-static data member of reference type usually increases the size of the class by the amount necessary to store a memory address).

Because references are not objects, there are no arrays of references, no pointers to references, and no references to references:

int& a[3];// errorint&* p;// errorint&&r;// error

typedefint&  lref;typedefint&& rref;int n; lref&  r1= n;// type of r1 is int&lref&& r2= n;// type of r2 is int&rref&  r3= n;// type of r3 is int&rref&& r4=1;// type of r4 is int&&

[edit]Lvalue references

Lvalue references can be used to alias an existing object (optionally with different cv-qualification):

#include <iostream>#include <string> int main(){std::string s="Ex";std::string& r1= s;conststd::string& r2= s;     r1+="ample";// modifies s//  r2 += "!";               // error: cannot modify through reference to conststd::cout<< r2<<'\n';// prints s, which now holds "Example"}

They can also be used to implement pass-by-reference semantics in function calls:

#include <iostream>#include <string> void double_string(std::string& s){    s+= s;// 's' is the same object as main()'s 'str'} int main(){std::string str="Test";    double_string(str);std::cout<< str<<'\n';}

When a function's return type is lvalue reference, the function call expression becomes anlvalue expression:

#include <iostream>#include <string> char& char_number(std::string& s,std::size_t n){return s.at(n);// string::at() returns a reference to char} int main(){std::string str="Test";    char_number(str,1)='a';// the function call is lvalue, can be assigned tostd::cout<< str<<'\n';}

#include <iostream>#include <string> int main(){std::string s1="Test";//  std::string&& r1 = s1;           // error: can't bind to lvalue conststd::string& r2= s1+ s1;// okay: lvalue reference to const extends lifetime//  r2 += "Test";                    // error: can't modify through reference to const std::string&& r3= s1+ s1;// okay: rvalue reference extends lifetime    r3+="Test";// okay: can modify through reference to non-conststd::cout<< r3<<'\n';}

#include <iostream>#include <utility> void f(int& x){std::cout<<"lvalue reference overload f("<< x<<")\n";} void f(constint& x){std::cout<<"lvalue reference to const overload f("<< x<<")\n";} void f(int&& x){std::cout<<"rvalue reference overload f("<< x<<")\n";} int main(){int i=1;constint ci=2;     f(i);// calls f(int&)    f(ci);// calls f(const int&)    f(3);// calls f(int&&)// would call f(const int&) if f(int&&) overload wasn't provided    f(std::move(i));// calls f(int&&) // rvalue reference variables are lvalues when used in expressionsint&& x=1;    f(x);// calls f(int& x)    f(std::move(x));// calls f(int&& x)}

int i2=42;int&& rri= std::move(i2);// binds directly to i2

std::vector<int> v{1,2,3,4,5};std::vector<int> v2(std::move(v));// binds an rvalue reference to vassert(v.empty());

template<class T>int f(T&& x)// x is a forwarding reference{return g(std::forward<T>(x));// and so can be forwarded} int main(){int i;    f(i);// argument is lvalue, calls f<int&>(int&), std::forward<int&>(x) is lvalue    f(0);// argument is rvalue, calls f<int>(int&&), std::forward<int>(x) is rvalue} template<class T>int g(const T&& x);// x is not a forwarding reference: const T is not cv-unqualified template<class T>struct A{template<class U>    A(T&& x, U&& y,int* p);// x is not a forwarding reference: T is not a// type template parameter of the constructor,// but y is a forwarding reference};

auto&& vec= foo();// foo() may be lvalue or rvalue, vec is a forwarding referenceauto i=std::begin(vec);// works either way(*i)++;// works either way g(std::forward<decltype(vec)>(vec));// forwards, preserving value category for(auto&& x: f()){// x is a forwarding reference; this is a common way to use range for in generic code} auto&& z={1,2,3};// *not* a forwarding reference (special case for initializer lists)

[edit]Dangling references

Although references always refer to valid objects or functions upon initialization, it is possible to create a program where thelifetime of the referred-to object ends, but the reference remains accessible (dangling).

Given an expressionexpr of reference type and lettarget be the object or function denoted by the reference:

• If a pointer totarget would bevalid in the context of the evalution ofexpr, the result designatestarget.
• Otherwise, the behavior is undefined.

std::string& f(){std::string s="Example";return s;// exits the scope of s:// its destructor is called and its storage deallocated} std::string& r= f();// dangling referencestd::cout<< r;// undefined behavior: reads from a dangling referencestd::string s= f();// undefined behavior: copy-initializes from a dangling reference

Note that rvalue references and lvalue references to const extend the lifetimes of temporary objects (seeReference initialization for rules and exceptions).

If the referred-to object was destroyed (e.g., by explicit destructor call), but the storage was not deallocated, a reference to the out-of-lifetime object may be used in limited ways, and may become valid if the object is recreated in the same storage (seeAccess outside of lifetime for details).

[edit]Type-inaccessible references

Attempting to bind a reference to an object where the converted initializer isan lvalue(until C++11)a glvalue(since C++11) through which the object is nottype-accessible results in undefined behavior:

char x alignas(int); int& ir=*reinterpret_cast<int*>(&x);// undefined behavior:// initializer refers to char object

[edit]Call-incompatible references

Attempting to bind a reference to a function where the converted initializer isan lvalue(until C++11)a glvalue(since C++11) whose type is notcall-compatible with the type of the function's definition results in undefined behavior:

void f(int); using F=void(float);F& ir=*reinterpret_cast<F*>(&f);// undefined behavior:// initializer refers to void(int) function

[edit]Notes

[edit]Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

[edit]External links

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文