P0221R2
revises: P0221R1
Jens Maurer <Jens.Maurer@gmx.net>
Audience: Evolution Working Group, Core Working Group
2016-06-23

P0221R2: Proposed wording for default comparisons, revision 4

Introduction

This paper presents design rationale and proposed wording to implement default comparisons for class types. It is a revision of N4532 with additional updates from the Evolution Working Group session at the Kona meeting of WG21 and in-depth discussions with interested parties.

This paper assumes that the reader is familar with N4475 "Default comparisons (R2)" by Bjarne Stroustrup. In particular, default comparisons are assumed to be implicit (i.e. require no extra syntax to be available).

P0221R0 as amended by a clarification for template specializations was approved by EWG during the Jacksonville (2016-03) meeting of WG21. Blue text in the proposed wording indicates changes compared to P0221R1.

Changes since P0221R1

Changes since P0221R0

Design

The fundamental open design questions are:

Aims

These are general high-level aims and are not all fully satisfied by the design presented further below. The numbering does not indicate a priority, but is intended for easier reference.
  1. A class author should have no valid reason to write a comparison function by hand if the default semantics suffice.
  2. A default comparison yields the same result for the same arguments, regardless where the default comparison appears (consistency).
  3. Do not invalidate existing code.
  4. Prevent slicing of objects. Per EWG guidance in Oulu, this is not implemented.
  5. Do not impose substantial new burdens on implementers.
  6. Make comparisons and copy-assignment similar. Per EWG guidance in Oulu, this is not implemented.
In an ideal world, the comparison operators would be declared alongside the class they apply to, i.e. as members or (preferrably) as non-members in the immediately enclosing namespace of the class. Unconstrained template parameters in comparison operators or declarations in unrelated namespaces are considered a bug in the user's code. That said, in order to avoid breaking existing code, existing semantics of code are preserved by this proposal.

Given aim 3, we're 30+ years late in mandating the ideal world, which is too late. In particular, that means we cannot enforce the important principle that x==y appearing in different corners of the source code has the same semantics everywhere. We can, however, make sure that the default (if used) has the same semantics everywhere.

Rules

The following rules reflect the aims above. These rules are given in informal language; for a precise wording of the rules, refer to the "wording" section below.

[Rule R1 removed per EWG guidance in Oulu.]

Second, we introduce declarations (but not definitions) of the default comparisons for each class that is defined (aim 1). Note that a class template specialization is a class that is defined when the class template is instantiated or explicitly specialized. A friend declaration is only visible to argument-dependent lookup, thus we can only find it for function calls, but not for taking the address.

R2: For each class that is defined, equality (5.10 expr.eq) and relational (5.9 expr.rel) operator functions according to the pattern
bool operator op(const C&, const C&);
are implicitly declared (unless there was a preceding user declaration with a similar signature), but not yet defined. (A member declaration of op is transformed into the equivalent non-member form by introducing the implicit object parameter (13.3.1 over.match.funcs) for the check.) The declaration is as-if by a friend declaration immediately before the closing brace of the class definition.
Third, we allow a user declaration of one of those operator functions to hide the implicitly-declared one (aim 3):
R3: A user-declared comparison function hides the corresponding implicitly-declared one for class C with a similar signature (if any). Hiding means that if both appear in a lookup set, only the user-declared comparison function is considered in overload resolution.
Fourth, the definition of a default comparison (aim 2, aim 6):
R4: An implicitly-declared comparison function for a class C is defined if it is odr-used (3.2 basic.def.odr). It performs subobject decomposition and then subobject comparisons (see "wording" below). The subobject comparisons are performed in the context of class C as-if immediately before the closing brace of the class definition. If subobject comparison would be ill-formed, the comparison is defined as deleted.
Fifth, using both a default comparison and the corresponding user-declared comparison is a syntax error (aim 2):
R5: If an expression or the definition of a default comparison uses a default comparison, but would use a user-declared comparison if the former appeared later in the translation unit, the program is ill-formed. No diagnostic is required if the use and the competing declaration are in different translation units.

