feat: comparisons against literal 0

Resolves #487

Author: mpusz

docs/users_guide/framework_basics/quantity_arithmetics.md

@@ -293,8 +293,10 @@ if (q1 / q2 != 0 * m / s)
 ```
 
 The above would work (assuming we are dealing with the quantity of speed) but could be
-suboptimal if the result of `q1 / q2` is not expressed in `m / s`. To eliminate the need
-for conversion, we need to write:
+suboptimal if the result of `q1 / q2` is not expressed in `m / s`. The library would
+need to rescale the arguments to the common unit before comparing if the value is zero.
+
+To eliminate the need for conversion, we need to write:
 
 ```cpp
 if (auto q = q1 / q2; q != q.zero())
@@ -304,32 +306,36 @@ if (auto q = q1 / q2; q != q.zero())
 but that is a bit inconvenient, and inexperienced users could be unaware of this technique
 and its reasons.
 
-For the above reasons, the library provides dedicated interfaces to compare against zero
-that follow the naming convention of
-[named comparison functions](https://en.cppreference.com/w/cpp/utility/compare/named_comparison_functions)
-in the C++ Standard Library. The _mp-units/compare.h_ header file exposes the following functions:
-
-- `is_eq_zero`
-- `is_neq_zero`
-- `is_lt_zero`
-- `is_gt_zero`
-- `is_lteq_zero`
-- `is_gteq_zero`
+For the above reasons, the library provides special support for comparisons against the
+literal `0`. Only this one value has elevated privileges and does not have to state the
+unit — the numerical value zero is common to all scaled units of any kind.
 
-Thanks to them, to save typing and not pay for unneeded conversions, our check could be
+Thanks to that, to save typing and not pay for unneeded conversions, our check could be
 implemented as follows:
 
 ```cpp
-if (is_neq_zero(q1 / q2))
+if (q1 / q2 != 0)
+  // ...
+```
+
+This works for all six comparison operators (`==`, `!=`, `<`, `>`, `<=`, `>=`):
+
+```cpp
+if (q > 0)
+  // ...
+if (q <= 0)
   // ...
 ```
 
 !!! tip
 
-    Those functions will work with any type `T` that exposes `zero()` member function returning
-    something comparable to `T`. Thanks to that, we can use them not only with quantities but also
-    with [`std::chrono::duration`](https://en.cppreference.com/w/cpp/chrono/duration) or any other
-    type that exposes such an interface.
+    All six comparison operators support comparison against zero without specifying a unit.
+    This works with any representation type `rep` for which
+    `representation_values<rep>::zero()` is provided.
+
+    Only a compile-time zero is accepted: an integer or floating-point literal that is zero
+    (e.g., `0`, `0.`, `0.f`, `0LL`). Passing another literal or a runtime variable — even one
+    whose value happens to be zero — is rejected at compile time.
 
 
 ## Other maths

example/include/geographic.h

@@ -141,9 +141,8 @@ struct MP_UNITS_STD_FMT::formatter<geographic::latitude<T>, Char> :
   auto format(geographic::latitude<T> lat, FormatContext& ctx) const -> decltype(ctx.out())
   {
     const auto& q = lat.quantity_ref_from(geographic::equator);
-    ctx.advance_to(
-      formatter<typename geographic::latitude<T>::quantity_type, Char>::format(is_gteq_zero(q) ? q : -q, ctx));
-    return MP_UNITS_STD_FMT::format_to(ctx.out(), "{}", is_gteq_zero(q) ? " N" : "S");
+    ctx.advance_to(formatter<typename geographic::latitude<T>::quantity_type, Char>::format(q >= 0 ? q : -q, ctx));
+    return MP_UNITS_STD_FMT::format_to(ctx.out(), "{}", q >= 0 ? " N" : "S");
   }
 };
 
@@ -154,9 +153,8 @@ struct MP_UNITS_STD_FMT::formatter<geographic::longitude<T>, Char> :
   auto format(geographic::longitude<T> lon, FormatContext& ctx) const -> decltype(ctx.out())
   {
     const auto& q = lon.quantity_ref_from(geographic::prime_meridian);
-    ctx.advance_to(
-      formatter<typename geographic::longitude<T>::quantity_type, Char>::format(is_gteq_zero(q) ? q : -q, ctx));
-    return MP_UNITS_STD_FMT::format_to(ctx.out(), "{}", is_gteq_zero(q) ? " E" : " W");
+    ctx.advance_to(formatter<typename geographic::longitude<T>::quantity_type, Char>::format(q >= 0 ? q : -q, ctx));
+    return MP_UNITS_STD_FMT::format_to(ctx.out(), "{}", q >= 0 ? " E" : " W");
   }
 };
 

