field_comparator.h

#include <google/protobuf/util/field_comparator.h>
namespace google::protobuf::util

Defines classes for field comparison.

Classes in this file

Base class specifying the interface for comparing protocol buffer fields.
Basic implementation of FieldComparator.

class FieldComparator

#include <google/protobuf/util/field_comparator.h>
namespace google::protobuf::util

Base class specifying the interface for comparing protocol buffer fields.

Regular users should consider using or subclassing DefaultFieldComparator rather than this interface. Currently, this does not support comparing unknown fields.

Known subclasses:

Members

enum
ComparisonResult
FieldComparator()
virtual
~FieldComparator()
virtual ComparisonResult
Compare(const Message & message_1, const Message & message_2, const FieldDescriptor * field, int index_1, int index_2, const util::FieldContext * field_context) = 0
Compares the values of a field in two protocol buffer messages. more...

enum FieldComparator::ComparisonResult {
  SAME,
  DIFFERENT,
  RECURSE
}

SAME

Compared fields are equal.

In case of comparing submessages, user should not recursively compare their contents.

DIFFERENT

Compared fields are different.

In case of comparing submessages, user should not recursively compare their contents.

RECURSE

Compared submessages need to be compared recursively.

FieldComparator does not specify the semantics of recursive comparison. This value should not be returned for simple values.


virtual ComparisonResult FieldComparator::Compare(
        const Message & message_1,
        const Message & message_2,
        const FieldDescriptor * field,
        int index_1,
        int index_2,
        const util::FieldContext * field_context) = 0

Compares the values of a field in two protocol buffer messages.

Returns SAME or DIFFERENT for simple values, and SAME, DIFFERENT or RECURSE for submessages. Returning RECURSE for fields not being submessages is illegal. In case the given FieldDescriptor points to a repeated field, the indices need to be valid. Otherwise they should be ignored.

FieldContext contains information about the specific instances of the fields being compared, versus FieldDescriptor which only contains general type information about the fields.

class DefaultFieldComparator: public FieldComparator

#include <google/protobuf/util/field_comparator.h>
namespace google::protobuf::util

Basic implementation of FieldComparator.

Supports three modes of floating point value comparison: exact, approximate using MathUtil::AlmostEqual method, and arbitrarily precise using MathUtil::WithinFractionOrMargin.

Members

enum
FloatComparison
DefaultFieldComparator()
Creates new comparator with float comparison set to EXACT.
~DefaultFieldComparator()
virtual ComparisonResult
Compare(const Message & message_1, const Message & message_2, const FieldDescriptor * field, int index_1, int index_2, const util::FieldContext * field_context)
Compares the values of a field in two protocol buffer messages. more...
void
set_float_comparison(FloatComparison float_comparison)
FloatComparison
float_comparison() const
void
set_treat_nan_as_equal(bool treat_nan_as_equal)
Set whether the FieldComparator shall treat floats or doubles that are both NaN as equal (treat_nan_as_equal = true) or as different (treat_nan_as_equal = false). more...
bool
treat_nan_as_equal() const
void
SetFractionAndMargin(const FieldDescriptor * field, double fraction, double margin)
Sets the fraction and margin for the float comparison of a given field. more...
void
SetDefaultFractionAndMargin(double fraction, double margin)
Sets the fraction and margin for the float comparison of all float and double fields, unless a field has been given a specific setting via SetFractionAndMargin() above. more...
protected bool
Compare(MessageDifferencer * differencer, const Message & message1, const Message & message2, const util::FieldContext * field_context)
Compare using the provided message_differencer. more...

enum DefaultFieldComparator::FloatComparison {
  EXACT,
  APPROXIMATE
}

EXACTFloats and doubles are compared exactly.
APPROXIMATEFloats and doubles are compared using the MathUtil::AlmostEqual method or MathUtil::WithinFractionOrMargin method.

virtual ComparisonResult DefaultFieldComparator::Compare(
        const Message & message_1,
        const Message & message_2,
        const FieldDescriptor * field,
        int index_1,
        int index_2,
        const util::FieldContext * field_context)

Compares the values of a field in two protocol buffer messages.

Returns SAME or DIFFERENT for simple values, and SAME, DIFFERENT or RECURSE for submessages. Returning RECURSE for fields not being submessages is illegal. In case the given FieldDescriptor points to a repeated field, the indices need to be valid. Otherwise they should be ignored.

FieldContext contains information about the specific instances of the fields being compared, versus FieldDescriptor which only contains general type information about the fields.


void DefaultFieldComparator::set_treat_nan_as_equal(
        bool treat_nan_as_equal)

Set whether the FieldComparator shall treat floats or doubles that are both NaN as equal (treat_nan_as_equal = true) or as different (treat_nan_as_equal = false).

Default is treating NaNs always as different.


void DefaultFieldComparator::SetFractionAndMargin(
        const FieldDescriptor * field,
        double fraction,
        double margin)

Sets the fraction and margin for the float comparison of a given field.

Uses MathUtil::WithinFractionOrMargin to compare the values.

REQUIRES: field->cpp_type == FieldDescriptor::CPPTYPE_DOUBLE or

field->cpp_type == FieldDescriptor::CPPTYPE_FLOAT

REQUIRES: float_comparison_ == APPROXIMATE


void DefaultFieldComparator::SetDefaultFractionAndMargin(
        double fraction,
        double margin)

Sets the fraction and margin for the float comparison of all float and double fields, unless a field has been given a specific setting via SetFractionAndMargin() above.

Uses MathUtil::WithinFractionOrMargin to compare the values.

REQUIRES: float_comparison_ == APPROXIMATE


protected bool DefaultFieldComparator::Compare(
        MessageDifferencer * differencer,
        const Message & message1,
        const Message & message2,
        const util::FieldContext * field_context)

Compare using the provided message_differencer.

For example, a subclass can use this method to compare some field in a certain way using the same message_differencer instance and the field context.