<h1 id="comparison-concepts">Comparison Concepts</h1>
<pre>
Date: 2018-09-24
Author: David Stone (&#100;&#97;&#118;&#105;&#100;&#109;&#115;&#116;&#111;&#110;&#101;&#64;&#103;&#111;&#111;&#103;&#108;&#101;&#46;&#99;&#111;&#109;, &#100;&#97;&#118;&#105;&#100;&#64;&#100;&#111;&#117;&#98;&#108;&#101;&#119;&#105;&#115;&#101;&#46;&#110;&#101;&#116;)
Audience: LEWG
</pre>

<h2 id="proposal">Proposal</h2>
<p>This paper proposes allowing anything which is currently specified as accepting a <code>BinaryPredicate</code> to also accept a function that returns a comparison category implicitly convertible to <code>weak_equality</code>. Anything which is currently specified as accepting a <code>Compare</code> should also accept a function that returns a comparison category implicitly convertible to <code>weak_ordering</code>.</p>
<p>This paper also proposes a general library requirement that if <code>a &lt;=&gt; b</code> is valid, it is consistent with all other comparison operators. In other words, for every comparison operator (<code>==</code>, <code>!=</code>, <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, and <code>&gt;=</code>) and for every value of <code>a</code> and <code>b</code>, <code>(a @ b) == (a &lt;=&gt; b @ 0)</code>. In particular, any function that accepts a type meeting the <code>LessThanComparable</code> concept should be able to call <code>a &lt;=&gt; b</code> instead of <code>a &lt; b</code> if <code>a &lt;=&gt; b</code> is well-formed. Whether an implementation calls <code>&lt;=&gt;</code> or any of the 6 traditional comparison operators is not considered an observable difference.</p>
<p>This paper does not recommend changing the definitions of the comparable type concepts (such as <code>LessThanComparable</code>) to require <code>operator&lt;=&gt;</code>. <code>operator&lt;=&gt;</code> is a valid implementation strategy to satisfy these concepts, but should not be required, as all that we care about for these concepts is the direct comparisons. This ensures backward compatibility with old user-defined types.</p>
<h2 id="motivation">Motivation</h2>
<p>This is especially important in the case of <code>Compare</code> to maximize efficiency. We would like users to be able to pass in function objects that are three-way-comparison-aware. Right now, <code>std::map&lt;std::string, T, Compare&gt;</code> has to make two passes over each <code>string</code> it compares if that string does not compare less. The <code>operator&lt;=&gt;</code> proposal gives us a more efficient way to do things (guaranteed single pass), so we should take advantage of it where possible. This paper does not propose changing the default template argument for <code>map</code>, but this paper does allow users to create something more efficient.</p>
<p>For <code>BinaryPredicate</code>, the issue has more to do with consistency. If a user has written a function returning a comparison category, we know that they intend it to be used to compare objects. It is a frustrating and incomplete user experience to not be able to use that function object consistently. This is especially true if the user is trying to perform multiple operations on the same type of elements. For instance, they may want to write a comparison function that can be passed to both <code>sort</code> and <code>unique</code>. This is not possible right now, because <code>sort</code> requires a <code>Compare</code>, but <code>unique</code> requires a <code>BinaryPredicate</code>. By integrating comparison categories into these concepts, we allow a single function object to meet both requirements.</p>
<h2 id="background">Background</h2>
<p>There are two sets of concepts in the standard library that relate to comparisons: concepts that constrain comparison function objects, and concepts that constrain comparable types.</p>
<h3 id="comparison-function-objects">Comparison Function Objects</h3>
<h4 id="-binarypredicate-"><code>BinaryPredicate</code></h4>
<p>A <code>BinaryPredicate</code> must accept two arguments and return a value contextually convertible to <code>bool</code>. representing whether those two objects are equal. <code>BinaryPredicate</code> is used in the following places in the standard:</p>
<ul>
<li><code>default_searcher</code></li>
<li><code>boyer_moore_searcher</code></li>
<li><code>boyer_moore_horspool_searcher</code></li>
<li><code>forward_list::unique</code></li>
<li><code>list::unique</code></li>
<li><code>find_end</code></li>
<li><code>find_first_of</code></li>
<li><code>adjacent_find</code></li>
<li><code>mismatch</code></li>
<li><code>equal</code></li>
<li><code>is_permutation</code></li>
<li><code>search</code></li>
<li><code>search_n</code></li>
<li><code>unique</code></li>
<li><code>unique_copy</code></li>
</ul>
<h4 id="-compare-"><code>Compare</code>.</h4>
<p> A <code>Compare</code> must accept two arguments and return a <code>bool</code> representing whether the first argument is less than the second, and it must provide a strict weak order (<code>a &lt; b</code> implies <code>!(b &lt; a)</code>, and equality is determined by <code>!(a &lt; b) and !(b &lt; a)</code>). <code>Compare</code> is used in the following places in the standard:</p>
<ul>
<li><code>AssociativeContainer</code> (<code>map</code>, <code>multimap</code>, <code>set</code>, <code>multiset</code>)</li>
<li><code>forward_list::merge</code></li>
<li><code>forward_list::sort</code></li>
<li><code>list::merge</code></li>
<li><code>list::sort</code></li>
<li><code>priority_queue</code></li>
<li><code>sort</code></li>
<li><code>stable_sort</code></li>
<li><code>partial_sort</code></li>
<li><code>partial_sort_copy</code></li>
<li><code>is_sorted</code></li>
<li><code>is_sorted_until</code></li>
<li><code>nth_element</code></li>
<li><code>lower_bound</code></li>
<li><code>upper_bound</code></li>
<li><code>equal_range</code></li>
<li><code>binary_search</code></li>
<li><code>merge</code></li>
<li><code>inplace_merge</code></li>
<li><code>includes</code></li>
<li><code>set_union</code></li>
<li><code>set_intersection</code></li>
<li><code>set_difference</code></li>
<li><code>set_symmetric_difference</code></li>
<li><code>push_heap</code></li>
<li><code>pop_heap</code></li>
<li><code>make_heap</code></li>
<li><code>sort_heap</code></li>
<li><code>is_heap</code></li>
<li><code>is_heap_until</code></li>
<li><code>min</code></li>
<li><code>max</code></li>
<li><code>minmax</code></li>
<li><code>min_element</code></li>
<li><code>max_element</code></li>
<li><code>minmax_element</code></li>
<li><code>clamp</code></li>
<li><code>lexicographical_compare</code></li>
<li><code>next_permutation</code></li>
<li><code>prev_permutation</code></li>
</ul>
<h3 id="comparable-type-concepts">Comparable Type Concepts</h3>
<ul>
<li><code>EqualityComparable</code>: requires only <code>a == b</code>.</li>
<li><code>LessThanComparable</code>: requires only that <code>a &lt; b</code> provides a strict weak ordering.</li>
<li><code>NullablePointer</code>: inherits <code>EqualityComparable</code> and turns it into <code>weak_equality</code>, additionally requiring <code>a != b</code>. Additionally requires heterogeneous <code>==</code> and <code>!=</code> (<code>weak_equality</code>) with <code>nullptr_t</code>.</li>
<li><code>InputIterator</code>: inherits <code>EqualityComparable</code> and turns it into <code>weak_equality</code>, additionally requiring <code>a != b</code>.</li>
<li><code>Allocator</code>: requires <code>weak_equality</code> (<code>a == b</code> and <code>a != b</code>), requires heterogeneous comparison with the equivalent <code>Allocator</code> for other types</li>
<li>&quot;bitmask type&quot;: <code>strong_equality</code> (it might be a <code>bitset</code>, which supports only equality, it might be integer or enum, which supports ordering, but this will naturally fall out, no wording changes are needed here)</li>
<li>We redundantly specify <code>weak_ordering</code> for <code>TrivialClock::rep</code>, <code>TrivialClock::duration</code>, and <code>TrivialClock::time_point</code>, but that is implied because we know they are an arithmetic type, a <code>chrono::duration</code>, and a <code>chrono::time_point</code>, respectively.</li>
</ul>

