util docs

Author: SpectraL519

include/gl/util/math.hpp

@@ -2,6 +2,9 @@
 // This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/// @file gl/util/math.hpp
+/// @brief Defines utility mathematical functions.
+
 #pragma once
 
 #include "gl/types/core.hpp"
@@ -11,7 +14,15 @@
 
 namespace gl::util {
 
-// exponentation function for u64 integral type
+/// @ingroup GL GL-Util
+/// @brief Computes the value of `base` raised to the power of `exp` using exponentiation by squaring.
+/// @param base The base value to be raised to a power.
+/// @param exp The exponent to which the base is raised.
+/// @return The result of `base` raised to the power of `exp`.
+///
+/// > [!INFO] Time complexity
+/// >
+/// > $O(\log(\text{exp}))$ due to halving the exponent at each step.
 [[nodiscard]] inline constexpr size_type upow(size_type base, size_type exp) {
     size_type result = 1uz;
     while (exp) {
@@ -24,8 +35,19 @@ namespace gl::util {
     return result;
 }
 
-// sum of exponents: base ^ i_begin + base ^ (i_begin + 1) + ... + base ^ (i_end)
-[[nodiscard]] inline size_type upow_sum(const size_type base, size_type i_begin, size_type i_end) {
+/// @ingroup GL GL-Util
+/// @brief Computes the sum of powers of `base` from `base^i_begin` to `base^i_end` inclusive.
+/// @param base The base value for the powers.
+/// @param i_begin The starting exponent (inclusive).
+/// @param i_end The ending exponent (inclusive).
+/// @return The sum of `base^i` for all `i` in the range `[i_begin, i_end]`.
+///
+/// > [!INFO] Time complexity
+/// >
+/// > $O(\log(\text{max}(\text{i\_begin}, \text{i\_end})))$ due to the use of the closed-form formula for geometric series.
+[[nodiscard]] inline constexpr size_type upow_sum(
+    const size_type base, size_type i_begin, size_type i_end
+) {
     std::tie(i_begin, i_end) = std::minmax(i_begin, i_end);
 
     if (base == 0uz)

include/gl/util/ranges.hpp

@@ -2,13 +2,32 @@
 // This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/// @file gl/util/ranges.hpp
+/// @brief Defines utility functions and views for working with C++20 ranges.
+
 #pragma once
 
 #include <algorithm>
 #include <ranges>
 
 namespace gl::util {
 
+/// @ingroup GL GL-Util
+/// @brief Returns the size of a range.
+///
+/// This function returns the size of a range if it is a sized range, otherwise it computes the
+/// distance between the beginning and end of the range. Note that computing the distance for
+/// non-sized ranges may be expensive.
+///
+/// > [!WARNING] This function will consume input ranges that are not sized, as it needs to iterate through them to count the elements.
+///
+/// @tparam R The type of the range.
+/// @param r The range to measure.
+/// @return The size of the range if it is a sized range, otherwise the distance between the beginning and end of the range.
+///
+/// > [!INFO] Time complexity
+/// >
+/// > $O(1)$ if the range is a sized range, otherwise $O(N)$ where $N$ is the number of elements in the range.
 template <std::ranges::range R>
 constexpr auto range_size(R&& r) {
     if constexpr (std::ranges::sized_range<R>)
@@ -18,6 +37,15 @@ constexpr auto range_size(R&& r) {
         return std::ranges::distance(std::begin(r), std::end(r));
 }
 
+/// @ingroup GL GL-Util
+/// @brief Checks if all elements in a range are equal.
+/// @tparam R The type of the range.
+/// @param range The range to check.
+/// @return `true` if all elements in the range are equal or the range is empty, otherwise `false`.
+///
+/// > [!INFO] Time complexity
+/// >
+/// > $O(N)$ where $N$ is the number of elements in the range.
 template <std::ranges::forward_range R>
 [[nodiscard]] constexpr bool is_constant(R&& range) noexcept {
     if (std::ranges::empty(range))
@@ -28,31 +56,55 @@ template <std::ranges::forward_range R>
     });
 }
 
+/// @ingroup GL GL-Util
+/// @brief Checks if all elements in a range are equal to a given value.
+/// @tparam R The type of the range.
+/// @param range The range to check.
+/// @param value The value to compare against.
+/// @return `true` if all elements in the range are equal to the given value or the range is empty, otherwise `false`.
+///
+/// > [!INFO] Time complexity
+/// >
+/// > $O(N)$ where $N$ is the number of elements in the range.
 template <std::ranges::forward_range R>
-[[nodiscard]] constexpr bool all_equal(R&& range, const std::ranges::range_value_t<R>& k) noexcept {
+[[nodiscard]] constexpr bool all_equal(
+    R&& range, const std::ranges::range_value_t<R>& value
+) noexcept {
     if (std::ranges::empty(range))
         return true;
 
-    return std::ranges::all_of(range, [&k](const auto& val) { return val == k; });
+    return std::ranges::all_of(range, [&value](const auto& val) { return val == value; });
 }
 
+/// @ingroup GL GL-Util
 /// @brief A view concatenating two ranges sequentially (C++20 polyfill for C++26 `std::views::concat`).
 ///
-/// @warning **GCC 13/14 Bug:** Using branching views (like this or `std::ranges::filter_view`)
-/// inside complex algorithms (e.g., `std::ranges::is_permutation`) may trigger false-positive
-/// `-Wmaybe-uninitialized` warnings. To work around this, suppress the warning at the call site
-/// or materialize the view into a contiguous container like `std::vector`.
+/// > [!WARNING] GCC 13/14 Bug
+/// >
+/// > Using branching views (like this or `std::ranges::filter_view`) inside complex algorithms
+/// > (e.g., `std::ranges::is_permutation`) may trigger false-positive `-Wmaybe-uninitialized`
+/// > warnings. To work around this, suppress the warning at the call site or materialize the
+/// > view into a contiguous container like `std::vector`.
 ///
 /// @tparam V1 First view type.
 /// @tparam V2 Second view type.
 /// @todo Replace with `std::views::concat` (C++26).
+/// ### See also
+/// - @ref gl::util::concat_fn "concat_fn": A helper compile-time constant function object for creating `concat_view` instances.
+/// - @ref gl::util::concat "concat": A compile-time constant instantiation of this function object for convenient use.
 template <std::ranges::view V1, std::ranges::view V2>
 class concat_view : public std::ranges::view_interface<concat_view<V1, V2>> {
 public:
+    /// @brief Default constructor creates an empty concatenated view.
     concat_view() = default;
 
+    /// @brief Constructs a `concat_view` from two viewable ranges.
+    /// @param v1 The first range to concatenate.
+    /// @param v2 The second range to concatenate.
     constexpr concat_view(V1 v1, V2 v2) : _v1(std::move(v1)), _v2(std::move(v2)) {}
 
+    /// @brief Returns an iterator to the beginning of the concatenated view.
+    /// @return An iterator that traverses the first range followed by the second range.
     constexpr auto begin() {
         return iterator<false>(
             std::ranges::begin(this->_v1),
@@ -61,8 +113,10 @@ class concat_view : public std::ranges::view_interface<concat_view<V1, V2>> {
         );
     }
 
+    /// @brief Returns a const iterator to the beginning of the concatenated view.
+    /// @return A const iterator that traverses the first range followed by the second range.
     constexpr auto begin() const
-    requires std::ranges::range<const V1> and std::ranges::range<const V2>
+    requires(std::ranges::range<const V1> and std::ranges::range<const V2>)
     {
         return iterator<true>(
             std::ranges::begin(this->_v1),
@@ -71,12 +125,16 @@ class concat_view : public std::ranges::view_interface<concat_view<V1, V2>> {
         );
     }
 
+    /// @brief Returns a sentinel representing the end of the concatenated view.
+    /// @return A sentinel that compares equal to an iterator when it reaches the end of the second range.
     constexpr auto end() {
         return sentinel<false>(std::ranges::end(this->_v2));
     }
 
+    /// @brief Returns a const sentinel representing the end of the concatenated view.
+    /// @return A const sentinel that compares equal to a const iterator when it reaches the end
     constexpr auto end() const
-    requires std::ranges::range<const V1> and std::ranges::range<const V2>
+    requires(std::ranges::range<const V1> and std::ranges::range<const V2>)
     {
         return sentinel<true>(std::ranges::end(this->_v2));
     }
@@ -172,9 +230,18 @@ class concat_view : public std::ranges::view_interface<concat_view<V1, V2>> {
     };
 };
 
-namespace detail {
-
+/// @ingroup GL GL-Util
+/// @brief A function object for concatenating two viewable ranges into a `concat_view`.
+/// ### See also
+/// - @ref gl::util::concat_view "concat_view": The view type that represents the concatenation of two ranges.
+/// - @ref gl::util::concat "concat": A compile-time constant instantiation of this function object for convenient use.
 struct concat_fn {
+    /// @brief Concatenates two viewable ranges into a `concat_view`.
+    /// @tparam R1 The type of the first range.
+    /// @tparam R2 The type of the second range.
+    /// @param r1 The first range to concatenate.
+    /// @param r2 The second range to concatenate.
+    /// @return A `concat_view` that represents the concatenation of the two ranges.
     template <std::ranges::viewable_range R1, std::ranges::viewable_range R2>
     constexpr auto operator()(R1&& r1, R2&& r2) const {
         return concat_view<std::views::all_t<R1>, std::views::all_t<R2>>(
@@ -183,12 +250,24 @@ struct concat_fn {
     }
 };
 
-} // namespace detail
-
+/// @ingroup GL GL-Util
 /// @brief Concatenates two viewable ranges into a `concat_view`.
+///
+/// ### Example usage
+/// ```cpp
+/// std::vector<int> v1 = {1, 2, 3};
+/// std::vector<int> v2 = {4, 5, 6};
+/// auto concatenated = gl::util::concat(v1, v2);
+/// for (int x : concatenated)
+///     std::cout << x << " "; // Output: 1 2 3 4 5 6
+/// ```
+///
 /// @param r1 First range to concatenate.
 /// @param r2 Second range to concatenate.
 /// @todo Replace with `std::views::concat` (C++26).
-inline constexpr detail::concat_fn concat{};
+/// ### See also
+/// - @ref gl::util::concat_view "concat_view": The view type that represents the concatenation of two ranges.
+/// - @ref gl::util::concat_fn "concat_fn": A helper compile-time constant function object for creating `concat_view` instances.
+inline constexpr concat_fn concat{};
 
 } // namespace gl::util