Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/utility/compare/partial ordering"

From cppreference.com
< cpp‎ | utility
m (s/unused argument/unused parameter)
m (~)
 
(18 intermediate revisions by 9 users not shown)
Line 1: Line 1:
 
{{cpp/title|partial_ordering}}
 
{{cpp/title|partial_ordering}}
 
{{cpp/utility/navbar}}
 
{{cpp/utility/navbar}}
−
{{ddcl | since=c++20 | header=compare| 1=
+
{{ddcl|since=c++20|header=compare|1=
 
class partial_ordering;
 
class partial_ordering;
 
}}
 
}}
  
−
The class type {{tt|std::partial_ordering}} is the result type of a [[cpp/language/operator_comparison#Three-way_comparison|three-way comparison]] that
+
The class type {{tt|std::partial_ordering}} is the result type of a [[cpp/language/operator comparison#Three-way comparison|three-way comparison]] that:
−
* admits all six relational operators (==, !=, <, <=, >, >=)
+
* Admits all six relational operators ({{tt|1===}}, {{tt|1=!=}}, {{tt|<}}, {{tt|1=<=}}, {{tt|>}}, {{tt|1=>=}}).
−
* does not imply substitutability: if a is equivalent to b, f(a) does not have to be equivalent to f(b)
+
{{cpp/utility/compare/substitutable|no}}
−
* admits incomparable values: a < b, a == b, and a > b may all be false
+
* {{enwiki|Connected relation|Admits incomparable values}}: {{c|a < b}}, {{c|1=a == b}}, and {{c|a > b}} may all be {{c|false}}.
  
 
===Constants===
 
===Constants===
−
The type {{tt|std::weak_ordering}} has four valid values, implemented as const static data members of its type:
+
The type {{tt|std::partial_ordering}} has four valid values, implemented as const static data members of its type:
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc hitem | Member type | Definition}}
+
{{dsc hitem|Name|Definition}}
−
{{dsc mem sconst | less | nolink=true| title=less{{mark|inline constexpr}} | a valid value of the type {{tt|std::partial_ordering}} indicating less-than (ordered before) relationship }}
+
{{dsc mem sconst|{{dsc small|{{c/core|inline constexpr std::partial_ordering}}}} less|nolink=true|a valid value indicating less-than (ordered before) relationship}}
−
{{dsc mem sconst | equivalent| nolink=true| title=equivalent{{mark|inline constexpr}} | a valid value of the type {{tt|std::partial_ordering}} indicating equivalence (neither ordered before nor ordered after)}}
+
{{dsc mem sconst|{{dsc small|{{c/core|inline constexpr std::partial_ordering}}}} equivalent|nolink=true|a valid value indicating equivalence (neither ordered before nor ordered after)}}
−
{{dsc mem sconst | greater | nolink=true| title=greater{{mark|inline constexpr}} | a valid value of the type {{tt|std::partial_ordering}} indicating greater-than (ordered after) relationship }}
+
{{dsc mem sconst|{{dsc small|{{c/core|inline constexpr std::partial_ordering}}}} greater|nolink=true|a valid value indicating greater-than (ordered after) relationship}}
−
{{dsc mem sconst | unordered | nolink=true| title=unordered{{mark|inline constexpr}} | a valid value of the type {{tt|std::partial_ordering}} indicating relationship with an incomparable value}}
+
{{dsc mem sconst|{{dsc small|{{c/core|inline constexpr std::partial_ordering}}}} unordered|nolink=true|a valid value indicating relationship with an incomparable value}}
 
{{dsc end}}
 
{{dsc end}}
  
 
===Conversions===
 
===Conversions===
−
{{tt|std::partial_ordering}} is implicitly-convertible to {{lc|std::weak_equality}}, while both {{lc|std::strong_ordering}} and {{lc|std::weak_ordering}} are implicitly-convertible to {{lc|partial_ordering}}.
+
{{tt|std::partial_ordering}} cannot be implicitly converted to other comparison category types, while both {{lc|std::strong_ordering}} and {{lc|std::weak_ordering}} are implicitly-convertible to {{tt|partial_ordering}}.
  
−
{{dsc begin}}
+
===Comparisons===
−
{{dsc fun | cpp/utility/compare/partial_ordering | inlinemem=true | title=operator weak_equality | implicit conversion to {{lc|std::weak_equality}} }}
+
Comparison operators are defined between values of this type and literal {{c|0}}. This supports the expressions {{c|1=a <=> b == 0}} or {{c|1=a <=> b < 0}} that can be used to convert the result of a three-way comparison operator to a boolean relationship; see  {{ltt|cpp/utility/compare/named comparison functions|std::is_eq}}, {{ltt|cpp/utility/compare/named comparison functions|std::is_lt}}, etc.
−
{{dsc end}}
+
  
−
{{member | {{small|std::strong_equality::}}operator weak_equality | 2=
+
{{cpp/hidden friend|plural=yes|{{tt|std::partial_ordering}}}}
−
{{ddcl | 1=
+
−
constexpr operator weak_equality() const noexcept;
+
−
}}
+
  
−
===Return value===
+
The behavior of a program that attempts to compare a {{tt|partial_ordering}} with anything other than the integer literal {{c|0}} is undefined.
−
{{lc|std::weak_equality::equivalent}} if {{tt|v}} is {{tt|equivalent}}, {{lc|std::weak_equality::nonequivalent}} if {{tt|v}} is {{tt|less}}, {{tt|greater}}, or {{tt|unordered}}.
+
−
}}
+
  
−
===Comparisons===
 
−
Comparison operators are defined between values of this type and literal zero. This supports the expressions {{c|1=a <=> b == 0}} or {{c|1=a <=> b < 0}} that can be used to convert the result of a three-way comparison operator to a boolean relationship; see  {{ltt|cpp/utility/compare/named_comparison_functions|std::is_eq}}, {{ltt|cpp/utility/compare/named_comparison_functions|std::is_lt}}, etc
 
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc fun | cpp/utility/compare/partial_ordering | inlinemem=true | title=operator{{==}}<br>operator!{{=}}<br>operator&lt;<br>operator&gt;<br>operator&lt;{{=}}<br>operator&gt;{{=}} | compares with zero }}
+
{{dsc fun|cpp/utility/compare/partial_ordering|inlinemem=true|title=operator{{==}}<br>operator&lt;<br>operator&gt;<br>operator&lt;{{=}}<br>operator&gt;{{=}}<br>operator<{{=}}>|compares with zero or a {{tt|partial_ordering}}}}
 
