Adding suggestions from @ferdymercury

Author: edfink234

math/vecops/inc/ROOT/RVec.hxx

@@ -3243,11 +3243,14 @@ RVec<typename RVec<T>::size_type> Enumerate(const RVec<T> &v)
 }
 
 /**
- * \brief Produce RVec with N evenly-spaced entries from start to end inclusive.
+ * \brief Produce RVec with N evenly-spaced entries from start to end.
  *
- * This function generates a vector of evenly spaced values, starting at \p start and ending at \p end,
- * with exactly \p n elements. The spacing is computed as
- * \f$\text{step} = \frac{\text{end} - \text{start}}{n-1}\f$, so that the vector includes both endpoints.
+ * This function generates a vector of evenly spaced values, starting at \p start and (depending on the
+ * \p endpoint parameter) either including or excluding \p end. If \p endpoint is true (default),
+ * the vector contains \p n values with \p end as the final element, and the spacing is computed as
+ * \f$\text{step} = \frac{\text{end} - \text{start}}{n-1}\f$. If \p endpoint is false,
+ * the sequence consists of n values computed as if there were n+1 evenly spaced samples, with the final
+ * value (\p end) omitted; in this case, \f$\text{step} = \frac{\text{end} - \text{start}}{n}\f$.
  *
  * The function is templated to allow for different arithmetic types. The deduced type \c Common_t is
  * determined as follows: if the common type of \p T1 and \p T2 is a floating point type, that type is used;
@@ -3259,17 +3262,28 @@ RVec<typename RVec<T>::size_type> Enumerate(const RVec<T> &v)
  * floating point type, or double otherwise.
  *
  * \param start The first value in the sequence.
- * \param end The last value in the sequence.
- * \param n The number of evenly spaced entries to produce (must be greater than 0).
+ * \param end The last value in the sequence if \p endpoint is true; otherwise, \p end is excluded.
+ * \param n The number of evenly spaced entries to produce.
+ * \param endpoint If true (default), \p end is included as the final element; if false, \p end is excluded.
  *
- * \return A vector (RVec<Common_t>) containing \p n evenly spaced values from \p start to \p end inclusive.
+ * \return A vector (RVec<Common_t>) containing \p n evenly spaced values.
  *
  * \note If \p n is 1, the resulting vector will contain only the value \p start.
  * \note The check `if (!n || (n > std::numeric_limits<long long>::max()))` is used to ensure that:
  *   - n is nonzero, and
  *   - n does not exceed std::numeric_limits<long long>::max(), which would indicate that a negative range (or other arithmetic issue)
  *     has resulted in an extremely large unsigned value, thereby preventing an attempt to reserve an absurd
  *     amount of memory.
+ * \note If the template parameter \c Common_t is explicitly overridden with an integral type, the arithmetic may cause rounding issues. Consequently, the resulting sequence may not end exactly at \p end. To ensure that the sequence ends exactly at \p end, consider casting the result as follows: `RVec<integral_type>(Linspace(...))`. This behavior is different than NumPy in Python.
+ *
+ * \par C++23 Enumerate Support:
+ * With C++23, you can use the range-based enumerate view to iterate over the resulting vector with both the index
+ * and the value, similar to Python's `enumerate`. For example:
+ * ~~~{.cpp}
+ * for (auto const [index, val] : std::views::enumerate(ROOT::VecOps::Linspace(6, 10, 16))) {
+ *     // Process index and val.
+ * }
+ * ~~~
  *
  * \par Example code, at the ROOT prompt:
  * ~~~{.cpp}
@@ -3278,12 +3292,14 @@ RVec<typename RVec<T>::size_type> Enumerate(const RVec<T> &v)
  * // { -1, 0.5, 2, 3.5, 5 }
  * cout << Linspace(3, 12, 5) << "\n";
  * // { 3, 5.25, 7.5, 9.75, 12 }
- * cout << Linspace(1.4, 13.66, 5) << "\n";
- * // { 1.4, 4.465, 7.53, 10.595, 13.66 }
+ * cout << Linspace(3, 12, 5, false) << "\n";
+ * // { 3, 4.8, 6.6, 8.4, 10.2 }
+ * Linspace<int, int, int>(1, 10, 3) << "\n";
+ * // { 1, 5, 9 }
  * ~~~
  */
 template <typename T1 = double, typename T2 = double, typename Common_t = std::conditional_t<std::is_floating_point_v<std::common_type_t<T1, T2>>, std::common_type_t<T1, T2>, double>>
