GHC.Internal.Data.Ord

The Ord class is used for totally ordered datatypes.

Instances of Ord can be derived for any user-defined datatype whose constituent types are in Ord. The declared order of the constructors in the data declaration determines the ordering in derived Ord instances. The Ordering datatype allows a single comparison to determine the precise ordering of two objects.

Ord, as defined by the Haskell report, implements a total order and has the following properties:

Comparability

x <= y || y <= x

=

True

Transitivity

if

x <= y && y <= z

=

True

, then

x <= z

=

True

Reflexivity

x <= x

=

True

Antisymmetry

if

x <= y && y <= x

=

True

, then

x == y

=

True

The following operator interactions are expected to hold:

1. x >= y = y <= x

2. x < y = x <= y && x /= y

3. x > y = y < x

4. x < y = compare x y == LT

5. x > y = compare x y == GT

6. x == y = compare x y == EQ

7. min x y == if x <= y then x else y = True

8. max x y == if x >= y then x else y = True

Note that (7.) and (8.) do not require min and max to return either of their arguments. The result is merely required to equal one of the arguments in terms of (==).

Minimal complete definition: either compare or <=. Using compare can be more efficient for complex types.

The Down type allows you to reverse sort order conveniently. A value of type Down a contains a value of type a (represented as Down a).

If a has an Ord instance associated with it then comparing two values thus wrapped will give you the opposite of their normal sort order. This is particularly useful when sorting in generalised list comprehensions, as in: then sortWith by Down x.

>>> compare True FalseGT

>>> compare (Down True) (Down False)LT

If a has a Bounded instance then the wrapped instance also respects the reversed ordering by exchanging the values of minBound and maxBound.

>>> minBound :: Int-9223372036854775808

>>> minBound :: Down IntDown 9223372036854775807

All other instances of Down a behave as they do for a.

comparing p x y = compare (p x) (p y)

Useful combinator for use in conjunction with the xxxBy family of functions from Data.List, for example:

  ... sortBy (comparing fst) ...

clamp (low, high) a = min high (max a low)

Function for ensuring the value a is within the inclusive bounds given by low and high. If it is, a is returned unchanged. The result is otherwise low if a <= low, or high if high <= a.

When clamp is used at Double and Float, it has NaN propagating semantics in its second argument. That is, clamp (l,h) NaN = NaN, but clamp (NaN, NaN) x = x.

>>> clamp (0, 10) 22

>>> clamp ('a', 'm') 'x''m'