Add regular _ref option to in param and forward _ return; remove oddity inout: const

Closes #876

This keeps things nicely orthogonal addresses the two open issues with parameter passing:

- the oddity of `inout : const`, which becomes just `in_ref`
- the need to directly express both Cpp1 `-> decltype(auto)` and `-> auto&&`, which now are `-> forward _` and `-> forward_ref _`

Style      Parameter  Return
--------   ---------  -------
`in`          ⭐
`inout`       ✅
`out`         ✅
`copy`        ✅
`move`        ✅        ✅
`forward`     ✅        ⭐

The two ⭐'s are the cases that automatically pass/return _by value_ or reference:

- all uses of `in`
- deduced uses of `-> forward _` (ordinary `-> forward specific_type` always returns by reference, adding constness if there's an `in this` parameter)

Now both ⭐ cases also provide a `_ref` option to not choose by-value. This addresses the two open issues with parameter passing:

An example that illustrates both is std::min:

    min: (in_ref a, in_ref b) -> forward_ref _
        = { if b < a { return b; } else { return a; } }

    main: (args) = {
        x := 456;
        y := 123;
        std::cout << min(x, y) << '\n';
    }

The container<T>::operator[] case could already be written like this, where the first return lowers to Cpp1 `T const&` and the second to `T&`:

    container: <T> type = {
        buf: std::array<T, 10> = ();
        operator[]: (      this, idx: i32) -> forward T = buf[idx];
        operator[]: (inout this, idx: i32) -> forward T = buf[idx];
    }

    main: (args) = {
        v: container<int> = ();
        std::cout << v[0] << '\n';
    }

Author: hsutter

docs/cpp2/functions.md

@@ -14,6 +14,23 @@ func: ( /* no parameters */ ) = { /* empty body */ }
 
 ## <a id="function-signatures"></a> Function signatures: Parameters, returns, and using function types
 
+### <a id="parameter-kinds"></a> Overview
+
+There are six kinds of function parameters, and two of them are the kinds of functions returns:
+
+| Kind | Parameter | Return |
+| -------- | -------- | ------- |
+| `in` | ⭐   |  |
+| `inout` | ✅    | |
+| `out` | ✅  |   |
+| `copy` | ✅  | |
+| `move` | ✅  | ✅ |
+| `forward` | ✅  | ⭐ |
+
+The two cases marked ⭐ can automatically pass/return by value or by reference, and so they can be optionally written with `_ref` to require pass/return by reference and not by value (i.e., `in_ref`, `-> forward_ref`).
+
+That's it. For details, see below.
+
 ### <a id="parameters"></a> Parameters
 
 The parameter list is a [list](common.md#lists) enclosed by `(` `)` parentheses. Each parameter is declared using the [same unified syntax](declarations.md) as used for all declarations. For example:
@@ -42,14 +59,14 @@ calc: (number: _ is std::integral) = { /*...*/ }
 
 There are six ways to pass parameters that cover all use cases, that can be written before the parameter name:
 
-| Parameter ***kind*** | "Pass an `x` the function ______" | Accepts arguments that are | Special semantics | ***kind*** `x: X` Compiles to Cpp1 as |
+| Parameter&nbsp;***kind*** | "Pass an `x` the function ______" | Accepts arguments that are | Special semantics | ***kind*** `x: X` compiles&nbsp;to&nbsp;Cpp1&nbsp;as |
 |---|---|---|---|---|
-| `in` (default) | can read from | anything | always `#!cpp const`<p>automatically passes by value if cheaply copyable | `X const x` or `X const& x` |
-| `copy` | gets a copy of | anything | acts like a normal local variable initialized with the argument | `X x` |
-| `inout` | can read from and write to | lvalues | | `X& x` |
-| `out` | writes to (including construct) | lvalues (including uninitialized) | must `=` assign/construct before other uses | `cpp2::impl::out<X>` |
-| `move` | moves from (consume the value of) | rvalues | automatically moves from every definite last use | `X&&` |
-| `forward` | forwards | anything | automatically forwards from every definite last use | `T&&` constrained to type `X` |
+| <big>**`in`**</big> (default) | can read from | anything | always `#!cpp const`<p>automatically passes by value if cheaply copyable<br><br>to guarantee a by-reference passing, use `in_ref` | `X const x` or <br> `X const& x` |
+| <big>**`copy`**</big> | gets a copy of | anything | acts like a normal local variable initialized with the argument | `X x` |
+| <big>**`inout`**</big> | can read from and write to | lvalues | | `X& x` |
+| <big>**`out`**</big> | writes to (including construct) | lvalues (including uninitialized) | must `=` assign/construct before other uses | `cpp2::impl::out<X>` |
+| <big>**`move`**</big> | moves from (consume the value of) | rvalues | automatically moves from every definite last use | `X&&` |
+| <big>**`forward`**</big> | forwards | anything | automatically forwards from every definite last use<br><br> for a deduced type (`-> forward _`), deduces a by-reference or by-value return (the latter if the function returns an rvalue); to guarantee a by-reference return, use `-> forward_ref _` | for&nbsp;a&nbsp;specific&nbsp;type, `-> forward T` compiles to Cpp1 `-> T&&`, and adds `const` if the function has an `in this` parameter (Cpp1 `const` member function)<br><br> for a deduced type, `-> forward _` compiles to Cpp1 `-> decltype(auto)`, and `-> forward_ref _` compiles to Cpp1 `-> auto&&` |
 
 > Note: All parameters and other objects in Cpp2 are `#!cpp const` by default, except for local variables. For details, see [Design note: `#!cpp const` objects by default](https://github.com/hsutter/cppfront/wiki/Design-note%3A-const-objects-by-default).
 
@@ -76,11 +93,19 @@ wrap_f: (
 
 ### <a id="return-values"></a> Return values
 
-A function can return either of the following. The default is `#!cpp -> void`.
+A function can return either a single anonymous return value, or a return parameter list containing named return value(s). The default is `#!cpp -> void`.
 
-(1) **`#!cpp -> X`** to return a single unnamed value of type `X` using the same passing styles from the [parameters](#parameters) syntax, but where the only passing styles are `move` (the default) or `forward`.  The type can be  `#!cpp void` to signify the function has no return value. If `X` is not `#!cpp void`, the function body must have a `#!cpp return /*value*/;` statement that returns a value of type `X` on every path that exits the function.
+#### Single anonymous return values
 
-To deduce the return type, write `-> _`. A function whose body returns a single expression `expr` can deduce the return type, and omit writing the leading `-> _ = { return` and trailing `; }`.
+**`#!cpp ->` _kind_ `X`** to return a single unnamed value of type `X` using the same kinds as in the [parameters](#parameters) syntax, but where the only legal kinds are `move` (the default) or `forward` (with optional `forward_ref`; see below).  The type can be  `#!cpp -> void` to signify the function has no return value. If `X` is not `#!cpp void`, the function body must have a `#!cpp return /*value*/;` statement that returns a value of type `X` on every path that exits the function, or must be a single expression of type `X`.
+
+To deduce the return type, write `_`:
+
+- `-> _` deduces by-value return.
+- `-> forward _` deduces by-value return (if the function returns an rvalue) or by-reference return (everything else).
+- `-> forward_ref _` deduces by-reference return only.
+
+A function whose body is a single expression `= expr;` defaults to `-> forward _ = { return expr; }`.
 
 For example:
 
@@ -96,9 +121,9 @@ add_one: (a: i32) -> i32 = { return a+1; }
 add_one: (a: i32) -> i32 = a+1;
 
 //  A generic function returning a single value of deduced type
-add: <T: type, U: type> (a:T, b:U) -> decltype(a+b) = { return a+b; }
+add: <T: type, U: type> (a:T, b:U) -> forward _ = { return a+b; }
 //  Or, using syntactic defaults, the following have identical meaning:
-add: (a, b) -> _ = a+b;
+add: (a, b) -> forward _ = a+b;
 add: (a, b) a+b;
 
 //  A generic function expression returning a single value of deduced type
@@ -109,7 +134,9 @@ vec.std::ranges::sort( :(x,y) y<x );
 vec.std::ranges::sort( :<T:type, U:type> (x:T, y:U) -> _ = { return y<x; } );
 ```
 
-(2) **`#!cpp -> ( /* parameter list */ )`** to return a list of named return parameters using the same [parameters](#parameters) syntax, but where the only passing styles are `out` (the default, which moves where possible) or `forward`. The function body must [initialize](objects.md#init) the value of each return-parameter `ret` in its body the same way as any other local variable. An explicit return statement is written just `#!cpp return;` and returns the named values; the function has an implicit `#!cpp return;` at the end. If only a single return parameter is in the list, it is emitted in the lowered Cpp1 code the same way as (1) above, so its name is only available inside the function body.
+#### Return parameter lists: Nameable return value(s)
+
+**`#!cpp -> ( /* parameter list */ )`** to return a list of named return parameters using the same [parameters](#parameters) syntax, but where the only needed kinds are `out` (the default, which moves where possible) or `forward`. The function body must [initialize](objects.md#init) the value of each return-parameter `ret` in its body the same way as any other local variable. An explicit return statement is written just `#!cpp return;` and returns the named values; the function has an implicit `#!cpp return;` at the end. If only a single return parameter is in the list, it is emitted in the lowered Cpp1 code the same way as a single anonymous return value above, so its name is only available inside the function body.
 
 For example:
 
@@ -256,7 +283,7 @@ else {
 
 **`#!cpp do`** and **`#!cpp while`** are like always in C++, except that `(` `)` parentheses around the condition are not required. Instead, `{` `}` braces around the loop body *are* required.
 
-**`#!cpp for range do (e)`** ***statement*** says "for each element in `range`, call it `e` and perform the statement." The loop parameter `(e)` is an ordinary parameter that can be passed using any [parameter passing style](#parameters); as always, the default is `in`, which is read-only and expresses a read-only loop. The statement is not required to be enclosed in braces.
+**`#!cpp for range do (e)`** ***statement*** says "for each element in `range`, call it `e` and perform the statement." The loop parameter `(e)` is an ordinary parameter that can be passed using any [parameter kinds](#parameters); as always, the default is `in`, which is read-only and expresses a read-only loop. The statement is not required to be enclosed in braces.
 
 Every loop can have a `next` clause, that is performed at the end of each loop body execution. This makes it easy to have a counter for any loop, including a range `#!cpp for` loop.
 
@@ -433,9 +460,9 @@ Next, `: _` is also the default parameter type, so we don't need to write even t
 equals: (in a, in b) -> _ = { return a == b; }
 ```
 
-Next, `in` is the default [parameter passing mode](#parameters). So we can use that default too:
+Next, `in` is the default [parameter kind](#parameters). So we can use that default too:
 
-``` cpp title="equals: Identical meaning, now using the 'in' default parameter passing style"
+``` cpp title="equals: Identical meaning, now using the 'in' default parameter kind"
 equals: (a, b) -> _ = { return a == b; }
 ```
 

regression-tests/mixed-parameter-passing.cpp2

@@ -37,4 +37,21 @@ parameter_styles: (
 
 }
 
-main: () -> int = { }
+min: (in_ref a, in_ref b) -> forward_ref _
+    = { if b < a { return b; } else { return a; } }
+
+container: <T> type = {
+    buf: std::array<T, 10> = ();
+    operator[]: (      this, idx: i32) -> forward T = buf[idx];
+    operator[]: (inout this, idx: i32) -> forward T = buf[idx];
+}
+
+main: () = {
+    x := 456;
+    y := 123;
+    std::cout << min(x, y) << '\n';
+
+    v: container<int> = ();
+    std::cout << v[0] << '\n';
+}
+

regression-tests/pure2-last-use.cpp2

@@ -159,7 +159,7 @@ issue_850: () = {
     v: std::vector = ( 1, 2, 3, 4, 5 );
 
     //  Definite last use of v => move-capture v into f's closure
-    f := :() -> forward _ = { return v$; };
+    f := :() -> forward_ref _ = { return v$; };
 
     //  Now we can access the vector captured inside f()...
     f().push_back(6);

regression-tests/test-results/clang-12-c++20/mixed-parameter-passing.cpp.execution

@@ -0,0 +1,2 @@
+123
+0

regression-tests/test-results/gcc-10-c++20/mixed-parameter-passing.cpp.execution

@@ -0,0 +1,2 @@
+123
+0

regression-tests/test-results/gcc-14-c++2b/mixed-parameter-passing.cpp.execution

@@ -0,0 +1,2 @@
+123
+0

regression-tests/test-results/mixed-parameter-passing.cpp

@@ -7,6 +7,9 @@
 
 #line 1 "mixed-parameter-passing.cpp2"
 
+#line 43 "mixed-parameter-passing.cpp2"
+template<typename T> class container;
+    
 
 //=== Cpp2 type definitions and function declarations ===========================
 
@@ -27,7 +30,24 @@ auto parameter_styles(
     ) -> void;
 
 #line 40 "mixed-parameter-passing.cpp2"
-[[nodiscard]] auto main() -> int;
+[[nodiscard]] auto min(auto const& a, auto const& b) -> auto&&;
+
+#line 43 "mixed-parameter-passing.cpp2"
+template<typename T> class container {
+    private: std::array<T,10> buf {}; 
+    public: [[nodiscard]] auto operator[](cpp2::impl::in<cpp2::i32> idx) const& -> T const&;
+    public: [[nodiscard]] auto operator[](cpp2::impl::in<cpp2::i32> idx) & -> T&;
+    public: container() = default;
+    public: container(container const&) = delete; /* No 'that' constructor, suppress copy */
+    public: auto operator=(container const&) -> void = delete;
+
+#line 47 "mixed-parameter-passing.cpp2"
+};
+
+auto main() -> int;
+#line 57 "mixed-parameter-passing.cpp2"
+
+#line 1 "mixed-parameter-passing.cpp2"
 
 //=== Cpp2 function definitions =================================================
 
@@ -70,5 +90,21 @@ auto parameter_styles(
 }
 
 #line 40 "mixed-parameter-passing.cpp2"
-[[nodiscard]] auto main() -> int{}
+[[nodiscard]] auto min(auto const& a, auto const& b) -> auto&&
+    {if (cpp2::impl::cmp_less(b,a)) {return b; }else {return a; }}
+
+#line 45 "mixed-parameter-passing.cpp2"
+    template <typename T> [[nodiscard]] auto container<T>::operator[](cpp2::impl::in<cpp2::i32> idx) const& -> T const& { return CPP2_ASSERT_IN_BOUNDS(buf, idx); }
+#line 46 "mixed-parameter-passing.cpp2"
+    template <typename T> [[nodiscard]] auto container<T>::operator[](cpp2::impl::in<cpp2::i32> idx) & -> T& { return CPP2_ASSERT_IN_BOUNDS(buf, idx);  }
+
+#line 49 "mixed-parameter-passing.cpp2"
+auto main() -> int{
+    auto x {456}; 
+    auto y {123}; 
+    std::cout << min(cpp2::move(x), cpp2::move(y)) << '\n';
+
+    container<int> v {}; 
+    std::cout << CPP2_ASSERT_IN_BOUNDS_LITERAL(cpp2::move(v), 0) << '\n';
+}
 

regression-tests/test-results/msvc-2022-c++latest/mixed-parameter-passing.cpp.execution

@@ -0,0 +1,2 @@
+123
+0

regression-tests/test-results/pure2-bugfix-for-ufcs-name-lookup.cpp

@@ -28,7 +28,7 @@ namespace ns {
 #line 1 "pure2-bugfix-for-ufcs-name-lookup.cpp2"
 class identity {
 #line 2 "pure2-bugfix-for-ufcs-name-lookup.cpp2"
-  public: [[nodiscard]] constexpr auto operator()(auto&& x) const& -> auto&&;
+  public: [[nodiscard]] constexpr auto operator()(auto&& x) const& -> decltype(auto);
 };
 
 class t {
@@ -53,7 +53,7 @@ auto main() -> int;
 #line 1 "pure2-bugfix-for-ufcs-name-lookup.cpp2"
 
 #line 2 "pure2-bugfix-for-ufcs-name-lookup.cpp2"
-  [[nodiscard]] constexpr auto identity::operator()(auto&& x) const& -> auto&& { return CPP2_FORWARD(x);  }
+  [[nodiscard]] constexpr auto identity::operator()(auto&& x) const& -> decltype(auto) { return CPP2_FORWARD(x);  }
 
 #line 6 "pure2-bugfix-for-ufcs-name-lookup.cpp2"
   [[nodiscard]] constexpr auto t::f() const& -> int { return 0;  }

regression-tests/test-results/pure2-for-loop-range-with-lambda.cpp

@@ -12,15 +12,15 @@
 //=== Cpp2 type definitions and function declarations ===========================
 
 #line 1 "pure2-for-loop-range-with-lambda.cpp2"
-[[nodiscard]] auto first(auto&& f, [[maybe_unused]] auto&& ...unnamed_param_2) -> auto&&;
+[[nodiscard]] auto first(auto&& f, [[maybe_unused]] auto&& ...unnamed_param_2) -> decltype(auto);
 
 #line 3 "pure2-for-loop-range-with-lambda.cpp2"
 auto main(int const argc_, char** argv_) -> int;
 
 //=== Cpp2 function definitions =================================================
 
 #line 1 "pure2-for-loop-range-with-lambda.cpp2"
-[[nodiscard]] auto first(auto&& f, [[maybe_unused]] auto&& ...unnamed_param_2) -> auto&& { return CPP2_FORWARD(f);  }
+[[nodiscard]] auto first(auto&& f, [[maybe_unused]] auto&& ...unnamed_param_2) -> decltype(auto) { return CPP2_FORWARD(f);  }
 
 #line 3 "pure2-for-loop-range-with-lambda.cpp2"
 auto main(int const argc_, char** argv_) -> int{

regression-tests/test-results/pure2-forward-return.cpp

@@ -14,7 +14,7 @@
 #line 1 "pure2-forward-return.cpp2"
 
 #line 2 "pure2-forward-return.cpp2"
-[[nodiscard]] auto first(auto&& rng) -> auto&&;
+[[nodiscard]] auto first(auto&& rng) -> decltype(auto);
 
 #line 7 "pure2-forward-return.cpp2"
 extern int const global;
@@ -27,7 +27,7 @@ extern int const global;
 #line 1 "pure2-forward-return.cpp2"
 
 #line 2 "pure2-forward-return.cpp2"
-[[nodiscard]] auto first(auto&& rng) -> auto&& { 
+[[nodiscard]] auto first(auto&& rng) -> decltype(auto) { 
     if (cpp2::bounds_safety.is_active() && !(!(std::empty(rng))) ) { cpp2::bounds_safety.report_violation(""); }
 
 #line 5 "pure2-forward-return.cpp2"

regression-tests/test-results/pure2-last-use.cpp

@@ -81,7 +81,7 @@ auto f_inout([[maybe_unused]] auto& unnamed_param_1) -> void;
 auto f_copy([[maybe_unused]] auto ...unnamed_param_1) -> void;
 [[nodiscard]] auto pred([[maybe_unused]] auto const& ...unnamed_param_1) -> auto;
 [[nodiscard]] auto pred_copy([[maybe_unused]] auto ...unnamed_param_1) -> auto;
-template<typename T> [[nodiscard]] constexpr auto identity(T&& x) -> auto&&
+template<typename T> [[nodiscard]] constexpr auto identity(T&& x) -> decltype(auto)
 CPP2_REQUIRES (std::is_reference_v<T>) ;
 #line 6 "pure2-last-use.cpp2"
 [[nodiscard]] auto identity_copy(auto x) -> auto
@@ -560,7 +560,7 @@ auto f_copy([[maybe_unused]] auto ...unnamed_param_1) -> void{}
 #line 4 "pure2-last-use.cpp2"
 [[nodiscard]] auto pred_copy([[maybe_unused]] auto ...unnamed_param_1) -> auto { return true;  }
 #line 5 "pure2-last-use.cpp2"
-template<typename T> [[nodiscard]] constexpr auto identity(T&& x) -> auto&&
+template<typename T> [[nodiscard]] constexpr auto identity(T&& x) -> decltype(auto)
 requires (std::is_reference_v<T>) {return CPP2_FORWARD(x); }
 #line 6 "pure2-last-use.cpp2"
 [[nodiscard]] auto identity_copy(auto x) -> auto
@@ -1430,7 +1430,7 @@ namespace captures {
 auto f() -> void{
   auto x {cpp2_new<int>(0)}; 
   f_copy(std::move(cpp2::move(x)));
-  auto id {[](auto const& x) -> auto&& { return x;  }}; 
+  auto id {[](auto const& x) -> decltype(auto) { return x;  }}; 
   auto y {cpp2_new<int>(0)}; 
   if (cpp2::cpp2_default.is_active() && !(&cpp2::move(id)(y) == &y) ) { cpp2::cpp2_default.report_violation(""); }
 }

regression-tests/test-results/version

@@ -1,5 +1,5 @@
 
-cppfront compiler v0.7.4   Build 9930:1408
+cppfront compiler v0.7.4   Build 9A03:1357
 Copyright(c) Herb Sutter   All rights reserved
 
 SPDX-License-Identifier: CC-BY-NC-ND-4.0

source/build.info

@@ -1 +1 @@
-"9930:1408"
+"9A03:1357"