-inline RVec<Common_t> Linspace(T1 start, T2 end, unsigned long long n = 128)
+inline RVec<Common_t> Linspace(T1 start, T2 end, unsigned long long n = 128, const bool endpoint = true)
 {
     RVec<Common_t> temp;
 
@@ -3292,7 +3308,7 @@ inline RVec<Common_t> Linspace(T1 start, T2 end, unsigned long long n = 128)
         return temp;
     }
 
-    Common_t step = (static_cast<Common_t>(end) - static_cast<Common_t>(start)) / static_cast<Common_t>(n - 1);
+    Common_t step = (static_cast<Common_t>(end) - static_cast<Common_t>(start)) / static_cast<Common_t>(n - endpoint);
     temp.reserve(n);
     temp.push_back(static_cast<Common_t>(start));
     for (unsigned long long i = 1; i < n; i++)
@@ -3303,38 +3319,46 @@ inline RVec<Common_t> Linspace(T1 start, T2 end, unsigned long long n = 128)
 }
 
 /**
- * \brief Produce RVec with n log-spaced entries from base^{start} to base^{end} inclusive.
+ * \brief Produce RVec with n log-spaced entries from base^{start} to base^{end}.
  *
- * This function generates a vector of values where the exponents are evenly spaced,
- * and then returns the corresponding values of base raised to these exponents.
- * More specifically, it creates a vector with n entries where the first element is
- * \f$base^{start}\f$ and the last element is \f$base^{end}\f$, with the intermediate
- * values computed such that the exponents are evenly spaced between start and end.
+ * This function generates a vector of values where the exponents are evenly spaced, and then returns the
+ * corresponding values of base raised to these exponents. If \p endpoint is true (default), the vector
+ * contains \p n values with the last element equal to \f$base^{end}\f$. If \p endpoint is false, the
+ * sequence is computed as if there were n+1 evenly spaced samples over the interval in the exponent space,
+ * and the final value (\f$base^{end}\f$) is excluded, resulting in a sequence of n values.
  *
- * The function is templated to allow for different arithmetic types. The deduced type
- * \c Common_t is determined as follows: if the common type of \p T1, \p T2, and \p T3 is a
- * floating point type, that type is used; otherwise, the arithmetic is performed using \c double.
+ * The function is templated to allow for different arithmetic types. The deduced type \c Common_t is determined as follows:
+ * if the common type of \p T1, \p T2, and \p T3 is a floating point type, that type is used; otherwise, the arithmetic is performed using \c double.
  *
  * \tparam T1 Type of the start exponent. Default is double.
  * \tparam T2 Type of the end exponent. Default is double.
  * \tparam T3 Type of the base (and auxiliary type for deducing common type). Default is double.
- * \tparam Common_t Deduced type used for arithmetic, which is
- * std::common_type_t<T1, T2, T3> if that is a floating point type, or double otherwise.
+ * \tparam Common_t Deduced type used for arithmetic, which is std::common_type_t<T1, T2, T3> if that is a floating point type, or double otherwise.
  *
- * \param start The exponent corresponding to the first element (\f$base^{start}\f$).
- * \param end The exponent corresponding to the last element (\f$base^{end}\f$).
+ * \param start The exponent corresponding to the first element (i.e., the first element is \f$base^{start}\f$).
+ * \param end The exponent corresponding to the final element if \p endpoint is true; otherwise, \p end is excluded.
  * \param n The number of log-spaced entries to produce.
  * \param base The base to be used in the exponentiation (default is 10.0).
+ * \param endpoint If true (default), \f$base^{end}\f$ is included as the final element; if false, \f$base^{end}\f$ is excluded.
  *
- * \return A vector (RVec<Common_t>) containing n values, where the i-th element is
- * computed as \f$base^{(start + i \cdot \text{step})}\f$, with \f$\text{step} = \frac{end - start}{n - 1}\f$.
+ * \return A vector (RVec<Common_t>) containing n log-spaced values.
  *
  * \note If \p n is 1, the resulting vector will contain only the value \f$base^{start}\f$.
  * \note The check `if (!n || (n > std::numeric_limits<long long>::max()))` is used to ensure that:
  *   - n is nonzero, and
  *   - n does not exceed std::numeric_limits<long long>::max(), which would indicate that a negative range (or other arithmetic issue)
  *     has resulted in an extremely large unsigned value, thereby preventing an attempt to reserve an absurd
  *     amount of memory.
+ * \note If the template parameter \c Common_t is explicitly overridden with an integral type, the arithmetic may introduce rounding errors, and as a consequence, the sequence may not end exactly at \f$base^{end}\f>. To ensure that the final element is exactly \f$base^{end}\f>, consider casting the result as follows: `RVec<integral_type>(Logspace(...))`. This behavior is different than NumPy in Python.
+ *
+ * \par C++23 Enumerate Support:
+ * With C++23, you can use the range-based enumerate view to iterate over the resulting vector with both the index
+ * and the value, similar to Python's `enumerate`. For example:
+ * ~~~{.cpp}
+ * for (auto const [index, val] : std::views::enumerate(ROOT::VecOps::Logspace(4, 10, 12))) {
+ *     // Process index and val.
+ * }
+ * ~~~
  *
  * \par Example code, at the ROOT prompt:
  * ~~~{.cpp}
@@ -3345,10 +3369,14 @@ inline RVec<Common_t> Linspace(T1 start, T2 end, unsigned long long n = 128)
  * // { 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 }
  * cout << Logspace(0, 0, 0) << '\n';
  * // {  }
+ * cout << Logspace(4, 10, 12, 10.0, false) << '\n';
+ * // { 10000, 31622.8, 100000, 316228, 1e+06, 3.16228e+06, 1e+07, 3.16228e+07, 1e+08, 3.16228e+08, 1e+09, 3.16228e+09 }
+ * cout << Logspace<int, int, int, int>(1, 5, 3) << '\n';
+ * // { 10, 1000, 100000 }
  * ~~~
  */
 template <typename T1 = double, typename T2 = double, typename T3 = double, typename Common_t = std::conditional_t<std::is_floating_point_v<std::common_type_t<T1, T2, T3>>, std::common_type_t<T1, T2, T3>, double>>