{{dsc end}}
 
{{dsc end}}
  
−
{{member | operator{{==}} | 2=
+
{{member|operator{{==}}|2=
−
{{ddcl | 1=
+
{{dcl begin}}
−
friend constexpr bool operator==(partial_ordering v, /*unspecified*/ u) noexcept;
+
{{dcl|num=1|1=
−
friend constexpr bool operator==(/*unspecified*/ u, partial_ordering v) noexcept;
+
friend constexpr bool operator==( partial_ordering v, /*unspecified*/ u ) noexcept;
 
}}
 
}}
 +
{{dcl|num=2|1=
 +
friend constexpr bool
 +
    operator==( partial_ordering v, partial_ordering w ) noexcept = default;
 +
}}
 +
{{dcl end}}
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | v | a {{tt|std::partial_ordering}} value to check}}
+
{{par|v, w|{{tt|std::partial_ordering}} values to check}}
−
{{par | u | an unused parameter of any type that accepts literal zero argument}}
+
{{par|u|an unused parameter of any type that accepts literal zero argument}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
{{c|true}} if {{tt|v}} is {{tt|equivalent}}, {{c|false}} if {{tt|v}} is {{tt|less}}, {{tt|greater}}, or {{tt|unordered}}
+
@1@ {{c|true}} if {{tt|v}} is {{tt|equivalent}}, {{c|false}} if {{tt|v}} is {{tt|less}}, {{tt|greater}}, or {{tt|unordered}}
 +
@2@ {{c|true}} if both parameters hold the same value, {{c|false}} otherwise
 
}}
 
}}
  
−
{{member | operator!{{=}} | 2=
+
{{member|operator&lt;|2=
−
{{ddcl | 1=
+
{{dcl begin}}
−
friend constexpr bool operator!=(partial_ordering v, /*unspecified*/ u) noexcept;
+
{{dcl|num=1|1=
−
friend constexpr bool operator!=(/*unspecified*/ u, partial_ordering v) noexcept;
+
friend constexpr bool operator<( partial_ordering v, /*unspecified*/ u ) noexcept;
 
}}
 
}}
 +
{{dcl|num=2|1=
 +
friend constexpr bool operator<( /*unspecified*/ u, partial_ordering v ) noexcept;
 +
}}
 +
{{dcl end}}
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | v | a {{tt|std::partial_ordering }} value to check}}
+
{{par|v|a {{tt|std::partial_ordering}} value to check}}
−
{{par | u | an unused parameter of any type that accepts literal zero argument}}
+
{{par|u|an unused parameter of any type that accepts literal zero argument}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
{{c|true}} if {{tt|v}} is {{tt|unordered}}, {{tt|less}}, or {{tt|greater}}, and {{c|false}} if {{tt|v}} is {{tt|equivalent}}
+
@1@ {{c|true}} if {{tt|v}} is {{tt|less}}, and {{c|false}} if {{tt|v}} is {{tt|greater}}, {{tt|equivalent}}, or {{tt|unordered}}
 +
@2@ {{c|true}} if {{tt|v}} is {{tt|greater}}, and {{c|false}} if {{tt|v}} is {{tt|less}}, {{tt|equivalent}}, or {{tt|unordered}}
 
}}
 
}}
  
