What is the "rvalue reference for *this" proposal?

Came across a proposal called "rvalue reference for *this" in clang's C++11 status page.

I've read quite a bit about rvalue references and understood them, but I don't think I know about this. I also couldn't find much resources on the web using the terms.

There's a link to the proposal paper on the page: N2439 (Extending move semantics to *this), but I'm also not getting much examples from there.

What is this feature about?

First, "ref-qualifiers for this" is a just a "marketing statement". The type of this never changes, see the bottom of this post. It's way easier to understand it with this wording though.

Next, the following code chooses the function to be called based on the ref-qualifier of the "implicit object parameter" of the function†:

// t.cpp
#include 

struct test{
  void f() &{ std::cout << "lvalue object\n"; }
  void f() &&{ std::cout << "rvalue object\n"; }
};

int main(){
  test t;
  t.f(); // lvalue
  test().f(); // rvalue
}

Output:

$ clang++ -std=c++0x -stdlib=libc++ -Wall -pedantic t.cpp
$ ./a.out
lvalue object
rvalue object

The whole thing is done to allow you to take advantage of the fact when the object the function is called on is an rvalue (unnamed temporary, for example). Take the following code as a further example:

struct test2{
  std::unique_ptr heavy_resource;

  test2()
    : heavy_resource(new int[500]) {}

  operator std::unique_ptr() const&{
    // lvalue object, deep copy
    std::unique_ptr p(new int[500]);
    for(int i=0; i () &&{
    // rvalue object
    // we are garbage anyways, just move resource
    return std::move(heavy_resource);
  }
};

This may be a bit contrived, but you should get the idea.

Note that you can combine the cv-qualifiers (const and volatile) and ref-qualifiers (& and &&).

Note: Many standard quotes and overload resolution explanation after here!

† To understand how this works, and why @Nicol Bolas' answer is at least partly wrong, we have to dig in the C++ standard for a bit (the part explaining why @Nicol's answer is wrong is at the bottom, if you're only interested in that).

Which function is going to be called is determined by a process called overload resolution. This process is fairly complicated, so we'll only touch the bit that is important to us.

First, it's important to see how overload resolution for member functions works:

§13.3.1 [over.match.funcs]

p2 The set of candidate functions can contain both member and non-member functions to be resolved against the same argument list. So that argument and parameter lists are comparable within this heterogeneous set, a member function is considered to have an extra parameter, called the implicit object parameter, which represents the object for which the member function has been called. [...]

p3 Similarly, when appropriate, the context can construct an argument list that contains an implied object argument to denote the object to be operated on.

Why do we even need to compare member and non-member functions? Operator overloading, that's why. Consider this:

struct foo{
  foo& operator<<(void*); // implementation unimportant
};

foo& operator<<(foo&, char const*); // implementation unimportant

You'd certainly want the following to call the free function, don't you?

char const* s = "free foo!\n";
foo f;
f << s;

That's why member and non-member functions are included in the so-called overload-set. To make the resolution less complicated, the bold part of the standard quote exists. Additionally, this is the important bit for us (same clause):

p4 For non-static member functions, the type of the implicit object parameter is

-
“lvalue reference to cv X” for functions declared without a ref-qualifier or with the & ref-qualifier

-
“rvalue reference to cv X” for functions declared with the && ref-qualifier

where X is the class of which the function is a member and cv is the cv-qualification on the member function declaration. [...]

p5 During overload resolution [...] [t]he implicit object parameter [...] retains its identity since conversions on the corresponding argument shall obey these additional rules:

-
no temporary object can be introduced to hold the argument for the implicit object parameter; and

-
no user-defined conversions can be applied to achieve a type match with it

[...]

(The last bit just means that you can't cheat overload resolution based on implicit conversions of the object a member function (or operator) is called on.)

Let's take the first example at the top of this post. After the aforementioned transformation, the overload-set looks something like this:

void f1(test&); // will only match lvalues, linked to 'void test::f() &'
void f2(test&&); // will only match rvalues, linked to 'void test::f() &&'

Then the argument list, containing an implied object argument, is matched against the parameter-list of every function contained in the overload-set. In our case, the argument list will only contain that object argument. Let's see how that looks like:

// first call to 'f' in 'main'
test t;
f1(t); // 't' (lvalue) can match 'test&' (lvalue reference)
       // kept in overload-set
f2(t); // 't' not an rvalue, can't match 'test&&' (rvalue reference)
       // taken out of overload-set

If, after all overloads in the set are tested, only one remains, the overload resolution succeeded and the functi

Stack Overflow Q#8610571, score: 331