src/core/include/mp-units/framework/compare.h

@@ -40,7 +40,7 @@ template<typename T>
   requires requires {
     { T::zero() } -> std::equality_comparable_with<T>;
   }
-[[nodiscard]] constexpr bool is_eq_zero(T v)
+[[deprecated("2.6.0: compare against literal `0` instead")]] [[nodiscard]] constexpr bool is_eq_zero(T v)
 {
   return v == T::zero();
 }
@@ -49,7 +49,7 @@ template<typename T>
   requires requires {
     { T::zero() } -> std::equality_comparable_with<T>;
   }
-[[nodiscard]] constexpr bool is_neq_zero(T v)
+[[deprecated("2.6.0: compare against literal `0` instead")]] [[nodiscard]] constexpr bool is_neq_zero(T v)
 {
   return v != T::zero();
 }
@@ -58,7 +58,7 @@ template<typename T>
   requires requires {
     { T::zero() } -> std::three_way_comparable_with<T>;
   }
-[[nodiscard]] constexpr bool is_lt_zero(T v)
+[[deprecated("2.6.0: compare against literal `0` instead")]] [[nodiscard]] constexpr bool is_lt_zero(T v)
 {
   return v < T::zero();
 }
@@ -67,7 +67,7 @@ template<typename T>
   requires requires {
     { T::zero() } -> std::three_way_comparable_with<T>;
   }
-[[nodiscard]] constexpr bool is_gt_zero(T v)
+[[deprecated("2.6.0: compare against literal `0` instead")]] [[nodiscard]] constexpr bool is_gt_zero(T v)
 {
   return v > T::zero();
 }
@@ -76,7 +76,7 @@ template<typename T>
   requires requires {
     { T::zero() } -> std::three_way_comparable_with<T>;
   }
-[[nodiscard]] constexpr bool is_lteq_zero(T v)
+[[deprecated("2.6.0: compare against literal `0` instead")]] [[nodiscard]] constexpr bool is_lteq_zero(T v)
 {
   return v <= T::zero();
 }
@@ -85,7 +85,7 @@ template<typename T>
   requires requires {
     { T::zero() } -> std::three_way_comparable_with<T>;
   }
-[[nodiscard]] constexpr bool is_gteq_zero(T v)
+[[deprecated("2.6.0: compare against literal `0` instead")]] [[nodiscard]] constexpr bool is_gteq_zero(T v)
 {
   return v >= T::zero();
 }

src/core/include/mp-units/framework/quantity.h

@@ -48,7 +48,10 @@
 import std;
 #else
 #include <compare>  // IWYU pragma: export
+#include <concepts>
 #include <limits>
+#include <stdexcept>
+#include <type_traits>
 #include <utility>
 #if MP_UNITS_HOSTED
 #include <locale>
