GH-48408: [C++] Enable ULP-based float comparison (#49290)

### Rationale for this change

Enable ULP-based floating-point comparison.

### What changes are included in this PR?

Add `arrow::EqualOptions::use_ulp_distance` and `arrow::EqualOptions::ulp_distance`.

### Are these changes tested?

Yes.

### Are there any user-facing changes?

Yes. The ULP-based comparison method is enabled via `arrow::EqualOptions::use_ulp_distance` and `arrow::EqualOptions::ulp_distance`.

* GitHub Issue: #48408

Lead-authored-by: arash andishgar <arashandishgar1@gmail.com>
Co-authored-by: Antoine Pitrou <antoine@python.org>
Signed-off-by: Sutou Kouhei <kou@clear-code.com>

Author: andishgar

c_glib/arrow-glib/basic-array.cpp

@@ -279,7 +279,8 @@ garrow_equal_options_get_property(GObject *object,
     g_value_set_boolean(value, priv->options.nans_equal());
     break;
   case PROP_ABSOLUTE_TOLERANCE:
-    g_value_set_double(value, priv->options.atol());
+    g_value_set_double(value,
+                       priv->options.atol().has_value() ? *priv->options.atol() : 0.0);
     break;
   default:
     G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec);
@@ -348,7 +349,7 @@ garrow_equal_options_class_init(GArrowEqualOptionsClass *klass)
                              "of floating-point values",
                              -G_MAXDOUBLE,
                              G_MAXDOUBLE,
-                             options.atol(),
+                             options.atol().has_value() ? *options.atol() : 0.0,
                              static_cast<GParamFlags>(G_PARAM_READWRITE));
   g_object_class_install_property(gobject_class, PROP_ABSOLUTE_TOLERANCE, spec);
 }

cpp/src/arrow/CMakeLists.txt

@@ -576,6 +576,7 @@ set(ARROW_UTIL_SRCS
     util/time.cc
     util/tracing.cc
     util/trie.cc
+    util/ulp_distance.cc
     util/union_util.cc
     util/unreachable.cc
     util/uri.cc

cpp/src/arrow/array/array_test.cc

@@ -2199,11 +2199,19 @@ void CheckFloatApproxEqualsWithAtol() {
   auto options = EqualOptions::Defaults().atol(0.2);
 
   ASSERT_FALSE(a->Equals(b));
+  ASSERT_TRUE(a->Equals(b, options));
+  ARROW_SUPPRESS_DEPRECATION_WARNING
   ASSERT_TRUE(a->Equals(b, options.use_atol(true)));
+  ASSERT_FALSE(a->Equals(b, options.use_atol(false)));
+  ARROW_UNSUPPRESS_DEPRECATION_WARNING
   ASSERT_TRUE(a->ApproxEquals(b, options));
 
-  ASSERT_FALSE(a->RangeEquals(0, 1, 0, b, options));
+  ASSERT_FALSE(a->RangeEquals(0, 1, 0, b));
+  ASSERT_TRUE(a->RangeEquals(0, 1, 0, b, options));
+  ARROW_SUPPRESS_DEPRECATION_WARNING
   ASSERT_TRUE(a->RangeEquals(0, 1, 0, b, options.use_atol(true)));
+  ASSERT_FALSE(a->RangeEquals(0, 1, 0, b, options.use_atol(false)));
+  ARROW_UNSUPPRESS_DEPRECATION_WARNING
   ASSERT_TRUE(ArrayRangeApproxEquals(*a, *b, 0, 1, 0, options));
 }
 
@@ -2413,6 +2421,42 @@ void CheckFloatingZeroEquality() {
   }
 }
 
