🎨 Make call_by_need deal with functions returning references

Problem:
- If `call_by_need` calls a function returning a reference, it decays the result
  into the results tuple. It should preserve lvalue references generated in this
  way.

Solution:
- Preserve lvalue references in the results tuple.

Author: elbeno

docs/call_by_need.adoc

@@ -3,9 +3,7 @@
 
 `call_by_need` is a function that takes a xref:tuple.adoc#_tuple_hpp[tuple] of
 functions and a tuple of arguments, and applies the functions to the arguments
-as needed. It returns a tuple of results, with any unused arguments forwarded as
-if by a call to
-https://en.cppreference.com/w/cpp/utility/functional/identity.html[`std::identity`].
+as needed. It returns a tuple of results, with any unused arguments also sent along.
 
 NOTE: `call_by_need` is available only in C++20 and later.
 
@@ -33,16 +31,22 @@ auto args = stdx::tuple{arg<0>{}};
 auto r = stdx::call_by_need(funcs, args); // tuple{17, 42}
 ----
 
-If arguments are unused, they are treated as if `std::identity` was appended to
-the set of functions:
+If arguments are unused, they are treated as if by a call to `safe_forward`:
 [source,cpp]
 ----
+template <typename T>
+constexpr auto safe_forward(T&& t) -> T { return t; }
+
 auto funcs = stdx::tuple{[] (arg<0>) { return 17; }};
 auto args = stdx::tuple{arg<0>{}, arg<1>{}}; // arg<1>{} is unused
 
 auto r = stdx::call_by_need(funcs, args); // tuple{17, arg<1>{}}
 ----
 
+NOTE: `safe_forward` forwards rvalue references so that they are
+moved into the results tuple as owned values, but preserves lvalue references so
+that they appear in the results tuple as lvalue references.
+
 Arguments and functions do not have to be in corresponding order; the results will be
 in the same order as the functions.
 [source,cpp]

include/stdx/call_by_need.hpp

@@ -9,14 +9,10 @@
 #include <algorithm>
 #include <array>
 #include <cstddef>
-#include <functional>
 #include <iterator>
 #include <type_traits>
 #include <utility>
 
-template <auto...> struct undef_v;
-template <typename...> struct undef_t;
-
 namespace stdx {
 inline namespace v1 {
 namespace cbn_detail {
@@ -145,6 +141,10 @@ template <typename... Fs> struct by_need {
         return concat(given_calls, extra_calls);
     }
 };
+
+struct safe_forward {
+    template <typename T> constexpr auto operator()(T &&t) -> T { return t; }
+};
 } // namespace cbn_detail
 
 template <tuplelike Fs, tuplelike Args>
@@ -160,13 +160,18 @@ constexpr auto call_by_need(Fs &&fs, Args &&args) {
           std::make_index_sequence<tuple_size_v<remove_cvref_t<Args>>>{});
 
     auto new_fs = [&]<std::size_t... Is>(std::index_sequence<Is...>) {
-        return tuple{get<Is>(std::forward<Fs>(fs))..., std::identity{}};
+        return tuple{get<Is>(std::forward<Fs>(fs))...,
+                     cbn_detail::safe_forward{}};
     }(std::make_index_sequence<tuple_size_v<Fs>>{});
 
     auto ret = [&]<std::size_t... Is>(std::index_sequence<Is...>) {
-        return tuple{cbn_detail::invoke<calls[Is].arg_base, calls[Is].arg_len>(
-            get<calls[Is].fn_idx>(std::move(new_fs)),
-            std::forward<Args>(args))...};
+        return tuple<
+            decltype(cbn_detail::invoke<calls[Is].arg_base, calls[Is].arg_len>(
+                get<calls[Is].fn_idx>(std::move(new_fs)),
+                std::forward<Args>(args)))...>{
+            cbn_detail::invoke<calls[Is].arg_base, calls[Is].arg_len>(
+                get<calls[Is].fn_idx>(std::move(new_fs)),
+                std::forward<Args>(args))...};
     }(std::make_index_sequence<calls.size()>{});
     return stdx::filter<cbn_detail::is_nonvoid_t>(std::move(ret));
 }

test/call_by_need.cpp

@@ -138,6 +138,14 @@ TEST_CASE("move-only return", "[call_by_need]") {
     STATIC_REQUIRE(get<0>(r).value == 17);
 }
 
+TEST_CASE("move-only function", "[call_by_need]") {
+    constexpr auto r = stdx::call_by_need(
+        stdx::tuple{[m = move_only{17}](int) mutable { return std::move(m); }},
+        stdx::tuple{17});
+    STATIC_REQUIRE(std::is_same_v<decltype(r), stdx::tuple<move_only> const>);
+    STATIC_REQUIRE(get<0>(r) == move_only{17});
+}
+
 TEST_CASE("converted arguments", "[call_by_need]") {
     auto const r = stdx::call_by_need(stdx::tuple{[](char c) {
                                                       CHECK(c == 'a');
@@ -197,3 +205,12 @@ TEST_CASE("no functions given", "[call_by_need]") {
     STATIC_REQUIRE(std::is_same_v<decltype(r), stdx::tuple<int> const>);
     STATIC_REQUIRE(get<0>(r) == 17);
 }
+
+TEST_CASE("function returning reference", "[call_by_need]") {
+    int value{17};
+    auto const r = stdx::call_by_need(
+        stdx::tuple{[&](arg_t<0>) -> int & { return value; }},
+        stdx::tuple{arg<0>});
+    STATIC_REQUIRE(std::is_same_v<decltype(r), stdx::tuple<int &> const>);
+    CHECK(get<0>(r) == 17);
+}