include/arrow/compare.h

0001 // Licensed to the Apache Software Foundation (ASF) under one
0002 // or more contributor license agreements.  See the NOTICE file
0003 // distributed with this work for additional information
0004 // regarding copyright ownership.  The ASF licenses this file
0005 // to you under the Apache License, Version 2.0 (the
0006 // "License"); you may not use this file except in compliance
0007 // with the License.  You may obtain a copy of the License at
0008 //
0009 //   http://www.apache.org/licenses/LICENSE-2.0
0010 //
0011 // Unless required by applicable law or agreed to in writing,
0012 // software distributed under the License is distributed on an
0013 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
0014 // KIND, either express or implied.  See the License for the
0015 // specific language governing permissions and limitations
0016 // under the License.
0017
0018 // Functions for comparing Arrow data structures
0019
0020 #pragma once
0021
0022 #include <cstdint>
0023 #include <iosfwd>
0024
0025 #include "arrow/util/macros.h"
0026 #include "arrow/util/visibility.h"
0027
0028 namespace arrow {
0029
0030 class Array;
0031 class DataType;
0032 class Tensor;
0033 class SparseTensor;
0034 struct Scalar;
0035
0036 static constexpr double kDefaultAbsoluteTolerance = 1E-5;
0037
0038 /// A container of options for equality comparisons
0039 class EqualOptions {
0040  public:
0041   /// Whether or not NaNs are considered equal.
0042   bool nans_equal() const { return nans_equal_; }
0043
0044   /// Return a new EqualOptions object with the "nans_equal" property changed.
0045   EqualOptions nans_equal(bool v) const {
0046     auto res = EqualOptions(*this);
0047     res.nans_equal_ = v;
0048     return res;
0049   }
0050
0051   /// Whether or not zeros with differing signs are considered equal.
0052   bool signed_zeros_equal() const { return signed_zeros_equal_; }
0053
0054   /// Return a new EqualOptions object with the "signed_zeros_equal" property changed.
0055   EqualOptions signed_zeros_equal(bool v) const {
0056     auto res = EqualOptions(*this);
0057     res.signed_zeros_equal_ = v;
0058     return res;
0059   }
0060
0061   /// The absolute tolerance for approximate comparisons of floating-point values.
0062   double atol() const { return atol_; }
0063
0064   /// Return a new EqualOptions object with the "atol" property changed.
0065   EqualOptions atol(double v) const {
0066     auto res = EqualOptions(*this);
0067     res.atol_ = v;
0068     return res;
0069   }
0070
0071   /// The ostream to which a diff will be formatted if arrays disagree.
0072   /// If this is null (the default) no diff will be formatted.
0073   std::ostream* diff_sink() const { return diff_sink_; }
0074
0075   /// Return a new EqualOptions object with the "diff_sink" property changed.
0076   /// This option will be ignored if diff formatting of the types of compared arrays is
0077   /// not supported.
0078   EqualOptions diff_sink(std::ostream* diff_sink) const {
0079     auto res = EqualOptions(*this);
0080     res.diff_sink_ = diff_sink;
0081     return res;
0082   }
0083
0084   static EqualOptions Defaults() { return {}; }
0085
0086  protected:
0087   double atol_ = kDefaultAbsoluteTolerance;
0088   bool nans_equal_ = false;
0089   bool signed_zeros_equal_ = true;
0090
0091   std::ostream* diff_sink_ = NULLPTR;
0092 };
0093
0094 /// Returns true if the arrays are exactly equal
0095 ARROW_EXPORT bool ArrayEquals(const Array& left, const Array& right,
0096                               const EqualOptions& = EqualOptions::Defaults());
0097
0098 /// Returns true if the arrays are approximately equal. For non-floating point
0099 /// types, this is equivalent to ArrayEquals(left, right)
0100 ARROW_EXPORT bool ArrayApproxEquals(const Array& left, const Array& right,
0101                                     const EqualOptions& = EqualOptions::Defaults());
0102
0103 /// Returns true if indicated equal-length segment of arrays are exactly equal
0104 ARROW_EXPORT bool ArrayRangeEquals(const Array& left, const Array& right,
0105                                    int64_t start_idx, int64_t end_idx,
0106                                    int64_t other_start_idx,
0107                                    const EqualOptions& = EqualOptions::Defaults());
0108
0109 /// Returns true if indicated equal-length segment of arrays are approximately equal
0110 ARROW_EXPORT bool ArrayRangeApproxEquals(const Array& left, const Array& right,
0111                                          int64_t start_idx, int64_t end_idx,
0112                                          int64_t other_start_idx,
0113                                          const EqualOptions& = EqualOptions::Defaults());
0114
0115 ARROW_EXPORT bool TensorEquals(const Tensor& left, const Tensor& right,
0116                                const EqualOptions& = EqualOptions::Defaults());
0117
0118 /// EXPERIMENTAL: Returns true if the given sparse tensors are exactly equal
0119 ARROW_EXPORT bool SparseTensorEquals(const SparseTensor& left, const SparseTensor& right,
0120                                      const EqualOptions& = EqualOptions::Defaults());
0121
0122 /// Returns true if the type metadata are exactly equal
0123 /// \param[in] left a DataType
0124 /// \param[in] right a DataType
0125 /// \param[in] check_metadata whether to compare KeyValueMetadata for child
0126 /// fields
0127 ARROW_EXPORT bool TypeEquals(const DataType& left, const DataType& right,
0128                              bool check_metadata = true);
0129
0130 /// Returns true if scalars are equal
0131 /// \param[in] left a Scalar
0132 /// \param[in] right a Scalar
0133 /// \param[in] options comparison options
0134 ARROW_EXPORT bool ScalarEquals(const Scalar& left, const Scalar& right,
0135                                const EqualOptions& options = EqualOptions::Defaults());
0136
0137 /// Returns true if scalars are approximately equal
0138 /// \param[in] left a Scalar
0139 /// \param[in] right a Scalar
0140 /// \param[in] options comparison options
0141 ARROW_EXPORT bool ScalarApproxEquals(
0142     const Scalar& left, const Scalar& right,
0143     const EqualOptions& options = EqualOptions::Defaults());
0144
0145 }  // namespace arrow