complete docs. for code

Author: Cppshizoid

lib/library1/include/utils/curry.hpp

@@ -0,0 +1,210 @@
+#pragma once
+
+#include <functional>
+#include <print>
+#include <tuple>
+#include <type_traits>
+#include <utility>
+
+namespace core::meta::utils {
+
+/**
+ * @class curried
+ * @brief A class template that implements function currying - transforming a
+ * function taking multiple arguments into a sequence of functions each taking a
+ * single argument.
+ *
+ * @tparam F The type of the callable object to be curried
+ * @tparam BoundArgs The types of the arguments already bound to the function
+ *
+ * This class stores a function and already bound arguments, and provides
+ * operator() to either:
+ * 1. Invoke the function if enough arguments are provided
+ * 2. Return a new curried object with additional arguments bound
+ */
+template <typename F, typename... BoundArgs>
+class curried {
+  F func;                          ///< The callable object to be curried
+  std::tuple<BoundArgs...> bound;  ///< Tuple of already bound arguments
+
+  /**
+   * @brief Helper function to invoke the stored function with bound and new
+   * arguments
+   *
+   * @tparam Args Types of additional arguments
+   * @tparam Is Index sequence for unpacking the bound arguments tuple
+   * @param f The callable object (forwarded)
+   * @param tup Tuple of bound arguments
+   * @param seq Index sequence for tuple unpacking
+   * @param args Additional arguments to pass to the function
+   * @return Result of invoking the function with all arguments
+   *
+   * @note This is noexcept when the function invocation is noexcept
+   */
+  template <typename... Args, std::size_t... Is>
+  static constexpr decltype(auto) invoke_impl(
+      F&& f, std::tuple<BoundArgs...>& tup, std::index_sequence<Is...>,
+      Args&&... args) noexcept(std::is_nothrow_invocable_v<F, BoundArgs...,
+                                                           Args...>) {
+    return std::invoke(std::forward<F>(f), std::get<Is>(tup)...,
+                       std::forward<Args>(args)...);
+  }
+
+ public:
+  /**
+   * @brief Construct a new curried object
+   *
+   * @param f The callable object to curry
+   * @param args Initial arguments to bind
+   *
+   * @note Constructor is noexcept if both F and all BoundArgs are nothrow
+   * move-constructible
+   */
+  constexpr explicit curried(F f, BoundArgs... args) noexcept(
+      std::is_nothrow_move_constructible_v<F> &&
+      (std::is_nothrow_move_constructible_v<BoundArgs> && ...))
+      : func(std::move(f)), bound(std::make_tuple(std::move(args)...)) {}
+
+  /**
+   * @brief Const lvalue overload of function call operator for complete
+   * invocation
+   *
+   * @tparam Args Types of additional arguments
+   * @param args Additional arguments to pass to the function
+   * @return Result of function invocation
+   *
+   * @note This overload is only available when the function can be invoked with
+   * the current bound arguments and provided arguments
+   */
+  template <typename... Args>
+  constexpr decltype(auto) operator()(Args&&... args) const&
+    requires std::is_invocable_v<const F&, const BoundArgs&..., Args...>
+  {
+    return invoke_impl(func, const_cast<std::tuple<BoundArgs...>&>(bound),
+                       std::index_sequence_for<BoundArgs...>{},
+                       std::forward<Args>(args)...);
+  }
+
+  /**
+   * @brief Rvalue overload of function call operator for complete invocation
+   *
+   * @tparam Args Types of additional arguments
+   * @param args Additional arguments to pass to the function
+   * @return Result of function invocation
+   *
+   * @note This overload is only available when the function can be invoked with
+   * the current bound arguments and provided arguments
+   */
+  template <typename... Args>
+  constexpr decltype(auto) operator()(Args&&... args) &&
+    requires std::is_invocable_v<F, BoundArgs..., Args...>
+  {
+    return invoke_impl(std::move(func), bound,
+                       std::index_sequence_for<BoundArgs...>{},
+                       std::forward<Args>(args)...);
+  }
+
+  /**
+   * @brief Const lvalue overload of function call operator for partial
+   * application
+   *
+   * @tparam Args Types of additional arguments
+   * @param args Additional arguments to bind
+   * @return A new curried object with additional arguments bound
+   *
+   * @note This overload is only available when the function cannot yet be
+   * invoked with the current bound arguments and provided arguments
+   */
+  template <typename... Args>
+  constexpr auto operator()(Args&&... args) const&
+    requires(!std::is_invocable_v<const F&, const BoundArgs&..., Args...>)
+  {
+    return curried<F, BoundArgs..., std::decay_t<Args>...>(
+        func, std::get<BoundArgs>(bound)..., std::forward<Args>(args)...);
+  }
+
+  /**
+   * @brief Rvalue overload of function call operator for partial application
+   *
+   * @tparam Args Types of additional arguments
+   * @param args Additional arguments to bind
+   * @return A new curried object with additional arguments bound
+   *
+   * @note This overload is only available when the function cannot yet be
+   * invoked with the current bound arguments and provided arguments
+   */
+  template <typename... Args>
+      constexpr auto operator()(Args&&... args) &&
+      requires(!std::is_invocable_v<F, BoundArgs..., Args...>) {
+        return curried<F, BoundArgs..., std::decay_t<Args>...>(
+            std::move(func), std::move(std::get<BoundArgs>(bound))...,
+            std::forward<Args>(args)...);
+      }
+
+      /**
+       * @brief Const lvalue overload of zero-argument function call operator
+       * @return Result of function invocation with just the bound arguments
+       *
+       * @note This overload is only available when the function can be invoked
+       * with just the bound arguments
+       */
+      constexpr decltype(auto) operator()() const&
+        requires std::is_invocable_v<const F&, const BoundArgs&...>
+  {
+    return invoke_impl(func, const_cast<std::tuple<BoundArgs...>&>(bound),
+                       std::index_sequence_for<BoundArgs...>{});
+  }
+
+  /**
+   * @brief Rvalue overload of zero-argument function call operator
+   * @return Result of function invocation with just the bound arguments
+   *
+   * @note This overload is only available when the function can be invoked with
+   * just the bound arguments
+   */
+  constexpr decltype(auto) operator()() &&
+    requires std::is_invocable_v<F, BoundArgs...>
+  {
+    return invoke_impl(std::move(func), bound,
+                       std::index_sequence_for<BoundArgs...>{});
+  }
+};
+
+/**
+ * @brief Creates a curried function object with no initially bound arguments
+ *
+ * @tparam F Type of the callable object
+ * @param f The callable object to curry
+ * @return A curried wrapper around f
+ *
+ * @note This is noexcept if constructing the curried wrapper is noexcept
+ */
+template <typename F>
+constexpr auto curry(F&& f) noexcept(
+    std::is_nothrow_constructible_v<std::decay_t<F>, F>) {
+  return curried<std::decay_t<F>>(std::forward<F>(f));
+}
+
+/**
+ * @brief Creates a curried function object with initially bound arguments
+ *
+ * @tparam F Type of the callable object
+ * @tparam Args Types of the arguments to bind initially
+ * @param f The callable object to curry
+ * @param args Arguments to bind initially
+ * @return A curried wrapper around f with args bound
+ *
+ * @note This is noexcept if constructing the curried wrapper with arguments is
+ * noexcept
+ * @note The returned object is marked [[nodiscard]] to prevent accidental
+ * discarding
+ */
+[[nodiscard]] template <typename F, typename... Args>
+constexpr auto curry(F&& f, Args&&... args) noexcept(
+    noexcept(curried<std::decay_t<F>, std::decay_t<Args>...>(
+        std::forward<F>(f), std::forward<Args>(args)...))) {
+  return curried<std::decay_t<F>, std::decay_t<Args>...>(
+      std::forward<F>(f), std::forward<Args>(args)...);
+}
+
+}  // namespace core::meta::utils

