<html>
<head>
<title>P0221R2: Proposed wording for default comparisons, revision 4</title>

<style type="text/css">
  ins { text-decoration:none; font-weight:bold; background-color:#A0FFA0 }
  .new { text-decoration:none; font-weight:bold; background-color:#D0FFD0 }
  .rule { background-color:#FFFF40 }
  .ex { background-color: #D0FFF0 }
  del { text-decoration:line-through; background-color:#FFA0A0 }  
  strong { font-weight: inherit; color: #2020ff }
  .blue { font-weight: inherit; color: #2020ff; background-color: #d0d0ff }
  .hl { font-weight:bold; color: #ff0000 }
</style>
</head>

<body>
P0221R2<br/>
revises: P0221R1<br/>
Jens Maurer &lt;Jens.Maurer@gmx.net><br/>
Audience: Evolution Working Group, Core Working Group<br/>
2016-06-23<br/>

<h1>P0221R2: Proposed wording for default comparisons, revision 4</h1>

<h2>Introduction</h2>

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

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

<p>

P0221R0 as amended by a clarification for template specializations was
approved by EWG during the Jacksonville (2016-03) meeting of WG21.

<strong>Blue text</strong> in the proposed wording indicates changes
compared to P0221R1.


<h2>Changes since P0221R1</h2>

<ul>

<li>allow memberwise comparisons even if operator= is deleted (but the
copy constructor is defaulted); this permits default comparisons for
  types having const data members</li>

<li>add notes in the wording according to CWG feedback</li>

<li>per EWG guidance in Oulu, remove all anti-slicing provisions and
  thereby avoid breakage of existing code</li>

<li>per CWG and EWG guidance in Oulu, exclude closure types from having
default comparisons</li>

</ul>


<h2>Changes since P0221R0</h2>

<ul>

<li>fix wording glitches</li>

<li>clarified the zero-subobject (= empty class) cases</li>

<li>clarified that the context for a subobject comparison is the
top-level class definition</li>

<li>clarified that both slicing copy and slicing move are prohibited</li>

<li>two-phase name lookup applies when comparing members whose type
was instantiated from a dependent type</li>
  
</ul>

<h2>Design</h2>

The fundamental open design questions are:

<ul>
<li>When exactly is a default comparison chosen over a user-declared
one?</li>

<li>Once chosen, what exactly are the semantics of the default
comparison?  In particular, which comparison operators on the
subobjects are looked up where?</li>

</ul>


<h3>Aims</h3>

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.

<ol>

<li>A class author should have no valid reason to write a comparison
function by hand if the default semantics suffice.</li>

<li>A default comparison yields the same result for the same
arguments, regardless where the default comparison appears
(consistency).</li>

<li>Do not invalidate existing code.</li>

<li>Prevent slicing of objects. <strong>Per EWG guidance in Oulu, this
is not implemented.</strong></li>

<li>Do not impose substantial new burdens on implementers.</li>

<li>Make comparisons and copy-assignment similar. <strong>Per EWG
guidance in Oulu, this is not implemented.</strong></li>

</ol>

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

<h3>Rules</h3>

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


<strong>[Rule R1 removed per EWG guidance in Oulu.]</strong>

<p>

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.

<blockquote class="rule">
R2: For each class that is defined, equality (5.10 expr.eq) and
relational (5.9 expr.rel) operator functions according to the pattern

<pre>bool operator <em>op</em>(const C&, const C&);</pre>

are implicitly declared (unless there was a preceding user declaration
with a similar signature), but not yet defined.  (A member declaration
of <em>op</em> 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.

</blockquote>

Third, we allow a user declaration of one of those operator functions
to hide the implicitly-declared one (aim 3):

<blockquote class="rule">
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.

</blockquote>

Fourth, the definition of a default comparison (aim 2, aim 6):

<blockquote class="rule">
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.

</blockquote>

Fifth, using both a default comparison and the corresponding
user-declared comparison is a syntax error (aim 2):

<blockquote class="rule">
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.

</blockquote>

<p>
  <strong>[Rule R6 removed per EWG guidance in Oulu.]</strong>
</p>

Seventh, define "similar signature". <em>This could be extended to (some
kinds of) function templates if desired.</em>

<blockquote class="rule">
Two operator functions have a <em>similar signature</em> if they

<ul>
<li>have the same name and,</li>

<li>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 <em>cv</em>
C</li>

</ul>

</blockquote>

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.


<h2>Examples</h2>

In the examples, cases where currently well-formed code becomes
ill-formed or changes semantics is highlighted in <span
class="hl">red</span>.


<h3>Basic case</h3>

<blockquote>
<pre class="ex">
struct B { int x; };
B b;
bool result = B() == b;   // ok, default== for B
</pre>
</blockquote>


<h3>Hiding by user-declared functions I</h3>

<blockquote>
<pre class="ex">
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==

</pre>

</blockquote>

<h3>Hiding by user-declared functions II</h3>

<blockquote>
<pre class="ex">
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)
}
</pre>

</blockquote>


<h3>Hijacking declarations I</h3>

<blockquote>
<pre class="ex">
struct S { };
bool b1 = S() == S();     // <span class="hl">ok, use default==</span>
namespace N {
  bool operator==(S,S);   // #1
  bool b2 = S() == S();   // ok, use N::operator==
}
</pre>

</blockquote>

<h3>Hijacking declarations II</h3>

<blockquote>
<pre class="ex">
struct S { };              // #1
struct S2 { S s; };
namespace N {
  bool operator==(S,S);    // #2
  bool b = S2() == S2();   // #3  ok, does not use #2
}
</pre>

For #3, we use the default== on S2.  Its definition uses the default==
on S introduced at #1.

</blockquote>


<h3>User-declared conversions</h3>

<blockquote>
<pre class="ex">
struct S {
  operator int() const;
};
bool b = S() == S();        // ok, <strong>using built-in "int == int"</strong>
</pre>

</blockquote>


<h3>Templates I</h3>

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

</blockquote>


<h3>Templates II</h3>

<blockquote>
<pre class="ex">
template&lt;class T>
class S { };
template&lt;class T>
bool operator==(const S&lt;T>&, const S&lt;T>&);
S&lt;int> s;
bool b = s == s;       // use user-declared operator==
</pre>

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

</blockquote>


<h3>Templates III (examples by Herb Sutter)</h3>

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

<pre class="ex">
// 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&lt;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&lt;class T> struct C4 { };
template&lt;class T> bool operator==(const C4&lt;T>&, const C4&lt;T>&);
bool b = C4() == C4();                // uses user-declared == for C4


// case 2a: fully general template
struct C5 { };
template&lt;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&lt;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();               // <strong>uses user-declared == for X</strong>
</pre>
</blockquote>


<h2>Open Issues</h2>

(none at this time)


<h2>Closed Issues</h2>

<ul>
<li>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
&lt; if both user-defined == and &lt; exist.  Example:

<pre>
  struct S {
    int i = 0;
  };
  bool operator==(const S&, const S&)
  { return true; }

  int f() {
    S() != S();    // well-formed, yields false
  }
</pre>

</li>

<li>A class with a mutable member does not get a memberwise operator==
or operator&lt; (deviating from N4475 page 17).</li>

<li><code>struct S { int a[3]; }</code> will acquire generated
comparison functions, but top-level (standalone) <code>int[3]</code>
(i.e. an array not wrapped in a struct) will not.</li>

<li>"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:

<pre>
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&lt;class T>
void operator==(const T&, A);                   // yes
template&lt;class T>
void operator==(const T&, const T&);            // yes
template&lt;class T>
void operator==(T&&, T&&);                      // no
</pre>
</li>

<li>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:
<pre>
struct A { int x, y; } a;
namespace N {
  void *operator&lt;(A, A);
  auto q = a > a;
}
</pre>

Consistent with aim 2, we cannot use N::operator&lt;.  This is
ill-formed to avoid silent surprises.</li>


<li>Generation of memberwise operator&lt; relies on memberwise
operator==.  We do not generate operator&lt; 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&lt; needs to be special as
well.

Example:
<pre>
 struct S {
   int x;
 };
 bool operator==(const S&, const S&);

 S s;
 bool b = s < s;    // error
</pre>
</li>


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

</ul>


<h2>Wording</h2>

Add at the end of 3.9.2 [basic.compound]:

<blockquote class="new">
A type <em>cv</em> T <em>supports comparison by subobject</em>
if T is an array type,
or is a non-union class type that satisfies the following constraints:

<ul>

<li><strong>T is not a closure type (5.1.5 [expr.prim.lambda]),</strong>
<li>T has no virtual base class (clause 10 [class.derived]),</li>
<li>T has no virtual member function (10.3 [class.virtual]),</li>
<li>T has no direct mutable member (7.1.1 [dcl.stc]),</li>

<li>T has no direct non-static data member of pointer type (9.2
[class.mem]),</li>

<li>T has no user-provided or deleted copy/move constructor <del
class=blue>or copy/move assignment operator</del> (12.8
  [class.copy])<strong>, and</strong></li>

<li><strong>T has no user-provided copy/move assignment operator</strong>.</li>

</ul>

T <em>supports operator op</em> in a given context if
overload resolution (13.3.1.2 [over.match.oper]) finds a viable
function for the expression <code>x
<em>op</em> y</code>, where x and y are lvalues of type T.

<p>

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

<p>

T <em>supports relational comparison by subobject</em> in a given
context if T supports equality comparison by subobject in that context
and does not support operator &lt;, operator &lt;=, operator &gt;, and
operator &gt;= in that context.

</blockquote>

<strong>Change in 5.9 [expr.rel] paragraph 2:</strong>

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

<strong>Change in 5.10 [expr.eq] paragraph 2:</strong>

<blockquote>
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 <code>std::nullptr_t</code>. <ins>[ Note: For operands of class
type, see 9.10 [class.oper]. ]</ins> ...
</blockquote>


Change in 9 [class] paragraph 7 bullet 6:

<blockquote>
<ul>
<li>...</li>

<li>has all non-static data members and bit-fields in the class and
its base classes <del>first declared in</del> <ins>as direct members
of</ins> the same class, and</li>

<li>...</li>

</ul>

</blockquote>

Change in 9.2 [class.mem] paragraph 1:

<blockquote>
The <em>member-specification</em> in a class definition declares the
full set of members of the class; no member can be added elsewhere.  <ins>A <em>direct
member</em> of a class is a member of <strong>the</strong> class that was first
declared within the class's <em>member-specification</em>.</ins> ...

</blockquote>

Add a new section 9.10 [class.oper]:

<blockquote class="new">
<b>9.10 Operators [class.oper]</b>
<p>

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

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.  <strong>[ Note: For the original
x-y pair, x and y are considered subobjects of themselves,
respectively. ]</strong> 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 <strong>as if in a member function of class
T defined at the point where the comparison appears</strong>.  [ Note:
The context determines operator function lookup and access control.  ]

<p>
Comparing x and y for equality is defined as follows:

<ul>

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

<li>If the resulting sequence of corresponding subobjects has
no elements, <code>x == y</code> yields true and <code>x != y</code>
yields false.</li>

<li>Otherwise, for each element in the sequence of
corresponding subobjects, the corresponding subobjects are compared
using ==. If <strong>a subobject</strong> comparison, when contextually converted to
<code>bool</code>, yields false, no further subobjects are compared,
and <code>x == y</code> yields false and <code>x != y</code> yields
true.  If all such comparisons yield true, then <code>x == y</code>
yields true and <code>x != y</code> yields false.</li>

</ul>

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

<ul>
<li>For x &gt; y, the result is y &lt; x.  For x &gt;= y, the result
is y &lt;= x.</li>

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

<li>If the resulting sequence of corresponding subobjects has
no elements, <code>x &lt; y</code> yields false and <code>x &lt;=
y</code> yields true.</li>

<li>Otherwise, for each element in the sequence of
corresponding subobjects, the corresponding subobjects are compared
using ==. If <strong>a subobject</strong> comparison, when contextually converted to bool,
yields false, that element is the first differing
one.  If the final element is reached for a &lt; 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.</li>

<li>If there is no first differing element, the result of the &lt;=
comparison is true. Otherwise, the corresponding subobjects for the
first differing element are compared using &lt;. The result of this
comparison, when contextually converted to bool, is the result of
the overall comparison.</li>

</ul>


[ Example:
<pre>
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 &lt; s1;       // yields false
  s1 &lt; s2;       // yields true
  s1 == b;       // error: not the same class type
  T() == T();    // yields true
  T() &lt; T();     // error: operator> is user-declared
}

template&lt;class T>
struct V {
  T x;
};

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

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

</pre>
-- end example ]

</blockquote>


Add a paragraph after 13.3.1.2 [over.match.oper] paragraph 7:

<blockquote class="new">
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:

<ul>

<li>If the operator is == and T does not support equality comparison
by subobject, the program is ill-formed.</li>

<li>If the operator is &lt; and T does not support relational comparison by subobject, the program is ill-formed.

<li>Otherwise, the operator is treated as a built-in
operator and interpreted according to 9.10 [class.oper].</li>

</ul>

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:

<pre>
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 ==
</pre>

-- end example ]

</blockquote>



<h2>Acknowledgements</h2>

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.

</body>
</html>