−
{{member | operator&lt; | 2=
+
{{member|operator&lt;{{=}}|2=
−
{{ddcl | 1=
+
{{dcl begin}}
−
friend constexpr bool operator<(partial_ordering v, /*unspecified*/ u) noexcept;
+
{{dcl|num=1|1=
−
friend constexpr bool operator<(/*unspecified*/ u, partial_ordering v) noexcept;
+
friend constexpr bool operator<=( partial_ordering v, /*unspecified*/ u ) noexcept;
 
}}
 
}}
 +
{{dcl|num=2|1=
 +
friend constexpr bool operator<=( /*unspecified*/ u, partial_ordering v ) noexcept;
 +
}}
 +
{{dcl end}}
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | v | a {{tt|std::partial_ordering }} value to check}}
+
{{par|v|a {{tt|std::partial_ordering}} value to check}}
−
{{par | u | an unused parameter of any type that accepts literal zero argument}}
+
{{par|u|an unused parameter of any type that accepts literal zero argument}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
{{c|true}} if {{tt|v}} is {{tt|less}}, and {{c|false}} if {{tt|v}} is {{tt|greater}}, {{tt|equivalent}}, or {{tt|unordered}}
+
@1@ {{c|true}} if {{tt|v}} is {{tt|less}} or {{tt|equivalent}}, and {{c|false}} if {{tt|v}} is {{tt|greater}} or {{tt|unordered}}
 +
@2@ {{c|true}} if {{tt|v}} is {{tt|greater}} or {{tt|equivalent}}, and {{c|false}} if {{tt|v}} is {{tt|less}} or {{tt|unordered}}
 
}}
 
}}
  
−
{{member | operator&lt;{{=}} | 2=
+
{{member|operator&gt;|2=
−
{{ddcl | 1=
+
{{dcl begin}}
−
friend constexpr bool operator<=(partial_ordering v, /*unspecified*/ u) noexcept;
+
{{dcl|num=1|1=
−
friend constexpr bool operator<=(/*unspecified*/ u, partial_ordering v) noexcept;
+
friend constexpr bool operator>( partial_ordering v, /*unspecified*/ u ) noexcept;
 
}}
 
}}
 +
{{dcl|num=2|1=
 +
friend constexpr bool operator>( /*unspecified*/ u, partial_ordering v ) noexcept;
 +
}}
 +
{{dcl end}}
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | v | a {{tt|std::partial_ordering }} value to check}}
+
{{par|v|a {{tt|std::partial_ordering}} value to check}}
−
{{par | u | an unused parameter of any type that accepts literal zero argument}}
+
{{par|u|an unused parameter of any type that accepts literal zero argument}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
{{c|true}} if {{tt|v}} is {{tt|less}} or {{tt|equivalent}}, and {{c|false}} if {{tt|v}} is {{tt|greater}} or {{tt|unordered}}
+
@1@ {{c|true}} if {{tt|v}} is {{tt|greater}}, and {{c|false}} if {{tt|v}} is {{tt|less}}, {{tt|equivalent}}, or {{tt|unordered}}
 +
@2@ {{c|true}} if {{tt|v}} is {{tt|less}}, and {{c|false}} if {{tt|v}} is {{tt|greater}}, {{tt|equivalent}}, or {{tt|unordered}}
 
}}
 
}}
  