lib/library1/include/utils/fill.hpp

@@ -1,37 +1,96 @@
+/**
+ * @file fill_utils.hpp
+ * @brief Template metaprogramming utilities for filling and assigning types
+ *
+ * This header provides utilities for creating filled sequences of types and
+ * assigning types to other type containers at compile-time.
+ */
+
 #pragma once
 
 #include "./expand.hpp"
 
 namespace core::meta::utils {
 
+/**
+ * @brief Fills a container with a type or value N times
+ * @tparam n The number of times to fill
+ * @tparam T The type or value to fill with
+ *
+ * This template creates a sequence containing the type T repeated n times.
+ * The result is adapted to match the input container type (variadic, tuple,
+ * etc).
+ */
 template <auto n, typename T>
 struct fill {
+  /**
+   * @brief Implementation helper for filling with types
+   */
   template <auto N, typename U>
   struct impl : U {};
 
+  /**
+   * @brief Applies a filler function
+   */
   template <template <auto, typename> typename F>
   using call = expand<F, T, index_sequence_of_c<n>>;
 
+  /**
+   * @brief Selects appropriate filling strategy
+   */
   using curr = type_if<!has_type_v<T> || !has_value_type_v<T>, call<identity>,
                        call<impl>>;
+
+  /**
+   * @brief The resulting filled type sequence
+   */
   using type = rename_if_t<is_variadic_type_v<T>, curr, std::tuple<>>;
 };
 
+/**
+ * @brief Helper type for fill
+ */
 template <auto n, typename T>
 using fill_t = typeof_t<fill<n, T>>;
 
+/**
+ * @brief Fills with a constant value
+ * @tparam n Number of times to fill
+ * @tparam v The constant value to fill with
+ */
 template <auto n, auto v>
 using fill_c = typeof_t<fill<n, c_<v>>>;
 
+/**
+ * @brief Assigns a type to fill another type's container
+ * @tparam T The target type to assign to
+ * @tparam U The type to fill with
+ *
+ * Creates a new container of the same type as T but filled with U
+ */
 template <typename T, typename U>
 struct assign : rename<fill_t<sizeof_t_v<T>, U>, clear_t<T>> {};
 
+/**
+ * @brief Helper type for assign
+ */
 template <typename T, typename U>
 using assign_t = typeof_t<assign<T, U>>;
 
+/**
+ * @brief Creates a nested fill structure
+ * @tparam N The nesting depth
+ * @tparam T The template to nest
+ *
+ * Creates a recursively nested structure of the template T, N levels deep
+ */
 template <auto N, template <typename...> typename T>
 struct nest_fill : to_nest<fill_t<N, T<>>> {};
 
+/**
+ * @brief Helper type for nest_fill
+ */
 template <auto N, template <typename...> typename T>
 using nest_fill_t = typeof_t<nest_fill<N, T>>;
+
 }  // namespace core::meta::utils