Feat: Round (#313)

* feat: round

* add more constraints for round

* overload round for quantity

* fix clang tidy

* Validate types before return

src/core/include/units/math.h

@@ -164,8 +164,9 @@ template<Unit To, typename D, typename U, typename Rep>
     })
 {
   const auto handle_signed_results = [&]<typename T>(const T& res) {
-    if (res > q)
+    if (res > q) {
       return res - T::one();
+    }
     return res;
   };
   if constexpr(treat_as_floating_point<Rep>) {
@@ -193,13 +194,9 @@ template<Unit To, typename D, typename U, typename Rep>
  * @tparam q Quantity being the base of the operation
  * @return Quantity The rounded quantity with unit type of quantity To
  */
-template<Quantity To, typename D, typename U, typename Rep>
+template<Quantity To, std::same_as<typename To::dimension> D, typename U, std::same_as<typename To::rep> Rep>
 [[nodiscard]] constexpr quantity<D, typename To::unit, Rep> floor(const quantity<D, U, Rep>& q) noexcept
-  requires std::same_as<typename To::dimension, D> &&
+  requires requires { ::units::floor<typename To::unit>(q); }
-    std::same_as<typename To::rep, Rep> &&
-    requires {
-      ::units::floor<typename To::unit>(q);
-    }
 {
   return ::units::floor<typename To::unit>(q);
 }
@@ -221,8 +218,9 @@ template<Unit To, typename D, typename U, typename Rep>
     })
 {
   const auto handle_signed_results = [&]<typename T>(const T& res) {
-    if (res < q)
+    if (res < q) {
       return res + T::one();
+    }
     return res;
   };
   if constexpr(treat_as_floating_point<Rep>) {
@@ -250,15 +248,69 @@ template<Unit To, typename D, typename U, typename Rep>
  * @tparam q Quantity being the base of the operation
  * @return Quantity The rounded quantity with unit type of quantity To
  */
-template<Quantity To, typename D, typename U, typename Rep>
+template<Quantity To, std::same_as<typename To::dimension> D, typename U, std::same_as<typename To::rep> Rep>
 [[nodiscard]] constexpr quantity<D, typename To::unit, Rep> ceil(const quantity<D, U, Rep>& q) noexcept
-  requires std::same_as<typename To::dimension, D> &&
+  requires requires { ::units::ceil<typename To::unit>(q); }
-    std::same_as<typename To::rep, Rep> &&
-    requires {
-      ::units::ceil<typename To::unit>(q);
-    }
 {
   return ::units::ceil<typename To::unit>(q);
 }
 
+/**
+ * @brief Computes the nearest quantity with integer representation and unit type To to q
+ *
+ * Rounding halfway cases away from zero, regardless of the current rounding mode.
+ *
+ * @tparam q Quantity being the base of the operation
+ * @return Quantity The rounded quantity with unit type To
+ */
+template<Unit To, typename D, typename U, typename Rep>
+[[nodiscard]] constexpr quantity<D, To, Rep> round(const quantity<D, U, Rep>& q) noexcept
+  requires ((!treat_as_floating_point<Rep>) ||
+    requires { round(q.number()); } ||
+    requires { std::round(q.number()); }) &&
+    (std::same_as<To, U> || requires {
+      ::units::floor<To>(q);
+      quantity<D, To, Rep>::one();
+    })
+{
+  if constexpr(std::is_same_v<To, U>) {
+    if constexpr(treat_as_floating_point<Rep>) {
+      using std::round;
+      return quantity<D, To, Rep>(round(q.number()));
+    }
+    else {
+      return q;
+    }
+  }
+  else {
+    const auto res_low = units::floor<To>(q);
+    const auto res_high = res_low + decltype(res_low)::one();
+    const auto diff0 = q - res_low;
+    const auto diff1 = res_high - q;
+    if (diff0 == diff1) {
+      if (static_cast<int>(res_low.number()) & 1) {
+        return res_high;
+      }
+      return res_low;
+    }
+    if (diff0 < diff1) {
+      return res_low;
+    }
+    return res_high;
+  }
+}
+
+/**
+ * @brief Overload of @c ::units::round<Unit>() using the unit type of To
+ *
+ * @tparam q Quantity being the base of the operation
+ * @return Quantity The rounded quantity with unit type of quantity To
+ */
+template<Quantity To, std::same_as<typename To::dimension> D, typename U, std::same_as<typename To::rep> Rep>
+[[nodiscard]] constexpr quantity<D, typename To::unit, Rep> round(const quantity<D, U, Rep>& q) noexcept
+  requires requires { ::units::round<typename To::unit>(q); }
+{
+  return ::units::round<typename To::unit>(q);
+}
+
 }  // namespace units

test/unit_test/runtime/math_test.cpp

@@ -199,6 +199,77 @@ TEST_CASE("ceil functions", "[ceil]")
   }
 }
 
