"""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; 
    
}
​