View source for cpp/named req/Compare

{{cpp/named req/title|Compare}}
{{cpp/named req/navbar}}

{{named req|Compare}} is a set of requirements expected by some of the standard library facilities from the user-provided function object types.

The return value of the function call operation applied to an object of a type satisfying {{named req/core|Compare}}, when [[cpp/language/implicit conversion|converted]] to {{c/core|bool}}, yields {{c|true}} if the first argument of the call appears before the second in the {{enwiki|Strict weak ordering|strict weak ordering relation}} induced by this type, and {{c|false}} otherwise.

As with any {{named req|BinaryPredicate}}, evaluation of that expression is not allowed to call non-const functions through the dereferenced iterators and, syntactically, the function call operation must accept {{c/core|const}} object arguments, with the same behavior regardless of whether the arguments are {{c/core|const}} or non-{{c/core|const}}.

===Requirements===
The type {{tt|T}} satisfies {{named req/core|Compare}} if

* The type {{tt|T}} satisfies {{named req|BinaryPredicate}}, and

Given
* {{tt|comp}}, an object of type {{tt|T}},
* {{c|equiv(a, b)}}, an [[cpp/language/expressions#Expression-equivalence|expression-equivalent]] to {{c|!comp(a, b) && !comp(b, a)}}.

The following expressions must be valid and have their specified effects:

{|table class=wikitable
|-
!Expression||Return type||Requirements
|-
|{{c|comp(a, b)}}
|{{rrev multi|noborder=true
|rev1=meets {{named req|BooleanTestable}}
|since2=c++20|rev2=models ''{{ltt|cpp/concepts/boolean-testable}}''
}}
|Establishes {{enwiki|strict weak ordering}} relation with the following properties:
* For all {{tt|a}}, {{c|1=comp(a, a) == false}}.
* If {{c|1=comp(a, b) == true}} then {{c|1=comp(b, a) == false}}.
* if {{c|1=comp(a, b) == true}} and {{c|1=comp(b, c) == true}} then {{c|1=comp(a, c) == true}}.
|-
|{{c|equiv(a, b)}}
|{{c/core|bool}}
|Establishes {{enwiki|equivalence relation}}ship with the following properties:
* For all {{tt|a}}, {{c|1=equiv(a, a) == true}}.
* If {{c|1=equiv(a, b) == true}}, then {{c|1=equiv(b, a) == true}}.
* If {{c|1=equiv(a, b) == true}} and {{c|1=equiv(b, c) == true}}, then {{c|1=equiv(a, c) == true}}.
|}

Note: {{tt|comp}} induces a {{enwiki|Total order#Strict and non-strict total orders|strict total ordering}} on the equivalence classes determined by {{tt|equiv}}.

===Standard library===
The following standard library facilities expect a {{named req/core|Compare}} type.
{{dsc begin}}
{{dsc inc|cpp/container/dsc set}}
{{dsc inc|cpp/container/dsc map}}
{{dsc inc|cpp/container/dsc multiset}}
{{dsc inc|cpp/container/dsc multimap}}
{{dsc inc|cpp/container/dsc priority_queue}}
{{dsc inc|cpp/algorithm/dsc sort}}
{{dsc inc|cpp/container/dsc sort|forward_list}}
{{dsc inc|cpp/container/dsc sort|list}}
{{dsc inc|cpp/algorithm/dsc stable_sort}}
{{dsc inc|cpp/algorithm/dsc partial_sort}}
{{dsc inc|cpp/algorithm/dsc partial_sort_copy}}
{{dsc inc|cpp/algorithm/dsc is_sorted}}
{{dsc inc|cpp/algorithm/dsc is_sorted_until}}
{{dsc inc|cpp/algorithm/dsc nth_element}}
{{dsc inc|cpp/algorithm/dsc lower_bound}}
{{dsc inc|cpp/algorithm/dsc upper_bound}}
{{dsc inc|cpp/algorithm/dsc binary_search}}
{{dsc inc|cpp/algorithm/dsc equal_range}}
{{dsc inc|cpp/algorithm/dsc merge}}
{{dsc inc|cpp/container/dsc merge|forward_list}}
{{dsc inc|cpp/container/dsc merge|list}}
{{dsc inc|cpp/algorithm/dsc inplace_merge}}
{{dsc inc|cpp/algorithm/dsc includes}}
{{dsc inc|cpp/algorithm/dsc set_difference}}
{{dsc inc|cpp/algorithm/dsc set_intersection}}
{{dsc inc|cpp/algorithm/dsc set_symmetric_difference}}
{{dsc inc|cpp/algorithm/dsc set_union}}
{{dsc inc|cpp/algorithm/dsc push_heap}}
{{dsc inc|cpp/algorithm/dsc pop_heap}}
{{dsc inc|cpp/algorithm/dsc make_heap}}
{{dsc inc|cpp/algorithm/dsc sort_heap}}
{{dsc inc|cpp/algorithm/dsc is_heap}}
{{dsc inc|cpp/algorithm/dsc is_heap_until}}
{{dsc inc|cpp/algorithm/dsc max}}
{{dsc inc|cpp/algorithm/dsc max_element}}
{{dsc inc|cpp/algorithm/dsc min}}
{{dsc inc|cpp/algorithm/dsc min_element}}
{{dsc inc|cpp/algorithm/dsc minmax}}
{{dsc inc|cpp/algorithm/dsc minmax_element}}
{{dsc inc|cpp/algorithm/dsc lexicographical_compare}}
{{dsc inc|cpp/algorithm/dsc next_permutation}}
{{dsc inc|cpp/algorithm/dsc prev_permutation}}
{{dsc end}}

===Defect reports===
{{dr list begin}}
{{dr list item|wg=lwg|dr=2114|paper=P2167R3|std=C++98|before=contextual convertibility of return types to {{c/core|bool}} did not<br>reflect the practice of implementations|after=requirements corrected}}
{{dr list item|wg=lwg|dr=3031|std=C++98|before=requirements on {{c/core|const}} values were insufficent|after=requirements strengthened}}
{{dr list end}}

===See also===
{{dsc begin}}
{{dsc inc|cpp/concepts/dsc strict_weak_order}}
{{dsc|[[cpp/language/operator comparison|'''Comparison operators''']]|{{tt|<}}, {{tt|1=<=}}, {{tt|1= >}}, {{tt|1= >=}}, {{tt|1= ==}}, {{tt|1= !=}}, and {{tt|1= <=>}} {{mark c++20}}, compare the arguments}}
{{dsc end}}

{{langlinks|es|ja|zh}}