+TEST_CASE("round functions", "[round]")
+{
+  SECTION ("round 1 second with target unit second should be 1 second") {
+    REQUIRE(round<si::second>(1_q_s) == 1_q_s);
+  }
+  SECTION ("round 1000 milliseconds with target unit second should be 1 second") {
+    REQUIRE(round<si::second>(1000_q_ms) == 1_q_s);
+  }
+  SECTION ("round 1001 milliseconds with target unit second should be 1 second") {
+    REQUIRE(round<si::second>(1001_q_ms) == 1_q_s);
+  }
+  SECTION ("round 1499 milliseconds with target unit second should be 1 second") {
+    REQUIRE(round<si::second>(1499_q_ms) == 1_q_s);
+  }
+  SECTION ("round 1500 milliseconds with target unit second should be 2 seconds") {
+    REQUIRE(round<si::second>(1500_q_ms) == 2_q_s);
+  }
+  SECTION ("round 1999 milliseconds with target unit second should be 2 seconds") {
+    REQUIRE(round<si::second>(1999_q_ms) == 2_q_s);
+  }
+  SECTION ("round -1000 milliseconds with target unit second should be -1 second") {
+    REQUIRE(round<si::second>(-1000_q_ms) == -1_q_s);
+  }
+  SECTION ("round -1001 milliseconds with target unit second should be -1 second") {
+    REQUIRE(round<si::second>(-1001_q_ms) == -1_q_s);
+  }
+  SECTION ("round -1499 milliseconds with target unit second should be -1 second") {
+    REQUIRE(round<si::second>(-1499_q_ms) == -1_q_s);
+  }
+  SECTION ("round -1500 milliseconds with target unit second should be -2 seconds") {
+    REQUIRE(round<si::second>(-1500_q_ms) == -2_q_s);
+  }
+  SECTION ("round -1999 milliseconds with target unit second should be -2 seconds") {
+    REQUIRE(round<si::second>(-1999_q_ms) == -2_q_s);
+  }
+  SECTION ("round 1000. milliseconds with target unit second should be 1 second") {
+    REQUIRE(round<si::second>(1000._q_ms) == 1_q_s);
+  }
+  SECTION ("round 1001. milliseconds with target unit second should be 1 second") {
+    REQUIRE(round<si::second>(1001._q_ms) == 1_q_s);
+  }
+  SECTION ("round 1499. milliseconds with target unit second should be 1 second") {
+    REQUIRE(round<si::second>(1499._q_ms) == 1_q_s);
+  }
+  SECTION ("round 1500. milliseconds with target unit second should be 2 seconds") {
+    REQUIRE(round<si::second>(1500._q_ms) == 2_q_s);
+  }
+  SECTION ("round 1999. milliseconds with target unit second should be 2 seconds") {
+    REQUIRE(round<si::second>(1999._q_ms) == 2_q_s);
+  }
+  SECTION ("round -1000. milliseconds with target unit second should be -1 second") {
+    REQUIRE(round<si::second>(-1000._q_ms) == -1_q_s);
+  }
+  SECTION ("round -1001. milliseconds with target unit second should be -1 second") {
+    REQUIRE(round<si::second>(-1001._q_ms) == -1_q_s);
+  }
+  SECTION ("round -1499. milliseconds with target unit second should be -1 second") {
+    REQUIRE(round<si::second>(-1499._q_ms) == -1_q_s);
+  }
+  SECTION ("round -1500. milliseconds with target unit second should be -2 seconds") {
+    REQUIRE(round<si::second>(-1500._q_ms) == -2_q_s);
+  }
+  SECTION ("round -1999. milliseconds with target unit second should be -2 seconds") {
+    REQUIRE(round<si::second>(-1999._q_ms) == -2_q_s);
+  }
+  SECTION ("round 1 second with target quantity with unit type second should be 1 second") {
+    using showtime = si::time<si::second, int>;
+    REQUIRE(round<showtime>(showtime::one()) == showtime::one());
+  }
+}
+
 TEMPLATE_TEST_CASE_SIG("pow<N>() implementation exponentiates values to power N", "[math][pow][exp]",
                        (std::intmax_t N, N), 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25)
 {

test/unit_test/static/math_test.cpp

@@ -57,7 +57,7 @@ static_assert(compare<decltype(pow<1, 4>(4_q_m2)), decltype(sqrt(2_q_m))>);
 static_assert(compare<decltype(pow<1, 4>(4_q_km2)), decltype(sqrt(2_q_km))>);
 static_assert(compare<decltype(pow<1, 4>(4_q_ft2)), decltype(sqrt(2_q_ft))>);
 
-#if __cpp_lib_constexpr_cmath  // TODO remove once std::floor is constexpr for all compilers
+#if __cpp_lib_constexpr_cmath  // TODO remove once std::floor, std::ceil, and std::round is constexpr for all compilers
 // floor
 // integral types
 static_assert(compare<decltype(floor<si::second>(1_q_s)), decltype(1_q_s)>);
@@ -103,6 +103,41 @@ static_assert(ceil<si::second>(-999._q_ms) == 0_q_s);
 
 // ceil with quantity
 static_assert(compare<decltype(ceil<si::time<si::second>>(1_q_s)), decltype(1_q_s)>);
+
+// round
+// integral types
+static_assert(compare<decltype(round<si::second>(1_q_s)), decltype(1_q_s)>);
+
+static_assert(compare<decltype(round<si::second>(1000_q_ms)), decltype(1_q_s)>);
+static_assert(compare<decltype(round<si::second>(1001_q_ms)), decltype(1_q_s)>);
+static_assert(compare<decltype(round<si::second>(1499_q_ms)), decltype(1_q_s)>);
+static_assert(compare<decltype(round<si::second>(1500_q_ms)), decltype(2_q_s)>);
+static_assert(compare<decltype(round<si::second>(1999_q_ms)), decltype(2_q_s)>);
+
+static_assert(compare<decltype(round<si::second>(-1000_q_ms)), decltype(-1_q_s)>);
+static_assert(compare<decltype(round<si::second>(-1001_q_ms)), decltype(-1_q_s)>);
+static_assert(compare<decltype(round<si::second>(-1499_q_ms)), decltype(-1_q_s)>);
+static_assert(compare<decltype(round<si::second>(-1500_q_ms)), decltype(-2_q_s)>);
+static_assert(compare<decltype(round<si::second>(-1999_q_ms)), decltype(-2_q_s)>);
+
+// floating-point
+static_assert(round<si::second>(1.3_q_s) == 1_q_s);
+static_assert(round<si::second>(-1.3_q_s) == -1_q_s);
+
+static_assert(compare<decltype(round<si::second>(1000._q_ms)), decltype(1_q_s)>);
+static_assert(compare<decltype(round<si::second>(1001._q_ms)), decltype(1_q_s)>);
+static_assert(compare<decltype(round<si::second>(1499._q_ms)), decltype(1_q_s)>);
+static_assert(compare<decltype(round<si::second>(1500._q_ms)), decltype(2_q_s)>);
+static_assert(compare<decltype(round<si::second>(1999._q_ms)), decltype(2_q_s)>);
+
+static_assert(compare<decltype(round<si::second>(-1000._q_ms)), decltype(-1_q_s)>);
+static_assert(compare<decltype(round<si::second>(-1001._q_ms)), decltype(-1_q_s)>);
+static_assert(compare<decltype(round<si::second>(-1499._q_ms)), decltype(-1_q_s)>);
+static_assert(compare<decltype(round<si::second>(-1500._q_ms)), decltype(-2_q_s)>);
+static_assert(compare<decltype(round<si::second>(-1999._q_ms)), decltype(-2_q_s)>);
+
+// round with quantity
+static_assert(compare<decltype(round<si::time<si::second>>(1_q_s)), decltype(1_q_s)>);
 #endif
 
 }  // namespace