11 Classes [class]

11.10 Comparisons [class.compare]

11.10.1 Defaulted comparison operator functions [class.compare.default]

A defaulted comparison operator function ([expr.spaceship], [expr.rel], [expr.eq]) for some class C shall be a non-template function declared in the member-specification of C that is

(1.1)
a non-static const member of C having one parameter of type const C&, or
(1.2)
a friend of C having two parameters of type const C&.

A defaulted comparison operator function for class C is defined as deleted if any non-static data member of C is of reference type or C is a union-like class ([class.union.anon]).

If the class definition does not explicitly declare an == operator function, but declares a defaulted three-way comparison operator function, an == operator function is declared implicitly with the same access as the three-way comparison operator function.

The implicitly-declared == operator for a class X is an inline member and is defined as defaulted in the definition of X.

If the three-way comparison operator function is declared as a non-static const member, the implicitly-declared == operator function is a member of the form

bool X::operator==(const X&) const;

Otherwise, the implicitly-declared == operator function is of the form

friend bool operator==(const X&, const X&);

[ Note

: Such a friend function is visible to argument-dependent lookup ([basic.lookup.argdep]) only ([namespace.memdef]). — end note

]

The operator is a constexpr function if its definition would satisfy the requirements for a constexpr function.

[ Note

The == operator function is declared implicitly even if the defaulted three-way comparison operator function is defined as deleted.

— end note

]

A type C has strong structural equality if, given a glvalue x of type const C, either:

(4.1)
C is a non-class type and x <=> x is a valid expression of type std::strong_ordering or std::strong_equality, or
(4.2)
C is a class type where all of the following hold:
- (4.2.1)
  All of C's base class subobjects and non-static data members have strong structural equality.
- (4.2.2)
  C has no mutable or volatile non-static data members.
- (4.2.3)
  At the end of the definition of C, overload resolution performed for the expression x == x succeeds and finds either a friend or public member == operator that is defined as defaulted in the definition of C.

The direct base class subobjects of C, in the order of their declaration in the base-specifier-list of C, followed by the non-static data members of C, in the order of their declaration in the member-specification of C, form a list of subobjects.

In that list, any subobject of array type is recursively expanded to the sequence of its elements, in the order of increasing subscript.

Let

x_{i}

be an lvalue denoting the

i^{th}

element in the expanded list of subobjects for an object x (of length n), where

x_{i}

is formed by a sequence of derived-to-base conversions ([over.best.ics]), class member access expressions ([expr.ref]), and array subscript expressions ([expr.sub]) applied to x.

It is unspecified whether virtual base class subobjects appear more than once in the expanded list of subobjects.

11.10.2 Equality operators [class.eq]

A defaulted equality operator ([expr.eq]) function shall have a declared return type bool.

A defaulted == operator function for a class C is defined as deleted unless, for each

x_{i}

in the expanded list of subobjects for an object x of type C,

x_{i} == x_{i}

is a valid expression and contextually convertible to bool.

The return value V of a defaulted == operator function with parameters x and y is determined by comparing corresponding elements

x_{i}

and

y_{i}

in the expanded lists of subobjects for x and y (in increasing index order) until the first index i where

x_{i} == y_{i}

yields a result value which, when contextually converted to bool, yields false.

If no such index exists, V is true.

Otherwise, V is false.

A defaulted != operator function for a class C with parameters x and y is defined as deleted if

(4.1)
overload resolution ([over.match]), as applied to x == y, does not result in a usable function, or
(4.2)
x == y is not a prvalue of type bool.

Otherwise, the operator function yields !(x == y).

[ Example

struct D {
  int i;
  friend bool operator==(const D& x, const D& y) = default;
                                                // OK, returns x.i == y.i
  bool operator!=(const D& z) const = default;  // OK, returns !(*this == z)
};

— end example

]

11.10.3 Three-way comparison [class.spaceship]

The synthesized three-way comparison for comparison category type R ([cmp.categories]) of glvalues a and b of the same type is defined as follows:

