P0221R2: Proposed wording for default comparisons, revision 4

Introduction

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

• allow memberwise comparisons even if operator= is deleted (but the copy constructor is defaulted); this permits default comparisons for types having const data members
• add notes in the wording according to CWG feedback
• per EWG guidance in Oulu, remove all anti-slicing provisions and thereby avoid breakage of existing code
• per CWG and EWG guidance in Oulu, exclude closure types from having default comparisons

Changes since P0221R0

• fix wording glitches
• clarified the zero-subobject (= empty class) cases
• clarified that the context for a subobject comparison is the top-level class definition
• clarified that both slicing copy and slicing move are prohibited
• two-phase name lookup applies when comparing members whose type was instantiated from a dependent type

Design

• When exactly is a default comparison chosen over a user-declared one?
• Once chosen, what exactly are the semantics of the default comparison? In particular, which comparison operators on the subobjects are looked up where?

Aims

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.

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.

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.

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.

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.

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

Two operator functions have a similar signature if they

• have the same name and,
• given a class type C and the types T1 and T2 of corresponding parameters, each of T1 and T2 is either C or reference to cv C

Examples

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

Closed Issues

• We generate != from == even if the class doesn't satisfy the constraints. This would only be possible if a user-defined operator== exists, of course. We generate any relational operators other than < if both user-defined == and < exist. Example:

    struct S {
      int i = 0;
    };
    bool operator==(const S&, const S&)
    { return true; }
  
    int f() {
      S() != S();    // well-formed, yields false
    }
  

• A class with a mutable member does not get a memberwise operator== or operator< (deviating from N4475 page 17).
• struct S { int a[3]; } will acquire generated comparison functions, but top-level (standalone) int[3] (i.e. an array not wrapped in a struct) will not.
• "T has operator op declared" is interpreted to mean: there is a viable function for x op y, where x and y are lvalues of type T. Examples:

  struct A { };
  void operator==(const A&, const A&);            // yes
  void operator==(const A&, int);                 // no
  void operator==(A&, const A&);                  // yes
  void operator==(A&&, volatile A&);              // no
  void operator==(const volatile A&&, const A&);  // no
  void operator==(A, const A&);                   // yes
  template<class T>
  void operator==(const T&, A);                   // yes
  template<class T>
  void operator==(const T&, const T&);            // yes
  template<class T>
  void operator==(T&&, T&&);                      // no
  

• What kind of lookup is performed for the operator function name when determining that "a class has a given operator declared"? Usual unqualified lookup from which context? Just argument-dependent lookup? Something else? Example:

  struct A { int x, y; } a;
  namespace N {
    void *operator<(A, A);
    auto q = a > a;
  }
  

  Consistent with aim 2, we cannot use N::operator<. This is ill-formed to avoid silent surprises.
• Generation of memberwise operator< relies on memberwise operator==. We do not generate operator< for a class C (implicitly using memberwise == in its definition) if we have a user-declared operator== for C. The latter expresses special comparison semantics for class C, so it's likely that operator< needs to be special as well. Example:

   struct S {
     int x;
   };
   bool operator==(const S&, const S&);
  
   S s;
   bool b = s < s;    // error
  

• Deviating from the recommendation in N4367 "Comparison in C++" by Lawrence Crowl, there is no special case for classes with a single member.

Wording

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 is not a closure type (5.1.5 [expr.prim.lambda]),
• T has no virtual base class (clause 10 [class.derived]),
• T has no virtual member function (10.3 [class.virtual]),
• T has no direct mutable member (7.1.1 [dcl.stc]),
• T has no direct non-static data member of pointer type (9.2 [class.mem]),
• T has no user-provided or deleted copy/move constructor or copy/move assignment operator (12.8 [class.copy]), and
• T has no user-provided copy/move assignment operator.

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.

The operands shall have arithmetic, enumeration, or pointer type. [ Note: For operands of class type, see 9.10 [class.oper]. ] ...

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

• ...
• has all non-static data members and bit-fields in the class and its base classes first declared in as direct members of the same class, and
• ...

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

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:

• A sequence of corresponding subobjects of x and y is formed by starting with a sequence comprising x corresponding to y, and repeatedly replacing each element whose type supports equality comparison by subobject (3.9.2 [basic.compound]) with a sequence of the corresponding subobjects of the direct base classes and direct members of that type, in order of declaration or order of increasing array subscript.
• If the resulting sequence of corresponding subobjects has no elements, x == y yields true and x != y yields false.
• Otherwise, for each element in the sequence of corresponding subobjects, the corresponding subobjects are compared using ==. If a subobject comparison, when contextually converted to bool, yields false, no further subobjects are compared, and x == y yields false and x != y yields true. If all such comparisons yield true, then x == y yields true and x != y yields false.

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

• For x > y, the result is y < x. For x >= y, the result is y <= x.
• A sequence of corresponding subobjects of x and y is formed by starting with a sequence comprising x corresponding to y, and repeatedly replacing each element whose type supports relational comparison by subobject (3.9.2 [basic.compound]) with a sequence of the corresponding subobjects of the direct base classes and direct members of that type, in order of declaration or order of increasing array subscript.
• If the resulting sequence of corresponding subobjects has no elements, x < y yields false and x <= y yields true.
• Otherwise, for each element in the sequence of corresponding subobjects, the corresponding subobjects are compared using ==. If a subobject comparison, when contextually converted to bool, yields false, that element is the first differing one. If the final element is reached for a < comparison, that element is the first differing one, and is not compared with ==. Otherwise, if all such comparisons yield true, there is no first differing element.
• If there is no first differing element, the result of the <= comparison is true. Otherwise, the corresponding subobjects for the first differing element are compared using <. The result of this comparison, when contextually converted to bool, is the result of the overall comparison.

[ 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 ]

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 the operator is == and T does not support equality comparison by subobject, the program is ill-formed.
• If the operator is < and T does not support relational comparison by subobject, the program is ill-formed.
• Otherwise, the operator is treated as a built-in operator and interpreted according to 9.10 [class.oper].

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