Comparison operators
Compares the arguments.
Operator name | Syntax | Overloadable | Prototype examples (for class T) | |
---|---|---|---|---|
Inside class definition | Outside class definition | |||
equal to | a == b
|
Yes | bool T::operator==(const T2& b) const; | bool operator==(const T& a, const T2& b); |
not equal to | a != b
|
Yes | bool T::operator!=(const T2& b) const; | bool operator!=(const T& a, const T2& b); |
less than | a < b
|
Yes | bool T::operator<(const T2& b) const; | bool operator<(const T& a, const T2& b); |
greater than | a > b
|
Yes | bool T::operator>(const T2& b) const; | bool operator>(const T& a, const T2& b); |
less than or equal to | a <= b
|
Yes | bool T::operator<=(const T2& b) const; | bool operator<=(const T& a, const T2& b); |
greater than or equal to | a >= b
|
Yes | bool T::operator>=(const T2& b) const; | bool operator>=(const T& a, const T2& b); |
three-way comparison (C++20) | a <=> b
|
Yes | R T::operator<=>(const T2& b) const;[1]
|
R operator<=>(const T& a, const T2& b);[1]
|
|
Two-way comparison
The two-way comparison operator expressions have the form
lhs < rhs
|
(1) | ||||||||
lhs > rhs
|
(2) | ||||||||
lhs <= rhs
|
(3) | ||||||||
lhs >= rhs
|
(4) | ||||||||
lhs == rhs
|
(5) | ||||||||
lhs != rhs
|
(6) | ||||||||
In all cases, for the built-in operators, lhs and rhs must have either
- arithmetic or enumeration type (see arithmetic comparison operators below)
- pointer type (see pointer comparison operators below)
after the application of the lvalue-to-rvalue, array-to-pointer and function-to-pointer standard conversions. The comparison is deprecated if both operands have array type prior to the application of these conversions. (since C++20)
In any case, the result is a bool prvalue.
Arithmetic comparison operators
If the operands have arithmetic or enumeration type (scoped or unscoped), usual arithmetic conversions are performed on both operands following the rules for arithmetic operators. The values are compared after conversions:
Example
#include <iostream> int main() { static_assert(sizeof(unsigned char) < sizeof(int), "Can't compare signed and smaller unsigned properly"); int a = -1; int b = 1; unsigned int c = 1; unsigned char d = 1; std::cout << std::boolalpha << "Comparing two signed values:\n" << " -1 == 1 ? " << (a == b) << '\n' << " -1 < 1 ? " << (a < b) << '\n' << " -1 > 1 ? " << (a > b) << '\n' << "Comparing signed and unsigned:\n" << " -1 == 1 ? " << (a == c) << '\n' // may issue different-signedness warning << " -1 < 1 ? " << (a < c) << '\n' // may issue different-signedness warning << " -1 > 1 ? " << (a > c) << '\n' // may issue different-signedness warning << "Comparing signed and smaller unsigned:\n" << " -1 == 1 ? " << (a == d) << '\n' << " -1 < 1 ? " << (a < d) << '\n' << " -1 > 1 ? " << (a > d) << '\n'; }
Output:
Comparing two signed values: -1 == 1 ? false -1 < 1 ? true -1 > 1 ? false Comparing signed and unsigned: -1 == 1 ? false -1 < 1 ? false -1 > 1 ? true Comparing signed and smaller unsigned: -1 == 1 ? false -1 < 1 ? true -1 > 1 ? false
Pointer comparison operators
Comparison operators can be used to compare two pointers.
Only equality operators (operator== and operator!=) can be used to compare the following pointer pairs:
- two pointers-to-members
- a null pointer constant with a pointer or a pointer-to-member
|
(since C++11) |
First, pointer conversions (pointer to member conversions if the arguments are pointers to members), function pointer conversions, (since C++17) and qualification conversions are applied to both operands to obtain the composite pointer type, as follows:
1) If both operands are null pointer constants, the composite pointer type is std::nullptr_t.
|
(since C++11) |
- a pointer to cv1 void, and
- a pointer to cv2
T
, whereT
is an object type or void,
-
P1
, a pointer to (possibly cv-qualified)T1
, and -
P2
, a pointer to (possibly cv-qualified)T2
,
T1
is the same as T2
or is a base class of T2
, then the composite pointer type is the cv-combined type of P1
and P2
. Otherwise, if T2
is a base class of T1
, then the composite pointer type is the cv-combined type of P2
and P1
.-
MP1
, pointer to member ofT1
of type (possibly cv-qualified)U1
, and -
MP2
, pointer to member ofT2
of type (possibly cv-qualified)U2
,
T1
is the same as or derived from T2
, then the composite pointer type is the cv-combined type of MP1
and MP2
. Otherwise, if T2
is derived from T1
, then the composite pointer type is the cv-combined type of MP2
and MP1
.P1
and P2
are multi-level mixed pointer and pointer to member types with the same number of levels that only differ by cv-qualifications at any of the levels, the composite pointer type is the cv-combined type of P1
and P2
.In the definition above, cv-combined type of two pointer types P1
and P2
is a type P3
that has the same number of levels and type at every level as P1
, except that cv-qualifications at every level are set as follows:
P1
and P2
at that level,P1
's or P2
's cv-qualification at the same level, then const is added to every level between the top level and this one.For example, the composite pointer type of void* and const int* is const void*. The composite pointer type of int** and const int** is const int* const*. Note that until the resolution of CWG issue 1512 (N3624), int** and const int** could not be compared.
In addition to the above, the composite pointer type between pointer to function and pointer to noexcept function (as long as the function type is the same) is pointer to function. |
(since C++17) |
Note that this implies that any pointer can be compared with void*.
The result of comparing two pointers to objects (after conversions) is defined as follows:
The result of equality comparison of two pointers (after conversions) is defined as follows:
reinterpret_cast
, etc).The result of comparing two pointers to members (after conversions) is defined as follows:
C1
and the other refers to a member of a different class C2
, where neither is a base class of the other, the result is unspecified.
struct A {}; struct B : A { int x; }; struct C : A { int x; }; int A::*bx = (int(A::*)) &B::x; int A::*cx = (int(A::*)) &C::x; bool b1 = (bx == cx); // unspecified
struct B { int f(); }; struct L : B {}; struct R : B {}; struct D : L, R {}; int (B::*pb)() = &B::f; int (L::*pl)() = pb; int (R::*pr)() = pb; int (D::*pdl)() = pl; int (D::*pdr)() = pr; bool x = (pdl == pdr); // false bool y = (pb == pl); // true
If a pointer p compare equal to pointer q, p <= q and p >= q both yield true and p < q and p > q both yield false.
If a pointer p compares greater than a pointer q, then p >= q, p > q, q <= p, and q < p all yield true and p <= q, p < q, q >= p, and q > p all yield false.
If two pointers are not specified to compare greater or compare equal, the result of the comparison is unspecified. An unspecified result may be nondeterministic, and need not be consistent even for multiple evaluations of the same expression with the same operands in the same execution of the program:
int x, y; bool f(int* p, int* q) { return p < q; } assert(f(&x, &y) == f(&x, &y)); // may fire in a conforming implementation
In overload resolution against user-defined operators, for every pair of promoted arithmetic types L
and R
, including enumeration types, the following function signatures participate in overload resolution:
bool operator<(L, R); |
||
bool operator>(L, R); |
||
bool operator<=(L, R); |
||
bool operator>=(L, R); |
||
bool operator==(L, R); |
||
bool operator!=(L, R); |
||
For every type P
which is either pointer to object or pointer to function, the following function signatures participate in overload resolution:
bool operator<(P, P); |
||
bool operator>(P, P); |
||
bool operator<=(P, P); |
||
bool operator>=(P, P); |
||
bool operator==(P, P); |
||
bool operator!=(P, P); |
||
For every type MP
that is a pointer to member object or pointer to member function or std::nullptr_t, the following function signatures participate in overload resolution:
bool operator==(MP, MP); |
||
bool operator!=(MP, MP); |
||
Example
#include <iostream> struct Foo { int n1; int n2; }; union Union { int n; double d; }; int main() { std::cout << std::boolalpha; char a[4] = "abc"; char* p1 = &a[1]; char* p2 = &a[2]; std::cout << "Pointers to array elements:\n" << "p1 == p2? " << (p1 == p2) << '\n' << "p1 < p2? " << (p1 < p2) << '\n'; Foo f; int* p3 = &f.n1; int* p4 = &f.n2; std::cout << "Pointers to members of a class:\n" << "p3 == p4? " << (p3 == p4) << '\n' << "p3 < p4? " << (p3 < p4) << '\n'; Union u; int* p5 = &u.n; double* p6 = &u.d; std::cout << "Pointers to members of a union:\n" << "p5 == (void*)p6? " << (p5 == (void*)p6) << '\n' << "p5 < (void*)p6? " << (p5 < (void*)p6) << '\n'; }
Output:
Pointers to array elements: p1 == p2? false p1 < p2? true Pointers to members of a class: p3 == p4? false p3 < p4? true Pointers to members of a union: p5 == (void*)p6? true p5 < (void*)p6? false
Notes
Because these operators group left-to-right, the expression a < b < c is parsed (a < b) < c, and not a < (b < c) or (a < b) && (b < c).
#include <iostream> int main() { int a = 3, b = 2, c = 1; std::cout << std::boolalpha << (a < b < c) << '\n' // true; maybe warning << ((a < b) < c) << '\n' // true << (a < (b < c)) << '\n' // false << ((a < b) && (b < c)) << '\n'; // false }
A common requirement for user-defined operator< is strict weak ordering. In particular, this is required by the standard algorithms and containers that work with Compare types: std::sort, std::max_element, std::map, etc.
Although the results of comparing pointers of random origin (e.g. not all pointing to members of the same array) is unspecified, many implementations provide strict total ordering of pointers, e.g. if they are implemented as addresses within continuous virtual address space. Those implementations that do not (e.g. where not all bits of the pointer are part of a memory address and have to be ignored for comparison, or an additional calculation is required or otherwise pointer and integer is not a 1 to 1 relationship), provide a specialization of std::less for pointers that has that guarantee. This makes it possible to use all pointers of random origin as keys in standard associative containers such as std::set or std::map.
For the types that are both EqualityComparable and LessThanComparable, the C++ standard library makes a distinction between equality, which is the value of the expression a == b and equivalence, which is the value of the expression !(a < b) && !(b < a).
Comparison between pointers and null pointer constants was removed by the resolution of CWG issue 583 included in N3624:
void f(char* p) { if (p > 0) { /*...*/ } // Error with N3624, compiled before N3624 if (p > nullptr) { /*...*/ } // Error with N3624, compiled before N3624 } int main() {}
Three-way comparisonThe three-way comparison operator expressions have the form
The expression returns an object such that
If one of the operands is of type bool and the other is not, the program is ill-formed. If both operands have arithmetic types, or if one operand has unscoped enumeration type and the other has integral type, the usual arithmetic conversions are applied to the operands, and then
If both operands have the same enumeration type If at least one of the operands is a pointer or pointer-to-member, array-to-pointer conversions, derived-to-base pointer conversions, function pointer conversions, and qualification conversions are applied as necessary to convert both operands to the same pointer type, and the resulting pointer type is an object pointer type, p <=> q returns a prvalue of type std::strong_ordering:
Otherwise, the program is ill-formed. In overload resolution against user-defined operators, for pointer or enumeration type
Where ExampleRun this code #include <compare> #include <iostream> int main() { double foo = -0.0; double bar = 0.0; auto res = foo <=> bar; if (res < 0) std::cout << "-0 is less than 0"; else if (res > 0) std::cout << "-0 is greater than 0"; else if (res == 0) std::cout << "-0 and 0 are equal"; else std::cout << "-0 and 0 are unordered"; } Output: -0 and 0 are equal NotesThree-way comparison can be automatically generated for class types, see default comparisons. If both of the operands are arrays, three-way comparison is ill-formed. unsigned int i = 1; auto r = -1 < i; // existing pitfall: returns ‘false’ auto r2 = -1 <=> i; // Error: narrowing conversion required |
(since C++20) |
Feature-test macro | Value | Std | Comment |
---|---|---|---|
__cpp_impl_three_way_comparison |
201907L | (C++20) | Three-way comparison (compiler support) |
__cpp_lib_three_way_comparison |
201907L | (C++20) | Three-way comparison (library support); adding three-way comparison to the library |
Standard library
Comparison operators are overloaded for many classes in the standard library.
(removed in C++20) |
checks whether the objects refer to the same type (public member function of std::type_info ) |
(removed in C++20)(removed in C++20)(C++20) |
compares two error_code s (function) |
(removed in C++20)(removed in C++20)(C++20) |
compares error_condition s and error_code s (function) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values in the pair (function template) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values in the tuple (function template) |
(removed in C++20) |
compares the contents (public member function of std::bitset<N> ) |
(removed in C++20) |
compares two allocator instances (public member function of std::allocator<T> ) |
(removed in C++20)(C++20) |
compares to another unique_ptr or with nullptr (function template) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
compares with another shared_ptr or with nullptr (function template) |
(removed in C++20) |
compares a std::function with nullptr (function template) |
(C++11)(C++11)(removed in C++20)(C++11)(C++11)(C++11)(C++11)(C++20) |
compares two durations (function template) |
(C++11)(C++11)(removed in C++20)(C++11)(C++11)(C++11)(C++11)(C++20) |
compares two time points (function template) |
(removed in C++20) |
compares two scoped_allocator_adaptor instances (function template) |
(removed in C++20)(C++20) |
compares the underlying std::type_info objects (public member function of std::type_index ) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares two strings (function template) |
(removed in C++20) |
equality comparison between locale objects (public member function of std::locale ) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values in the array (function template) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values in the deque (function template) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values in the forward_list (function template) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values in the list (function template) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values in the vector (function template) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values in the map (function template) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values in the multimap (function template) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values in the set (function template) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values in the multiset (function template) |
(removed in C++20) |
compares the values in the unordered_map (function template) |
(removed in C++20) |
compares the values in the unordered_multimap (function template) |
(removed in C++20) |
compares the values in the unordered_set (function template) |
(removed in C++20) |
compares the values in the unordered_multiset (function template) |
lexicographically compares the values in the queue (function template) | |
lexicographically compares the values in the stack (function template) | |
compares the underlying iterators (function template) | |
(C++11)(C++11)(removed in C++20)(C++11)(C++11)(C++11)(C++11)(C++20) |
compares the underlying iterators (function template) |
(removed in C++20) |
compares two istream_iterator s (function template) |
(removed in C++20) |
compares two istreambuf_iterator s (function template) |
(removed in C++20) |
compares two complex numbers or a complex and a scalar (function template) |
compares two valarrays or a valarray with a value (function template) | |
(C++11)(C++11)(removed in C++20) |
compares the internal states of two pseudo-random number engines (function) |
(C++11)(C++11)(removed in C++20) |
compares two distribution objects (function) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
compares a sub_match with another sub_match , a string, or a character (function template) |
(removed in C++20) |
lexicographically compares the values in the two match result (function template) |
(removed in C++20) |
compares two regex_iterator s (public member function of std::regex_iterator<BidirIt,CharT,Traits> ) |
(removed in C++20) |
compares two regex_token_iterator s (public member function of std::regex_token_iterator<BidirIt,CharT,Traits> ) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
compares two thread::id objects (function) |
The namespace std::rel_ops provides generic operators !=, >, <=, and >=:
Defined in header
<utility> | |
Defined in namespace
std::rel_ops | |
(deprecated in C++20) |
automatically generates comparison operators based on user-defined operator== and operator< (function template) |
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
CWG 583 (N3624) |
C++98 | all six comparison operators could be used to compare a pointer with a null pointer constant |
only equality operators allowed |
CWG 661 | C++98 | the actual semantics of arithmetic comparisons (e.g. whether 1 < 2 yields true or false) were unspecified |
specification added |
CWG 879 | C++98 | pointers to function types and pointers to void did not have built-in comparisons |
added comparison specification for these pointers |
CWG 1512 (N3624) |
C++98 | the rule of composite pointer type was incomplete, and thus did not allow comparison between int** and const int** |
made complete |
CWG 1596 | C++98 | non-array objects were considered to belong to arrays with one element only for the purpose of pointer arithmetic |
the rule is also applied to comparison |
CWG 1598 | C++98 | two pointers to members of classes that are different and neither is the base class of the other did not compare equal even if the offsets of the pointed members can be the same |
the result is unspecified in this case |
CWG 1858 | C++98 | it was not clear whether two pointers to members that refer to different members of the same union compare equal as if they refer to the same member |
they compare equal in this case |
CWG 2419 | C++98 | a pointer to non-array object was only treated as a pointer to the first element of an array with size 1 in pointer comparison if the pointer is obtained by &
|
applies to all pointers to non-array objects |
CWG 2526 | C++98 | the definition of relational comparison (> , >= , < and <= ) ofpointers to void and function pointers were removed by N3624 |
restored |
See also
- Compare (named requirements)
Common operators | ||||||
---|---|---|---|---|---|---|
assignment | increment decrement |
arithmetic | logical | comparison | member access |
other |
a = b |
++a |
+a |
!a |
a == b |
a[...] |
function call |
a(...) | ||||||
comma | ||||||
a, b | ||||||
conditional | ||||||
a ? b : c | ||||||
Special operators | ||||||
static_cast converts one type to another related type |