std::weak_order

From cppreference.com

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros(C++20)
Language support library
Concepts library(C++20)
Diagnostics library
Memory management library
Metaprogramming library(C++11)
General utilities library
Containers library
Iterators library
Ranges library(C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library(C++17)
Concurrency support library(C++11)
Execution control library(C++26)
Technical specifications
Symbols index
External libraries

[edit]

Utilities library

Language support

Type support (basic types, RTTI)

Library feature-test macros(C++20)

Program utilities

Variadic functions

initializer_list

(C++11)

is_constant_evaluated

(C++20)

is_within_lifetime

(C++26)

source_location

(C++20)

Coroutine support(C++20)

Contract support(C++26)

Three-way comparison

three_way_comparablethree_way_comparable_with

(C++20)(C++20)

strong_ordering

(C++20)

weak_ordering

(C++20)

partial_ordering

(C++20)

common_comparison_category

(C++20)

compare_three_way_result

(C++20)

compare_three_way

(C++20)

strong_order

(C++20)

weak_order

(C++20)

partial_order

(C++20)

compare_strong_order_fallback

(C++20)

compare_weak_order_fallback

(C++20)

compare_partial_order_fallback

(C++20)

is_eqis_ltis_lteq

(C++20)(C++20)(C++20)

is_neqis_gtis_gteq

(C++20)(C++20)(C++20)

General utilities

Function objects
Bit manipulation(C++20)
C-style bit manipulation(C++26)
bitset
hash (C++11)

Relational operators(deprecated in C++20)

rel_ops::operator!=rel_ops::operator>

rel_ops::operator<=rel_ops::operator>=

Integer comparison functions

cmp_equalcmp_lesscmp_less_than

(C++20)(C++20)(C++20)

cmp_not_equalcmp_greatercmp_greater_than

(C++20)(C++20)(C++20)

in_range

(C++20)

Swap andtype operations

swap
ranges::swap (C++20)
exchange (C++14)
declval (C++11)
to_underlying (C++23)

forward (C++11)
forward_like (C++23)
move (C++11)
move_if_noexcept (C++11)
as_const (C++17)

Common vocabulary types

pair
tuple (C++11)
optional (C++17)
any (C++17)
variant (C++17)

tuple_size (C++11)
tuple_element (C++11)
apply (C++17)
make_from_tuple (C++17)
expected (C++23)

[edit]

Defined in header`<compare>`
inlinenamespace/* unspecified /{ inlineconstexpr/ unspecified / weak_order=/ unspecified */; }		(since C++20)
Call signature
template<class T,class U> requires/* see below / constexprstd::weak_ordering weak_order(T&& t, U&& u)noexcept(/ see below */);

Compares two values using 3-way comparison and produces a result of typestd::weak_ordering.

Lett andu be expressions andT andU denotedecltype((t)) anddecltype((u)) respectively,std::weak_order(t, u) isexpression-equivalent to:

Ifstd::is_same_v<std::decay_t<T>,std::decay_t<U>> istrue:
- std::weak_ordering(weak_order(t, u)), if it is a well-formed expression with overload resolution performed in a context that does not include a declaration ofstd::weak_order,
- otherwise, ifT is a floating-point type:
  - ifstd::numeric_limits<T>::is_iec559 istrue, performs the weak ordering comparison of floating-point values (see below) and returns that result as a value of typestd::weak_ordering,
  - otherwise, yields a value of typestd::weak_ordering that is consistent with the ordering observed byT's comparison operators,
- otherwise,std::weak_ordering(std::compare_three_way()(t, u)), if it is well-formed,
- otherwise,std::weak_ordering(std::strong_order(t, u)), if it is well-formed.
In all other cases, the expression is ill-formed, which can result insubstitution failure when it appears in the immediate context of a template instantiation.

Customization point objects

The namestd::weak_order denotes acustomization point object, which is a constfunction object of aliteral semiregular class type. SeeCustomizationPointObject for details.

[edit]Strict weak order of IEEE floating-point types

Letx andy be values of same IEEE floating-point type, andweak_order_less(x, y) be the boolean result indicating ifx precedesy in the strict weak order defined by the C++ standard.

If neitherx nory is NaN, thenweak_order_less(x, y)==true if and only ifx< y, i.e. all representations of equal floating-point value are equivalent;
Ifx is negative NaN andy is not negative NaN, thenweak_order_less(x, y)==true;
Ifx is not positive NaN andy is positive NaN, thenweak_order_less(x, y)==true;
If bothx andy are NaNs with the same sign, then(weak_order_less(x, y)|| weak_order_less(y, x))==false, i.e. all NaNs with the same sign are equivalent.

[edit]Example

This section is incomplete
Reason: no example

[edit]See also

weak_ordering (C++20)	the result type of 3-way comparison that supports all 6 operators and is not substitutable (class)[edit]
strong_order (C++20)	performs 3-way comparison and produces a result of type`std::strong_ordering` (customization point object)[edit]
partial_order (C++20)	performs 3-way comparison and produces a result of type`std::partial_ordering` (customization point object)[edit]
compare_weak_order_fallback (C++20)	performs 3-way comparison and produces a result of type`std::weak_ordering`, even ifoperator<=> is unavailable (customization point object)[edit]