−
{{member | operator&gt; | 2=
+
{{member|operator&gt;{{=}}|2=
−
{{ddcl | 1=
+
{{dcl begin}}
−
friend constexpr bool operator>(partial_ordering v, /*unspecified*/ u) noexcept;
+
{{dcl|num=1|1=
−
friend constexpr bool operator>(/*unspecified*/ u, partial_ordering v) noexcept;
+
friend constexpr bool operator>=( partial_ordering v, /*unspecified*/ u ) noexcept;
 
}}
 
}}
 +
{{dcl|num=2|1=
 +
friend constexpr bool operator>=( /*unspecified*/ u, partial_ordering v ) noexcept;
 +
}}
 +
{{dcl end}}
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | v | a {{tt|std::partial_ordering }} value to check}}
+
{{par|v|a {{tt|std::partial_ordering}} value to check}}
−
{{par | u | an unused parameter of any type that accepts literal zero argument}}
+
{{par|u|an unused parameter of any type that accepts literal zero argument}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
{{c|true}} if {{tt|v}} is {{tt|greater}}, and {{c|false}} if {{tt|v}} is {{tt|less}}, {{tt|equivalent}}, or {{tt|unordered}}
+
@1@{{c|true}} if {{tt|v}} is {{tt|greater}} or {{tt|equivalent}}, and {{c|false}} if {{tt|v}} is {{tt|less}} or {{tt|unordered}}
 +
@2@{{c|true}} if {{tt|v}} is {{tt|less}} or {{tt|equivalent}}, and {{c|false}} if {{tt|v}} is {{tt|greater}} or {{tt|unordered}}
 
}}
 
}}
−
 
+
{{member|operator<{{=}}>|2=
−
{{member | operator&gt;{{=}} | 2=
+
{{dcl begin}}
−
{{ddcl | 1=
+
{{dcl|num=1|1=
−
friend constexpr bool operator>=(partial_ordering v, /*unspecified*/ u) noexcept;
+
friend constexpr partial_ordering operator<=>( partial_ordering v, /*unspecified*/ u ) noexcept;
−
friend constexpr bool operator>=(/*unspecified*/ u, partial_ordering v) noexcept;
+
 
}}
 
}}
 +
{{dcl|num=2|1=
 +
friend constexpr partial_ordering operator<=>( /*unspecified*/ u, partial_ordering v ) noexcept;
 +
}}
 +
{{dcl end}}
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | v | a {{tt|std::partial_ordering }} value to check}}
+
{{par|v|a {{tt|std::partial_ordering}} value to check}}
−
{{par | u | an unused parameter of any type that accepts literal zero argument}}
+
{{par|u|an unused parameter of any type that accepts literal zero argument}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
{{c|true}} if {{tt|v}} is {{tt|greater}} or {{tt|equivalent}}, and {{c|false}} if {{tt|v}} is {{tt|less}} or {{tt|unordered}}
+
@1@ {{c|v}}.
 +
@2@ {{tt|greater}} if {{tt|v}} is {{tt|less}}, {{tt|less}} if {{tt|v}} is {{tt|greater}}, otherwise {{tt|v}}.
 
}}
 
}}
 +
 +
===Notes===
 +
The [[cpp/language/operator comparison#Three-way comparison|built-in {{tt|1= operator<=>}}]] between floating-point values uses this ordering: the positive zero and the negative zero compare {{tt|equivalent}}, but can be distinguished, and NaN values compare {{tt|unordered}} with any other value.
  
 
===Example===
 
===Example===
Line 143: Line 168:
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/utility/compare/dsc strong_ordering}}
+
{{dsc inc|cpp/utility/compare/dsc strong_ordering}}
−
{{dsc inc | cpp/utility/compare/dsc weak_ordering}}
+
{{dsc inc|cpp/utility/compare/dsc weak_ordering}}
−
{{dsc inc | cpp/utility/compare/dsc strong_equality}}
+
−
{{dsc inc | cpp/utility/compare/dsc weak_equality}}
+
 
{{dsc end}}
 
{{dsc end}}
  
−
{{langlinks|zh}}
+
{{langlinks|es|ja|ru|zh}}

Latest revision as of 05:04, 12 July 2024

 
C++
 
Utilities library
General utilities
Relational operators (deprecated in C++20)
 
Defined in header <compare>
class partial_ordering;
 (since C++20)

The class type std::partial_ordering is the result type of a three-way comparison that:

  • Admits all six relational operators (==, !=, <, <=, >, >=).
  • Does not imply substitutability: if a is equivalent to b, f(a) may not be equivalent to f(b), where f denotes a function that reads only comparison-salient state that is accessible via the argument's public const members. In other words, equivalent values may be distinguishable.
  • Admits incomparable values: a < b, a == b, and a > b may all be false.

Contents

[edit] Constants

The type std::partial_ordering has four valid values, implemented as const static data members of its type:

Name Definition
inline constexpr std::partial_ordering less
[static]
 a valid value indicating less-than (ordered before) relationship