-inline RVec<Common_t> Logspace(T1 start, T2 end, unsigned long long n = 128, T3 base = 10.0)
+inline RVec<Common_t> Logspace(T1 start, T2 end, unsigned long long n = 128, T3 base = 10.0, const bool endpoint = true)
 {
     RVec<Common_t> temp;
 
@@ -3360,7 +3388,7 @@ inline RVec<Common_t> Logspace(T1 start, T2 end, unsigned long long n = 128, T3
     Common_t start_c = static_cast<Common_t>(start);
     Common_t end_c   = static_cast<Common_t>(end);
     Common_t base_c  = static_cast<Common_t>(base);
-    Common_t step = static_cast<Common_t>(end_c-start_c)/static_cast<Common_t>(n-1);
+    Common_t step = static_cast<Common_t>(end_c - start_c)/static_cast<Common_t>(n - endpoint);
     temp.reserve(n);
     temp.push_back(static_cast<Common_t>(std::pow(base_c, start_c)));
     for (unsigned long long i = 1; i < n; i++)
@@ -3404,6 +3432,16 @@ inline RVec<Common_t> Logspace(T1 start, T2 end, unsigned long long n = 128, T3
  *   - n does not exceed std::numeric_limits<long long>::max(), which would indicate that a negative range (or other arithmetic issue)
  *     has resulted in an extremely large unsigned value, thereby preventing an attempt to reserve an absurd
  *     amount of memory.
+ * \note If the template parameter \c Common_t is explicitly overridden with an integral type, the arithmetic may introduce rounding errors, and as a consequence, the produced sequence may not strictly adhere to the intended progression. If an exact sequence is desired, consider casting the result as follows: `RVec<integral_type>(Arange(...))`. This behavior is different than NumPy in Python.
+ *
+ * \par C++23 Enumerate Support:
+ * With C++23, you can use the range-based enumerate view to iterate over the resulting vector with both the index
+ * and the value, similar to Python's `enumerate`. For example:
+ * ~~~{.cpp}
+ * for (auto const [index, val] : std::views::enumerate(ROOT::VecOps::Arange(1, 13, 5))) {
+ *     // Process index and val.
+ * }
+ * ~~~
  *
  * \par Example code, at the ROOT prompt:
  * ~~~{.cpp}
@@ -3414,6 +3452,8 @@ inline RVec<Common_t> Logspace(T1 start, T2 end, unsigned long long n = 128, T3
  * // { -7, -3, 1, 5, 9, 13, 17 }
  * cout << Arange(1, 13, 5) << '\n';
  * // { 1, 6, 11 }
+ * cout << Arange<unsigned int, unsigned int, unsigned int, unsigned int>(5, 9, 1) << '\n';
+ * // { 5, 6, 7, 8 }
  * ~~~
  */
 template <typename T1 = double, typename T2 = double, typename T3 = double, typename Common_t = std::conditional_t<std::is_floating_point_v<std::common_type_t<T1, T2, T3>>, std::common_type_t<T1, T2, T3>, double>>