Added __rvalue function attribute to the spec. (#4183)

Author: TurkeyMan

spec/attribute.dd

@@ -30,6 +30,7 @@ $(GNAME Attribute):
     $(RELATIVE_LINK2 override, $(D override))
     $(RELATIVE_LINK2 ref, $(D ref))
     $(RELATIVE_LINK2 return, $(D return))
+    $(RELATIVE_LINK2 __rvalue, $(D __rvalue))
     $(RELATIVE_LINK2 scope, $(D scope))
     $(RELATIVE_LINK2 shared, $(D shared))
     $(RELATIVE_LINK2 static, $(D static))
@@ -733,6 +734,10 @@ $(H2 $(LNAME2 return, $(D return) Attribute))
     * $(DDSUBLINK spec/function, return-ref-parameters, Return Ref Parameters).
     * $(DDSUBLINK spec/function, return-scope-parameters, Return Scope Parameters).
 
+$(H2 $(LNAME2 __rvalue, $(D __rvalue) Attribute))
+
+    * $(DDSUBLINK spec/expression, __rvalue-function-attribute, $(I RvalueExpression)).
+
 $(H2 $(LNAME2 static, $(D static) Attribute))
 
         $(P The $(D static) attribute applies to types, functions and data.

spec/expression.dd

@@ -3596,6 +3596,23 @@ void oops()
 
     $(P $(I RvalueExpression)s enable the use of $(I move constructor)s and $(I move assignment)s.)
 
+$(H4 $(LNAME2 __rvalue-function-attribute, As a function attribute))
+
+    $(P It is also allowed to use the $(CODE __rvalue) keyword as a function attribute. The presence of this
+    attribute will infer the $(I RvalueExpression) upon the function call expression at the call-site,
+    as if applied to the function's return value. This is only accepted on functions that return by reference.
+    )
+
+---
+ref S fun(return ref S s) __rvalue
+{
+    return s;
+}
+
+S s;
+S t = fun(s); // call inferred as: __rvalue(fun(s))
+---
+
 $(H3 $(LNAME2 specialkeywords, Special Keywords))
 
 $(GRAMMAR