[Rule R6 removed per EWG guidance in Oulu.]

Seventh, define "similar signature". This could be extended to (some kinds of) function templates if desired.
Two operator functions have a similar signature if they
Note that the wording below takes a slightly different approach by reusing the intermediate results of overload resolution to determine whether a default comparison should be generated.

Examples

In the examples, cases where currently well-formed code becomes ill-formed or changes semantics is highlighted in red.

Basic case

struct B { int x; };
B b;
bool result = B() == b;   // ok, default== for B

Hiding by user-declared functions I

struct S {
  bool operator==(const S&);   // #1; note: non-const (user oversight)
};

S s;
bool b1 = s == s;               // calls #1
bool b2 = S() == S();           // error, can't call #1 and no default==

struct S2 { };
bool operator==(const S2&, const S2&);  // #2

bool b3 = S2() == S2();         // calls #2

struct S3 { };
S operator==(const S3&, S3&);   // #3 (strange)
S3 s3;
S b4 = s3 == s3;                // calls #3; no default==
S b5 = S3() == S3();            // error, can't call #3 and no default==

Hiding by user-declared functions II

struct S { };
namespace N {
  bool operator==(const S&, const S&);  // #1
  bool operator==(const S&, S&);        // #2
  bool b = S() == S();   // calls #1 (note: some prefer default== or error)
  S s;
  bool b2 = S() == s;    // calls #2 (note: some prefer default== or error)
}

Hijacking declarations I

struct S { };
bool b1 = S() == S();     // ok, use default==
namespace N {
  bool operator==(S,S);   // #1
  bool b2 = S() == S();   // ok, use N::operator==
}

Hijacking declarations II

struct S { };              // #1
struct S2 { S s; };
namespace N {
  bool operator==(S,S);    // #2
  bool b = S2() == S2();   // #3  ok, does not use #2
}
For #3, we use the default== on S2. Its definition uses the default== on S introduced at #1.

User-declared conversions

struct S {
  operator int() const;
};
bool b = S() == S();        // ok, using built-in "int == int"

Templates I

struct C { };
template<class T>
bool operator==(const T&, const T&);
bool b = C() == C();           // ok, use operator== template

Templates II

template<class T>
class S { };
template<class T>
bool operator==(const S<T>&, const S<T>&);
S<int> s;
bool b = s == s;       // use user-declared operator==
template<class T>
class S2 {
  friend bool operator==(const S2<T>&, const S2<T>&) { ... }
};
S<int> s;
bool b2 = s == s;      // uses user-declared operator==

Templates III (examples by Herb Sutter)

Case 1: User-written == appears as a member of C, or in the same namespace as C and mentions C specifically. All of these cases call the user-written ==. Varying the parameter types between C, const C&, and C& does not change the outcome, except that the rules preventing binding prvalues to lvalue references remain in force.
// case 1a: obvious case
struct C1 { 
  bool operator==(const C1&) const;
};
bool b = C1() == C1();                // uses user-declared == for C1

// case 1b: obvious case, non-member
struct C2 { };
bool operator==(const C2&, const C2&);
bool b = C2() == C2();                // uses user-declared == for C2

// case 1c: class template member
template<class T>
struct C3 { 
  bool operator==(const C3&) const;
};
bool b = C3() == C3();                // uses user-declared == for C3

// case 1d: function template for a class template
template<class T> struct C4 { };
template<class T> bool operator==(const C4<T>&, const C4<T>&);
bool b = C4() == C4();                // uses user-declared == for C4


// case 2a: fully general template
struct C5 { };
template<class T> bool operator==(const T&, const T&);
C5 c5;
bool b = C5() == C5();              // calls operator function template

// case 2b: same with concept
struct C6 { };
template<My_concept T> bool operator==(const T&, const T&);
bool b = C6() == C6();              // calls operator function template

// case 2c: conversion
struct C7 { };
struct X { X(const C7&){} };         // convertible from C7
bool operator==(const X&, const X&);
bool b = C7() == C7();               // uses user-declared == for X

Open Issues

(none at this time)

Closed Issues

