field_comparator.h

This section contains reference documentation for working with protocol buffer classes in C++.

#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 SimpleFieldComparator: 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.

Known subclasses:

Members

enum
FloatComparison
SimpleFieldComparator()
Creates new comparator with float comparison set to EXACT.
~SimpleFieldComparator()
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 ComparisonResult
SimpleCompare(const Message & message_1, const Message & message_2, const FieldDescriptor * field, int index_1, int index_2, const util::FieldContext * field_context)
Returns the comparison result for the given field in two messages. more...
protected bool
CompareWithDifferencer(MessageDifferencer * differencer, const Message & message1, const Message & message2, const util::FieldContext * field_context)
Compare using the provided message_differencer. more...
protected ComparisonResult
ResultFromBoolean(bool boolean_result) const
Returns FieldComparator::SAME if boolean_result is true and FieldComparator::DIFFERENT otherwise.

enum SimpleFieldComparator::FloatComparison {
  EXACT,
  APPROXIMATE
}

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

void SimpleFieldComparator::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 SimpleFieldComparator::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 SimpleFieldComparator::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 ComparisonResult SimpleFieldComparator::SimpleCompare(
        const Message & message_1,
        const Message & message_2,
        const FieldDescriptor * field,
        int index_1,
        int index_2,
        const util::FieldContext * field_context)

Returns the comparison result for the given field in two messages.

This function is called directly by DefaultFieldComparator::Compare. Subclasses can call this function to compare fields they do not need to handle specially.

protected bool SimpleFieldComparator::CompareWithDifferencer(
        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.

class DefaultFieldComparator: public SimpleFieldComparator

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

Members

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...

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.