@@ -60,6 +63,15 @@ namespace mp_units {
 
 namespace detail {
 
+struct zero {
+  template<typename T>
+    requires std::is_arithmetic_v<T> && (!is_same_v<T, bool>)
+  consteval explicit(false) zero(T val)
+  {
+    if (val != T{0}) MP_UNITS_THROW(std::logic_error("not zero"));
+  }
+};
+
 template<Unit UFrom, Unit UTo>
 [[nodiscard]] consteval bool integral_conversion_factor(UFrom from, UTo to)
 {
@@ -467,7 +479,7 @@ class quantity {
             }
   constexpr quantity& operator%=(const quantity<R2, Rep2>& other) &
   {
-    MP_UNITS_EXPECTS_DEBUG(is_neq_zero(other));
+    MP_UNITS_EXPECTS_DEBUG(other != 0);
     if constexpr (equivalent(unit, get_unit(R2)))
       numerical_value_is_an_implementation_detail_ %= other.numerical_value_is_an_implementation_detail_;
     else
@@ -574,7 +586,7 @@ class quantity {
             detail::CommonlyInvocableQuantities<std::modulus<>, quantity, quantity<R2, Rep2>>
   [[nodiscard]] friend constexpr Quantity auto operator%(const Q& lhs, const quantity<R2, Rep2>& rhs)
   {
-    MP_UNITS_EXPECTS_DEBUG(is_neq_zero(rhs));
+    MP_UNITS_EXPECTS_DEBUG(rhs != 0);
     using ret = detail::common_quantity_for<std::modulus<>, quantity, quantity<R2, Rep2>>;
     const ret ret_lhs(lhs);
     const ret ret_rhs(rhs);
@@ -625,7 +637,7 @@ class quantity {
     requires detail::InvocableQuantities<std::divides<>, quantity, quantity<R2, Rep2>>
   [[nodiscard]] friend constexpr Quantity auto operator/(const Q& lhs, const quantity<R2, Rep2>& rhs)
   {
-    MP_UNITS_EXPECTS_DEBUG(is_neq_zero(rhs));
+    MP_UNITS_EXPECTS_DEBUG(rhs != 0);
     return ::mp_units::quantity{lhs.numerical_value_ref_in(unit) / rhs.numerical_value_ref_in(rhs.unit), R / R2};
   }
 
@@ -643,7 +655,7 @@ class quantity {
             (!Reference<Value>) && detail::InvokeResultOf<quantity_spec, std::divides<>, const Value&, rep>
   [[nodiscard]] friend constexpr Quantity auto operator/(const Value& val, const Q& q)
   {
-    MP_UNITS_EXPECTS_DEBUG(is_neq_zero(q));
+    MP_UNITS_EXPECTS_DEBUG(q != 0);
     return ::mp_units::quantity{val / q.numerical_value_ref_in(unit), one / R};
   }
 
@@ -668,6 +680,13 @@ class quantity {
     return lhs.numerical_value_ref_in(unit) == rhs;
   }
 
+  template<std::derived_from<quantity> Q>
+    requires std::equality_comparable<rep> && requires { representation_values<rep>::zero(); }
+  [[nodiscard]] friend constexpr bool operator==(const Q& lhs, detail::zero)
+  {
+    return lhs.numerical_value_ref_in(unit) == representation_values<rep>::zero();
+  }
+
   template<std::derived_from<quantity> Q, auto R2, typename Rep2>
     requires requires { typename std::common_type_t<quantity, quantity<R2, Rep2>>; } &&
              std::three_way_comparable<typename std::common_type_t<quantity, quantity<R2, Rep2>>::rep>
@@ -685,6 +704,13 @@ class quantity {
   {
     return lhs.numerical_value_ref_in(unit) <=> rhs;
   }
+
+  template<std::derived_from<quantity> Q>
+    requires std::three_way_comparable<rep> && requires { representation_values<rep>::zero(); }
+  [[nodiscard]] friend constexpr auto operator<=>(const Q& lhs, detail::zero)
+  {
+    return lhs.numerical_value_ref_in(unit) <=> representation_values<rep>::zero();
+  }
 };
 
 // CTAD

src/core/include/mp-units/framework/quantity_point.h

@@ -26,7 +26,6 @@
 #include <mp-units/bits/hacks.h>
 #include <mp-units/bits/module_macros.h>
 #include <mp-units/compat_macros.h>
-#include <mp-units/framework/compare.h>
 #include <mp-units/framework/customization_points.h>
 #include <mp-units/framework/quantity.h>
 #include <mp-units/framework/quantity_point_concepts.h>
@@ -109,9 +108,9 @@ struct point_origin_interface {
                        is_derived_from_specialization_of_v<PO2, relative_point_origin>)
       return PO1::_quantity_point_ == PO2::_quantity_point_;
     else if constexpr (is_derived_from_specialization_of_v<PO1, relative_point_origin>)
-      return detail::same_absolute_point_origins(po1, po2) && is_eq_zero(PO1::_quantity_point_.quantity_from_zero());
+      return detail::same_absolute_point_origins(po1, po2) && PO1::_quantity_point_.quantity_from_zero() == 0;
     else if constexpr (is_derived_from_specialization_of_v<PO2, relative_point_origin>)
-      return detail::same_absolute_point_origins(po1, po2) && is_eq_zero(PO2::_quantity_point_.quantity_from_zero());
+      return detail::same_absolute_point_origins(po1, po2) && PO2::_quantity_point_.quantity_from_zero() == 0;
   }
 };
 

src/systems/include/mp-units/systems/si/prefixes.h

@@ -131,7 +131,7 @@ template<Quantity Q, std::invocable<Q> Func, PrefixableUnit U, auto Character =
 constexpr decltype(auto) invoke_with_prefixed(Func func, Q q, U u, prefix_range range = prefix_range::engineering,
                                               int min_integral_digits = 1)
 {
-  if (is_eq_zero(q)) return func(q.in(u));
+  if (q == 0) return func(q.in(u));
 
   using std::abs, std::log10, std::floor;
 

test/static/CMakeLists.txt

@@ -34,7 +34,6 @@ add_library(
     angular_test.cpp
     astronomy_test.cpp
     cgs_test.cpp
-    compare_test.cpp
     concepts_test.cpp
     # custom_rep_test_min_expl.cpp
     custom_rep_test_min_impl.cpp

test/static/compare_test.cpp

@@ -1309,6 +1309,24 @@ static_assert(v{1., 2., 3.} * one == v{1., 2., 3.});
 static_assert(v{1., 2., 3.} != v{3., 2., 1.} * one);
 #endif
 
+static_assert(0 * m == 0);
+static_assert(0. * m == 0);
+static_assert(0 * m == 0.);
+static_assert(0. * m == 0.);
+static_assert(42 * m != 0);
+static_assert(42. * m != 0);
+static_assert(42 * m != 0.);
+static_assert(42. * m != 0.);
+
+static_assert(!(42 * m == 0));
+static_assert(!(42. * m == 0));
+static_assert(!(42 * m == 0.));
+static_assert(!(42. * m == 0.));
+static_assert(!(0 * m != 0));
+static_assert(!(0. * m != 0));
+static_assert(!(0 * m != 0.));
+static_assert(!(0. * m != 0.));
+
 ///////////////////////
 // ordering operators
 ///////////////////////
@@ -1366,6 +1384,38 @@ static_assert(!(123 * km >= 321'000 * m));
 static_assert(1 * one < 2);
 static_assert(1 < 2 * one);
 
+static_assert(42 * m > 0);
+static_assert(42. * m > 0);
+static_assert(42 * m > 0.);
+static_assert(42. * m > 0.);
+static_assert(-42 * m < 0);
+static_assert(-42. * m < 0);
+static_assert(-42 * m < 0.);
+static_assert(-42. * m < 0.);
+
+static_assert(!(-42 * m > 0));
+static_assert(!(-42. * m > 0));
+static_assert(!(-42 * m > 0.));
+static_assert(!(-42. * m > 0.));
+static_assert(!(42 * m < 0));
+static_assert(!(42. * m < 0));
+static_assert(!(42 * m < 0.));
+static_assert(!(42. * m < 0.));
+
+static_assert(42 * m >= 0);
+static_assert(42. * m >= 0);
+static_assert(42 * m >= 0.);
+static_assert(42. * m >= 0.);
+static_assert(0 * m >= 0);
+static_assert(-42 * m <= 0);
+static_assert(-42. * m <= 0);
+static_assert(-42 * m <= 0.);
+static_assert(-42. * m <= 0.);
+static_assert(0 * m <= 0);
+
+static_assert(!(-42 * m >= 0));
+static_assert(!(42 * m <= 0));
+
 
 //////////////////
 // dimensionless