Wording

Add at the end of 3.9.2 [basic.compound]:
A type cv T supports comparison by subobject if T is an array type, or is a non-union class type that satisfies the following constraints: T supports operator op in a given context if overload resolution (13.3.1.2 [over.match.oper]) finds a viable function for the expression x op y, where x and y are lvalues of type T.

T supports equality comparison by subobject in a given context if T supports comparison by subobject and does not support operator== and operator!= in that context.

T supports relational comparison by subobject in a given context if T supports equality comparison by subobject in that context and does not support operator <, operator <=, operator >, and operator >= in that context.

Change in 5.9 [expr.rel] paragraph 2:
The operands shall have arithmetic, enumeration, or pointer type. [ Note: For operands of class type, see 9.10 [class.oper]. ] ...
Change in 5.10 [expr.eq] paragraph 2:
The == (equal to) and the != (not equal to) operators group left-to-right. The operands shall have arithmetic, enumeration, pointer, or pointer to member type, or type std::nullptr_t. [ Note: For operands of class type, see 9.10 [class.oper]. ] ...
Change in 9 [class] paragraph 7 bullet 6:
Change in 9.2 [class.mem] paragraph 1:
The member-specification in a class definition declares the full set of members of the class; no member can be added elsewhere. A direct member of a class is a member of the class that was first declared within the class's member-specification. ...
Add a new section 9.10 [class.oper]:
9.10 Operators [class.oper]

[ Note: This section specifies the meaning of relational (5.9 [expr.rel]) or equality (5.10 [expr.eq]) operators applied to values of class type. ]

The result of comparing two objects x and y that have the same class or array type T (ignoring cv-qualification) is defined by decomposing x and y into a sequence of corresponding subobjects and comparing the pairs of corresponding subobjects. [ Note: For the original x-y pair, x and y are considered subobjects of themselves, respectively. ] The context for applying a comparison operator to such a pair is defined as follows: If the original x-y pair is compared, the context is where the comparison appears. Otherwise, the context is as if in a member function of class T defined at the point where the comparison appears. [ Note: The context determines operator function lookup and access control. ]

Comparing x and y for equality is defined as follows:

Comparing x and y with a relational operator is defined as follows:

[ Example:
struct B {
  int i = 0;
};

struct S : B {
  int j = 1;
};

struct T : S {
   bool operator>(T) = delete;
};

void f()
{
  B b;
  S s1, s2;
  s2.j = 2;
  s1 == s1;      // yields true
  s1 != s2;      // yields true
  s1 < s1;       // yields false
  s1 < s2;       // yields true
  s1 == b;       // error: not the same class type
  T() == T();    // yields true
  T() < T();     // error: operator> is user-declared
}

template<class T>
struct V {
  T x;
};

struct E { };
bool operator==(E,E);

V<E> v;
bool b = v == v;   // ok, default== finds operator== for E
 
struct Q {
  int x;
};
bool operator==(Q&&, Q&&);
Q q1, q2;
bool bq = q1 == q2;   // ok, compares q1.x == q2.x

-- end example ]
Add a paragraph after 13.3.1.2 [over.match.oper] paragraph 7:
If overload resolution yields no viable function (13.3.2 [over.match.viable]) for a relational (5.9 [expr.rel]) or equality (5.10 [expr.eq]) operator and the operands are of the same complete class type T (ignoring cv-qualification), then: If a comparison operator is treated as a built-in operator in a context whose nearest enclosing namespace is N, and a comparison with the same operator and the same operand types in another context whose nearest enclosing namespace is also N is not treated as a built-in operator, the program is ill-formed. No diagnostic is required if the two comparisons appear in different translation units. [ Example:
struct S { };
bool b = S() == S();   // built-in ==

bool operator==(const S&, const S&);
S s;
bool b2 = s == s;      // error: not using built-in ==
-- end example ]

Acknowledgements

Thanks to Richard Smith for valuable input, and the majority of the drafting presented above. All errors are mine, of course. Thanks to Bjarne Stroupstrup and Herb Sutter for in-depth discussions.