Comparisons

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()`.

By: Gavin
See also `Comparison`, `sort()`, `max()`, `min()`, `largest()`, `smallest()`

no type hierarchy

no supertypes hierarchy

- `Comparable` of
  - `Character`
  - `Number`
    - `Float`
    - `Integral`
      - `Integer`
  - `String`

Inherited Attributes
Attributes inherited from: `Object` `hash`, `string`

Methods
`compare` | Source Code `shared formal Comparison compare(Other 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 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 also `Object.equals()`
`largerThan` | Source Code `shared default Boolean largerThan(Other other)` Determines if this value is strictly larger than the given value. Since 1.1.0
`notLargerThan` | Source Code `shared default Boolean notLargerThan(Other other)` Determines if this value is smaller than or equal to the given value. Since 1.1.0
`notSmallerThan` | Source Code `shared default Boolean notSmallerThan(Other other)` Determines if this value is larger than or equal to the given value. Since 1.1.0
`smallerThan` | Source Code `shared default Boolean smallerThan(Other other)` Determines if this value is strictly smaller than the given value. Since 1.1.0

Inherited Methods
Methods inherited from: `Object` `equals()`