Add API make_proxy_ref

Author: mingxwa

docs/spec/.pages

@@ -32,6 +32,7 @@ nav:
     - allocate_proxy_shared: allocate_proxy_shared.md
     - allocate_proxy: allocate_proxy.md
     - make_proxy_inplace: make_proxy_inplace.md
+    - make_proxy_ref: make_proxy_ref.md
     - make_proxy_shared: make_proxy_shared.md
     - make_proxy_view: make_proxy_view.md
     - make_proxy: make_proxy.md

docs/spec/README.md

@@ -52,6 +52,7 @@ This document provides the API specifications for the C++ library Proxy (version
 | [`allocate_proxy_shared`](allocate_proxy_shared.md) | Creates a `proxy` object with shared ownership using an allocator |
 | [`allocate_proxy`](allocate_proxy.md)               | Creates a `proxy` object with an allocator                   |
 | [`make_proxy_inplace`](make_proxy_inplace.md)       | Creates a `proxy` object with strong no-allocation guarantee |
+| [`make_proxy_ref`](make_proxy_ref.md)               | Creates a `proxy` object with no ownership                   |
 | [`make_proxy_shared`](make_proxy_shared.md)         | Creates a `proxy` object with shared ownership               |
 | [`make_proxy_view`](make_proxy_view.md)             | Creates a `proxy_view` object                                |
 | [`make_proxy`](make_proxy.md)                       | Creates a `proxy` object potentially with heap allocation    |

docs/spec/make_proxy_ref.md

@@ -0,0 +1,50 @@
+# Function template `make_proxy_ref`
+
+> Header: `proxy.h`  
+> Module: `proxy`  
+> Namespace: `pro::inline v4`  
+> Since: 4.1.0
+
+The definition of `make_proxy_ref` makes use of an exposition-only class template *observer-ptr*. `observer-ptr<T>` contains a raw pointer to an object of type `T`, and provides `operator*` for access with the same qualifiers.
+
+```cpp
+template <facade F, class T>
+proxy<F> make_proxy_ref(T& value) noexcept;
+```
+
+Creates a `proxy<F>` object containing a value `p` of type `observer-ptr<T>`, where `*p` is direct-non-list-initialized with `&value`. If [`proxiable_target<T, F>`](proxiable_target.md) is `false`, the program is ill-formed and diagnostic messages are generated.
+
+## Return Value
+
+The constructed `proxy` object.
+
+## Example
+
+```cpp
+#include <iostream>
+
+#include <proxy/proxy.h>
+
+struct Printable : pro::facade_builder //
+                   ::add_convention<pro::operator_dispatch<"<<", true>,
+                                    std::ostream&(std::ostream&) const> //
+                   ::build {};
+
+int main() {
+  int val = 123;
+  pro::proxy<Printable> p = pro::make_proxy_ref<Printable>(val);
+
+  // Prints "123"
+  std::cout << *p << "\n";
+
+  val = 456;
+
+  // Prints "456"
+  std::cout << *p << "\n";
+}
+```
+
+## See Also
+
+- [concept `proxiable_target`](proxiable_target.md)
+- [function template `make_proxy_view`](make_proxy_view.md)

include/proxy/v4/proxy.h

@@ -1818,6 +1818,11 @@ constexpr proxy<F> make_proxy_inplace(T&& value) noexcept(
                   std::in_place, std::forward<T>(value)};
 }
 
+template <facade F, class T>
+constexpr proxy<F> make_proxy_ref(T& value) noexcept {
+  return proxy<F>{details::observer_ptr<T&, const T&, T&&, const T&&>{value}};
+}
+
 template <facade F, class T>
 constexpr proxy_view<F> make_proxy_view(T& value) noexcept {
   return proxy_view<F>{

tests/proxy_creation_tests.cpp

@@ -1222,3 +1222,27 @@ TEST(ProxyCreationTests, TestMakeProxyView) {
   p = pro::make_proxy_view<TestFacade>(test_callable);
   ASSERT_EQ((*std::move(std::as_const(p)))(), 3);
 }
+
+TEST(ProxyCreationTests, TestMakeProxyRef) {
+  struct TestFacade
+      : pro::facade_builder //
+        ::add_convention<pro::operator_dispatch<"()">, int() &, int() const&,
+                         int() && noexcept, int() const&&> //
+        ::build {};
+
+  struct {
+    int operator()() & noexcept { return 0; }
+    int operator()() const& noexcept { return 1; }
+    int operator()() && noexcept { return 2; }
+    int operator()() const&& noexcept { return 3; }
+  } test_callable;
+
+  pro::proxy<TestFacade> p = pro::make_proxy_ref<TestFacade>(test_callable);
+  static_assert(!noexcept((*p)()));
+  static_assert(noexcept((*std::move(p))()));
+  ASSERT_EQ((*p)(), 0);
+  ASSERT_EQ((*std::as_const(p))(), 1);
+  ASSERT_EQ((*std::move(p))(), 2);
+  p = pro::make_proxy_ref<TestFacade>(test_callable);
+  ASSERT_EQ((*std::move(std::as_const(p)))(), 3);
+}