(public static member constant)
inline constexpr std::partial_ordering equivalent
[static]
 a valid value indicating equivalence (neither ordered before nor ordered after)
(public static member constant)
inline constexpr std::partial_ordering greater
[static]
 a valid value indicating greater-than (ordered after) relationship
(public static member constant)
inline constexpr std::partial_ordering unordered
[static]
 a valid value indicating relationship with an incomparable value
(public static member constant)

[edit] Conversions

std::partial_ordering cannot be implicitly converted to other comparison category types, while both std::strong_ordering and std::weak_ordering are implicitly-convertible to partial_ordering.

[edit] Comparisons

Comparison operators are defined between values of this type and literal ​0​. This supports the expressions a <=> b == 0 or a <=> b < 0 that can be used to convert the result of a three-way comparison operator to a boolean relationship; see std::is_eq, std::is_lt, etc.

These functions are not visible to ordinary unqualified or qualified lookup, and can only be found by argument-dependent lookup when std::partial_ordering is an associated class of the arguments.

The behavior of a program that attempts to compare a partial_ordering with anything other than the integer literal ​0​ is undefined.

operator==operator<operator>operator<=operator>=operator<=>
 compares with zero or a partial_ordering
(function)

operator==

friend constexpr bool operator==( partial_ordering v, /*unspecified*/ u ) noexcept;
 (1)
friend constexpr bool
    operator==( partial_ordering v, partial_ordering w ) noexcept = default;
 (2)

Parameters

v, w - std::partial_ordering values to check
u - an unused parameter of any type that accepts literal zero argument

Return value

1) true if v is equivalent, false if v is less, greater, or unordered
2) true if both parameters hold the same value, false otherwise

operator<

friend constexpr bool operator<( partial_ordering v, /*unspecified*/ u ) noexcept;
 (1)
friend constexpr bool operator<( /*unspecified*/ u, partial_ordering v ) noexcept;
 (2)

Parameters

v - a std::partial_ordering value to check
u - an unused parameter of any type that accepts literal zero argument

Return value

1) true if v is less, and false if v is greater, equivalent, or unordered
2) true if v is greater, and false if v is less, equivalent, or unordered

operator<=

friend constexpr bool operator<=( partial_ordering v, /*unspecified*/ u ) noexcept;
 (1)
friend constexpr bool operator<=( /*unspecified*/ u, partial_ordering v ) noexcept;
 (2)

Parameters

v - a std::partial_ordering value to check
u - an unused parameter of any type that accepts literal zero argument

Return value

1) true if v is less or equivalent, and false if v is greater or unordered
2) true if v is greater or equivalent, and false if v is less or unordered

operator>

friend constexpr bool operator>( partial_ordering v, /*unspecified*/ u ) noexcept;
 (1)
friend constexpr bool operator>( /*unspecified*/ u, partial_ordering v ) noexcept;
 (2)

Parameters

v - a std::partial_ordering value to check
u - an unused parameter of any type that accepts literal zero argument

Return value

1) true if v is greater, and false if v is less, equivalent, or unordered
2) true if v is less, and false if v is greater, equivalent, or unordered

operator>=

friend constexpr bool operator>=( partial_ordering v, /*unspecified*/ u ) noexcept;
 (1)
friend constexpr bool operator>=( /*unspecified*/ u, partial_ordering v ) noexcept;
 (2)

Parameters

v - a std::partial_ordering value to check
u - an unused parameter of any type that accepts literal zero argument

Return value

1) true if v is greater or equivalent, and false if v is less or unordered
2) true if v is less or equivalent, and false if v is greater or unordered

operator<=>

friend constexpr partial_ordering operator<=>( partial_ordering v, /*unspecified*/ u ) noexcept;
 (1)
friend constexpr partial_ordering operator<=>( /*unspecified*/ u, partial_ordering v ) noexcept;
 (2)

Parameters

v - a std::partial_ordering value to check
u - an unused parameter of any type that accepts literal zero argument

Return value

1) v.
2) greater if v is less, less if v is greater, otherwise v.

[edit] Notes

The built-in operator<=> between floating-point values uses this ordering: the positive zero and the negative zero compare equivalent, but can be distinguished, and NaN values compare unordered with any other value.

[edit] Example

This section is incomplete
Reason: no example

[edit] See also

(C++20)
 the result type of 3-way comparison that supports all 6 operators and is substitutable
(class) [edit]
(C++20)
 the result type of 3-way comparison that supports all 6 operators and is not substitutable
(class) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/utility/compare/partial_ordering&oldid=173504"