✨ Add dereference

Problem:
- There is no standard function object that calls unary `operator*`.

Solution:
- Add `dereference`.

Author: elbeno

docs/functional.adoc

@@ -10,6 +10,24 @@ NOTE: https://wg21.link/P2714[P2714] added the ability (in C\\++26) to use a
 non-type template parameter for the bound function; this works for function
 pointers in C++17, and also for lambda expressions in C++20 and beyond.
 
+=== `dereference`
+
+`dereference` is a function object like
+https://en.cppreference.com/w/cpp/utility/functional/negate.html[`std::negate`],
+except it calls (unary) `operator*` instead of `operator-`.
+
+It also has a specialization for `void` which is _transparent_ like that of
+https://en.cppreference.com/w/cpp/utility/functional/negate_void.html[`std::negate`].
+
+=== `unary_plus`
+
+`unary_plus` is a function object like
+https://en.cppreference.com/w/cpp/utility/functional/negate.html[`std::negate`],
+except it calls (unary) `operator+` instead of `operator-`.
+
+It also has a specialization for `void` which is _transparent_ like that of
+https://en.cppreference.com/w/cpp/utility/functional/negate_void.html[`std::negate`].
+
 === `with_result_of`
 
 `with_result_of` is a class that can be used for lazy evaluation.
@@ -35,11 +53,3 @@ v.emplace(0, stdx::with_result_of{make_S}); // this constructs S in-place thanks
 `with_result_of` can help to achieve in-place construction, effectively by deferring
 evaluation of function arguments.
 
-=== `unary_plus`
-
-`unary_plus` is a function object like
-https://en.cppreference.com/w/cpp/utility/functional/negate.html[`std::negate`],
-except it calls (unary) `operator+` instead of `operator-`.
-
-It also has a specialization for `void` which is _transparent_ like that of
-https://en.cppreference.com/w/cpp/utility/functional/negate_void.html[`std::negate`].

include/stdx/functional.hpp

@@ -171,11 +171,15 @@ template <auto F, typename... Args> constexpr auto bind_back(Args &&...args) {
 
 #endif
 
+// NOLINTBEGIN(modernize-use-constraints)
 template <typename T = void> struct unary_plus {
-    constexpr auto operator()(T const &arg) const -> decltype(+arg) {
-        return +arg;
+    template <typename U,
+              typename = std::enable_if_t<is_same_unqualified_v<U, T>>>
+    constexpr auto operator()(U &&u) const -> decltype(+std::forward<U>(u)) {
+        return +std::forward<U>(u);
     }
 };
+// NOLINTEND(modernize-use-constraints)
 
 template <> struct unary_plus<void> {
     using is_transparent = int;
@@ -187,5 +191,25 @@ template <> struct unary_plus<void> {
     }
 };
 
+// NOLINTBEGIN(modernize-use-constraints)
+template <typename T = void> struct dereference {
+    template <typename U,
+              typename = std::enable_if_t<is_same_unqualified_v<U, T>>>
+    constexpr auto operator()(U &&u) const -> decltype(*std::forward<U>(u)) {
+        return *std::forward<U>(u);
+    }
+};
+// NOLINTEND(modernize-use-constraints)
+
+template <> struct dereference<void> {
+    using is_transparent = int;
+
+    template <typename T>
+    constexpr auto operator()(T &&arg) const
+        -> decltype(*std::forward<T>(arg)) {
+        return *std::forward<T>(arg);
+    }
+};
+
 } // namespace v1
 } // namespace stdx

test/functional.cpp

@@ -13,6 +13,7 @@ constexpr auto
 
 struct S {};
 constexpr auto operator+(S) { return 17; }
+constexpr auto operator*(S) { return 17; }
 } // namespace
 
 TEST_CASE("unary_plus", "[functional]") {
@@ -28,3 +29,18 @@ TEST_CASE("unary_plus transparency", "[functional]") {
 TEST_CASE("unary_plus calls operator+", "[functional]") {
     STATIC_REQUIRE(stdx::unary_plus<>{}(S{}) == 17);
 }
+
+TEST_CASE("dereference", "[functional]") {
+    int x{17};
+    CHECK(stdx::dereference<int *>{}(&x) == 17);
+    CHECK(stdx::dereference<>{}(&x) == 17);
+}
+
+TEST_CASE("dereference transparency", "[functional]") {
+    STATIC_REQUIRE(not detect_is_transparent<stdx::dereference<int *>>);
+    STATIC_REQUIRE(detect_is_transparent<stdx::dereference<>>);
+}
+
+TEST_CASE("dereference calls operator*", "[functional]") {
+    STATIC_REQUIRE(stdx::dereference<>{}(S{}) == 17);
+}