Add discard functor (#162)

* Add discard functor
* Add simple examples for discard
* Add docs for discard
* Add discard tests

Author: godexsoft

docs/expected/discard.md

@@ -0,0 +1,29 @@
+---
+title: fn::discard
+---
+
+##### Defined in {style: "api", badge: "#include <fn/discard.hpp>"}
+
+---
+
+:include-doxygen-doc: fn::discard_t
+
+---
+
+## Call signatures {style: "api"}
+:include-doxygen-member: fn::discard_t::operator() { signatureOnly: false, includeAllMatches: true }
+
+---
+
+## Return value {style: "api"}
+void
+
+---
+
+## Examples {style: "api"}
+
+:include-template: templates/snippet.md {
+    path:  "examples/simple.cpp",
+    surroundedBy: ["// example-error-struct", "// example-expected-discard"],
+    desc:  "`42` is observed by `inspect` and the value is discarded by `discard` (no warning for discarded result of `inspect`)."
+}

docs/optional/discard.md

@@ -0,0 +1,29 @@
+---
+title: fn::discard
+---
+
+##### Defined in {style: "api", badge: "#include <fn/discard.hpp>"}
+
+---
+
+:include-doxygen-doc: fn::discard_t
+
+---
+
+## Call signatures {style: "api"}
+:include-doxygen-member: fn::discard_t::operator() { signatureOnly: false, includeAllMatches: true }
+
+---
+
+## Return value {style: "api"}
+void
+
+---
+
+## Examples {style: "api"}
+
+:include-template: templates/snippet.md {
+    path:  "examples/simple.cpp",
+    surroundedBy: ["// example-error-struct", "// example-optional-discard"],
+    desc:  "`42` is observed by `inspect` and the value is discarded by `discard` (no warning for discarded result of `inspect`)."
+}

docs/toc

@@ -1,5 +1,6 @@
 expected
     and_then
+    discard
     fail
     filter
     inspect_error
@@ -11,6 +12,7 @@ expected
     value_or
 optional
     and_then
+    discard
     fail
     filter
     inspect_error

include/CMakeLists.txt

@@ -17,6 +17,7 @@ set(INCLUDE_FN_HEADERS
     fn/and_then.hpp
     fn/choice.hpp
     fn/concepts.hpp
+    fn/discard.hpp
     fn/expected.hpp
     fn/fail.hpp
     fn/filter.hpp

include/fn/detail/fwd.hpp

@@ -12,6 +12,7 @@ namespace fn {
 
 // functors
 struct and_then_t;
+struct discard_t;
 struct transform_t;
 struct transform_error_t;
 struct or_else_t;

include/fn/discard.hpp

@@ -0,0 +1,38 @@
+// Copyright (c) 2025 Bronek Kozicki, Alex Kremer
+//
+// Distributed under the ISC License. See accompanying file LICENSE.md
+// or copy at https://opensource.org/licenses/ISC
+
+#ifndef INCLUDE_FUNCTIONAL_DISCARD
+#define INCLUDE_FUNCTIONAL_DISCARD
+
+#include <fn/concepts.hpp>
+#include <fn/functor.hpp>
+
+#include <concepts>
+#include <type_traits>
+#include <utility>
+
+namespace fn {
+/**
+ * @brief Discard the value explicitly
+ *
+ * This is useful when only side-effects are desired and the final value is not needed.
+ *
+ * Use through the `fn::discard` nielbloid.
+ */
+constexpr inline struct discard_t final {
+  /**
+   * @brief Unconditionally discards the value
+   * @return A functor that explicitly discards the value
+   */
+  [[nodiscard]] constexpr auto operator()() const noexcept -> functor<discard_t> { return {}; }
+
+  struct apply final {
+    static constexpr auto operator()(some_monadic_type auto &&) noexcept -> void {}
+  };
+} discard = {};
+
+} // namespace fn
+
+#endif // INCLUDE_FUNCTIONAL_DISCARD

include/fn/functor.hpp

@@ -39,7 +39,6 @@ template <typename Functor, typename... Args> struct functor final {
   using data_t = pack<as_value_t<Args>...>;
   data_t data;
 
-  static_assert(sizeof...(Args) > 0); // NOTE Consider relaxing
   static_assert(std::is_empty_v<functor_type> && std::is_empty_v<functor_apply>
                 && std::is_default_constructible_v<functor_type> && std::is_default_constructible_v<functor_apply>);
 

tests/CMakeLists.txt

@@ -22,6 +22,7 @@ set(TESTS_FN_SOURCES
     fn/and_then.cpp
     fn/choice.cpp
     fn/concepts.cpp
+    fn/discard.cpp
     fn/expected.cpp
     fn/fail.cpp
     fn/filter.cpp

tests/examples/simple.cpp

@@ -4,6 +4,7 @@
 // or copy at https://opensource.org/licenses/ISC
 
 #include <fn/and_then.hpp>
+#include <fn/discard.hpp>
 #include <fn/fail.hpp>
 #include <fn/filter.hpp>
 #include <fn/inspect.hpp>
@@ -114,10 +115,19 @@ TEST_CASE("Minimal expected", "[expected][and_then]")
     REQUIRE(value.error().what == "Less than 42");
     // example-expected-filter-error
   }
+  {
+    // example-expected-discard
+    fn::expected<int, Error> ex{42};
+
+    // Observe for side-effects only
+    ex | fn::inspect([](int v) noexcept { REQUIRE(v == 42); })
+       | fn::discard();
+    // example-expected-discard
+  }
   // clang-format on
 }
 
-TEST_CASE("Demo expected", "[expected][pack][and_then][transform_error][transform][inspect][inspect_error]["
+TEST_CASE("Demo expected", "[expected][pack][and_then][discard][transform_error][transform][inspect][inspect_error]["
                            "recover][fail][filter][immovable]")
 {
   constexpr auto fn1 = [](char const *str, double &peek) {
@@ -219,6 +229,16 @@ TEST_CASE("Demo expected", "[expected][pack][and_then][transform_error][transfor
   auto const p4 = fn3("42", "12");
   CHECK(p4.has_value());
   CHECK(p4.value() == 42 * 12);
+
+  fn::expected<int, Error>{42}                                  //
+      | fn::inspect([](int v) noexcept { REQUIRE(v == 42); })   //
+      | fn::inspect_error([](Error) noexcept { CHECK(false); }) //
+      | fn::discard();
+
+  fn::expected<int, Error>{std::unexpected<Error>{"discarded"}}                     //
+      | fn::inspect([](int) noexcept { CHECK(false); })                             //
+      | fn::inspect_error([](Error e) noexcept { REQUIRE(e.what == "discarded"); }) //
+      | fn::discard();
 }
 
 TEST_CASE("Minimal optional", "[optional][and_then]")
@@ -250,28 +270,37 @@ TEST_CASE("Minimal optional", "[optional][and_then]")
   }
   {
     // example-optional-filter-value
-    fn::optional<int> ex{42};
+    fn::optional<int> op{42};
 
-    auto value = ex
+    auto value = op
         | fn::filter([](auto &&i) { return i >= 42; }); // Filter out values less than 42
 
     REQUIRE(value.value() == 42);
     // example-optional-filter-value
   }
   {
     // example-optional-filter-empty
-    fn::optional<int> ex{12};
+    fn::optional<int> op{12};
 
-    auto value = ex
+    auto value = op
         | fn::filter([](auto &&i) { return i >= 42; });
 
     REQUIRE(not value.has_value());
     // example-optional-filter-empty
   }
+  {
+    // example-optional-discard
+    fn::optional<int> op{42};
+
+    // Observe for side-effects only
+    op | fn::inspect([](int v) noexcept { REQUIRE(v == 42); })
+       | fn::discard();
+    // example-optional-discard
+  }
   // clang-format on
 }
 
-TEST_CASE("Demo optional", "[optional][pack][and_then][or_else][inspect][transform][fail][filter][recover]")
+TEST_CASE("Demo optional", "[optional][pack][and_then][discard][or_else][inspect][transform][fail][filter][recover]")
 {
   constexpr auto fn1 = [](char const *str, int &peek) {
     using namespace fn;
@@ -359,6 +388,10 @@ TEST_CASE("Demo optional", "[optional][pack][and_then][or_else][inspect][transfo
   auto const p4 = fn3("42", "12");
   CHECK(p4.has_value());
   CHECK(p4.value() == 42 * 12);
+
+  fn::optional<int>{42}                                       //
+      | fn::inspect([](int v) noexcept { REQUIRE(v == 42); }) //
+      | fn::discard();
 }
 
 TEST_CASE("Demo choice and graded monad", "[choice][and_then][inspect][transform][graded]")