"""The general contract for values whose magnitude can be compared. `Comparable` imposes a total ordering upon instances of any type that satisfies the interface. If a type `T` satisfies `Comparable<T>`, then instances of `T` may be compared using the comparison operators `<`, `>`, `<=`, `>=`. assert (x>=0.0); A _ternary comparison_ is useful for asserting lower and upper bounds. assert (0.0<=x<1.0); Finally, the _compare_ operator `<=>` may be used to produce an instance of [[Comparison]]. switch (x<=>y) case (equal) { print("same same"); } case (smaller) { print("x smaller"); } case (larger) { print("y smaller"); } The total order of a type must be consistent with the definition of equality for the type. That is, there are three mutually exclusive possibilities: - `x<y`, - `x>y`, or - `x==y` (These possibilities are expressed by the enumerated instances [[smaller]], [[larger]], and [[equal]] of `Comparison`.) The order imposed by `Comparable` is sometimes called the _natural order_ of a type, to reflect the fact that any function of type `Comparison(T,T)` might determine a different order. Thus, some order-related operations come in two flavors: a flavor that depends upon the natural order, and a flavor which accepts an arbitrary comparator function. Examples are: - [[sort]] vs [[Iterable.sort]] and - [[max]] vs [[Iterable.max]].""" see (`class Comparison`, `function sort`, `function max`, `function min`, `function largest`, `function smallest`) by ("Gavin") tagged("Comparisons") shared interface Comparable<in Other> of Other given Other satisfies Comparable<Other> { "Compares this value with the given value, returning: - [[larger]], if this value is strictly larger than the given value, - [[smaller]], if this value is strictly smaller than the given value, or - [[equal]], if this value is [[equal|equals]] to the given value. For any two values `x` and `y` such that the expression `x.compare(y)` is well-typed, the expression may be written: x <=> y Implementations must respect the constraints that: - `x==y` if and only if `x<=>y == equal` (consistency with `equals()`), - if `x>y` then `y<x` (symmetry), and - if `x>y` and `y>z` then `x>z` (transitivity)." see (`function equals`) shared formal Comparison compare(Other other); "Determines if this value is strictly larger than the given value." since("1.1.0") shared default Boolean largerThan(Other other) => compare(other)===larger; "Determines if this value is strictly smaller than the given value." since("1.1.0") shared default Boolean smallerThan(Other other) => compare(other)===smaller; "Determines if this value is larger than or equal to the given value." since("1.1.0") shared default Boolean notSmallerThan(Other other) => !compare(other)===smaller; "Determines if this value is smaller than or equal to the given value." since("1.1.0") shared default Boolean notLargerThan(Other other) => !compare(other)===larger; }