(1.1)
If overload resolution for a <=> b finds a usable function ([over.match]), static_cast<R>(a <=> b).
(1.2)
Otherwise, if overload resolution for a <=> b finds at least one viable candidate, the synthesized three-way comparison is not defined.

(1.3)

Otherwise, if R is strong_ordering, then

a == b ? strong_ordering::equal :
a < b  ? strong_ordering::less :
         strong_ordering::greater

(1.4)

Otherwise, if R is weak_ordering, then

a == b ? weak_ordering::equal :
a < b  ? weak_ordering::less :
         weak_ordering::greater

(1.5)

Otherwise, if R is partial_ordering, then

a == b ? partial_ordering::equivalent :
a < b  ? partial_ordering::less :
b < a  ? partial_ordering::greater :
         partial_ordering::unordered

(1.6)

Otherwise, if R is strong_equality, then

a == b ? strong_equality::equal : strong_equality::nonequal

(1.7)

Otherwise, if R is weak_equality, then

a == b ? weak_equality::equivalent : weak_equality::nonequivalent

(1.8)
Otherwise, the synthesized three-way comparison is not defined.

[ Note

A synthesized three-way comparison may be ill-formed if overload resolution finds usable functions that do not otherwise meet the requirements implied by the defined expression.

— end note

]

Given an expanded list of subobjects for an object x of type C, the type of the expression

x_{i}

<=>

x_{i}

is denoted by

R_{i}

If overload resolution as applied to

x_{i}

<=>

x_{i}

does not find a usable function, then

R_{i}

is void.

If the declared return type of a defaulted three-way comparison operator function is auto, then the return type is deduced as the common comparison type (see below) of

R_{0}

R_{1}

, …,

R_{n - 1}

If the return type is deduced as void, the operator function is defined as deleted.

If the declared return type of a defaulted three-way comparison operator function is R and the synthesized three-way comparison for comparison category type R between any objects

x_{i}

and

x_{i}

is not defined or would be ill-formed, the operator function is defined as deleted.

The return value V of type R of the defaulted three-way comparison operator function with parameters x and y of the same type is determined by comparing corresponding elements

x_{i}

and

y_{i}

in the expanded lists of subobjects for x and y (in increasing index order) until the first index i where the synthesized three-way comparison for comparison category type R between

x_{i}

and

y_{i}

yields a result value

v_{i}

where

v_{i}!= 0

, contextually converted to bool, yields true; V is

v_{i}

If no such index exists, V is std::strong_ordering::equal converted to R.

The common comparison type U of a possibly-empty list of n types

T_{0}

T_{1}

, …,

T_{n - 1}

is defined as follows:

(4.1)
If any $T_{i}$ is not a comparison category type ([cmp.categories]), U is void.
(4.2)
Otherwise, if at least one $T_{i}$ is std::weak_equality, or at least one $T_{i}$ is std::strong_equality and at least one $T_{j}$ is std::partial_ordering or std::weak_ordering, U is std::weak_equality ([cmp.weakeq]).
(4.3)
Otherwise, if at least one $T_{i}$ is std::strong_equality, U is std::strong_equality ([cmp.strongeq]).
(4.4)
Otherwise, if at least one $T_{i}$ is std::partial_ordering, U is std::partial_ordering ([cmp.partialord]).
(4.5)
Otherwise, if at least one $T_{i}$ is std::weak_ordering, U is std::weak_ordering ([cmp.weakord]).
(4.6)
Otherwise, U is std::strong_ordering ([cmp.strongord]).

[ Note
:
In particular, this is the result when n is 0.
— end note
]

11.10.4 Relational operators [class.rel]

A defaulted relational ([expr.rel]) operator function for some operator @ shall have a declared return type bool.

The operator function with parameters x and y is defined as deleted if

(2.1)
overload resolution ([over.match]), as applied to x <=> y, does not result in a usable function, or
(2.2)
the operator @ cannot be applied to the return type of x <=> y.

Otherwise, the operator function yields x <=> y @ 0.

[ Example

struct C {
  friend std::strong_equality operator<=>(const C&, const C&);
  bool operator<(const C&) const = default;             // OK, function is deleted
};

— end example

]