+template <typename TYPE>
+void CheckFloatApproxEqualsWithUlpDistance() {
+  using CType =
+      std::conditional_t<is_half_float_type<TYPE>::value, Float16, typename TYPE::c_type>;
+  auto type = TypeTraits<TYPE>::type_singleton();
+  std::vector<CType> a, b;
+  a = {CType(NAN), CType(+0.0), CType(INFINITY)};
+  b = {CType(NAN), CType(-0.0), CType(INFINITY)};
+  if constexpr (is_half_float_type<TYPE>::value) {
+    a.push_back(Float16(1.00097656));
+    b.push_back(Float16(0.999511719f));
+  } else if constexpr (std::is_same_v<TYPE, DoubleType>) {
+    a.push_back(CType(0.9999999999999999));
+    b.push_back(CType(1.0000000000000002));
+  } else if constexpr (std::is_same_v<TYPE, FloatType>) {
+    a.push_back(CType(1.0000001f));
+    b.push_back(CType(0.99999994f));
+  }
+
+  std::shared_ptr<Array> array_a, array_b;
+  ArrayFromVector<TYPE>(type, a, &array_a);
+  ArrayFromVector<TYPE>(type, b, &array_b);
+  auto options = EqualOptions::Defaults().ulp_distance(2);
+
+  // Check with NaN
+  ASSERT_FALSE(array_a->Equals(array_b, options));
+  ASSERT_TRUE(array_a->Equals(array_b, options.nans_equal(true)));
+
+  // Check With Signed Zero
+  ASSERT_FALSE(
+      array_a->Equals(array_b, options.nans_equal(true).signed_zeros_equal(false)));
+
+  // Check with Ulp Distance
+  ASSERT_FALSE(array_a->Equals(array_b, options.nans_equal(true).ulp_distance(1)));
+}
+
 TEST(TestPrimitiveAdHoc, FloatingApproxEquals) {
   CheckApproxEquals<FloatType>();
   CheckApproxEquals<DoubleType>();
@@ -2446,6 +2490,12 @@ TEST(TestPrimitiveAdHoc, FloatingZeroEquality) {
   CheckFloatingZeroEquality<HalfFloatType>();
 }
 
+TEST(TestPrimitiveAdHoc, FloatingUlpDistanceEquality) {
+  CheckFloatApproxEqualsWithUlpDistance<HalfFloatType>();
+  CheckFloatApproxEqualsWithUlpDistance<FloatType>();
+  CheckFloatApproxEqualsWithUlpDistance<DoubleType>();
+}
+
 // ----------------------------------------------------------------------
 // FixedSizeBinary tests
 

cpp/src/arrow/array/statistics_test.cc

@@ -255,8 +255,12 @@ TEST_F(TestArrayStatisticsEqualityDoubleValue, NaN) {
 TEST_F(TestArrayStatisticsEqualityDoubleValue, ApproximateEquals) {
   statistics1_.max = 0.5001f;
   statistics2_.max = 0.5;
-  ASSERT_FALSE(statistics1_.Equals(statistics2_, options_.atol(1e-3)));
+  ASSERT_FALSE(statistics1_.Equals(statistics2_, options_));
+  ASSERT_TRUE(statistics1_.Equals(statistics2_, options_.atol(1e-3)));
+  ARROW_SUPPRESS_DEPRECATION_WARNING
   ASSERT_TRUE(statistics1_.Equals(statistics2_, options_.atol(1e-3).use_atol(true)));
+  ASSERT_FALSE(statistics1_.Equals(statistics2_, options_.atol(1e-3).use_atol(false)));
+  ARROW_UNSUPPRESS_DEPRECATION_WARNING
 }
 
 }  // namespace arrow

cpp/src/arrow/chunked_array.cc

@@ -161,7 +161,11 @@ bool ChunkedArray::Equals(const std::shared_ptr<ChunkedArray>& other,
 
 bool ChunkedArray::ApproxEquals(const ChunkedArray& other,
                                 const EqualOptions& equal_options) const {
-  return Equals(other, equal_options.use_atol(true));
+  auto resolved_options = equal_options;
+  if (!resolved_options.atol()) {
+    resolved_options = resolved_options.atol(kDefaultAbsoluteTolerance);
+  }
+  return Equals(other, resolved_options);
 }
 
 Result<std::shared_ptr<Scalar>> ChunkedArray::GetScalar(int64_t index) const {

cpp/src/arrow/chunked_array.h

@@ -166,6 +166,10 @@ class ARROW_EXPORT ChunkedArray {
   bool Equals(const std::shared_ptr<ChunkedArray>& other,
               const EqualOptions& opts = EqualOptions::Defaults()) const;
   /// \brief Determine if two chunked arrays approximately equal
+  ///
+  /// If the absolute tolerance (atol) is not specified in \ref arrow::EqualOptions,
+  /// 'arrow::kDefaultAbsoluteTolerance' is used.
+  ///
   bool ApproxEquals(const ChunkedArray& other,
                     const EqualOptions& = EqualOptions::Defaults()) const;
 

cpp/src/arrow/chunked_array_test.cc

@@ -202,7 +202,11 @@ TEST_F(TestChunkedArray, ApproxEquals) {
   auto options = EqualOptions::Defaults().atol(1e-3);
 
   ASSERT_FALSE(chunked_array_1->Equals(chunked_array_2));
+  ASSERT_TRUE(chunked_array_1->Equals(chunked_array_2, options));
+  ARROW_SUPPRESS_DEPRECATION_WARNING
   ASSERT_TRUE(chunked_array_1->Equals(chunked_array_2, options.use_atol(true)));
+  ASSERT_FALSE(chunked_array_1->Equals(chunked_array_2, options.use_atol(false)));
+  ARROW_UNSUPPRESS_DEPRECATION_WARNING
   ASSERT_TRUE(chunked_array_1->ApproxEquals(*chunked_array_2, options));
 }