Module Order.Comparator

Module for the comparator function type. Includes implementations for common data types.

type 'a t = 'a comparator

The type of order comparison functions.

val unit : unit comparator

Order comparison function for values of type unit.

val bool : bool comparator

Order comparison function for values of type bool.

val char : char comparator

Order comparison function for values of type char.

val int : int comparator

Order comparison function for values of type int.

val int32 : int32 comparator

Order comparison function for values of type int32.

val int64 : int64 comparator

Order comparison function for values of type int64.

val float : float comparator

Order comparison function for values of type float.

val string : string comparator

Order comparison function for values of type string.

val list : 'a comparator -> 'a list comparator

Order comparison function for values of type list.

val array : 'a comparator -> 'a array comparator

Order comparison function for values of type array.

val option : 'a comparator -> 'a option comparator

Order comparison function for values of type option.

val result : 'a comparator -> 'b comparator -> ('a'b) Result.result comparator

Order comparison function for values of type result.

val ref : 'a comparator -> 'a Pervasives.ref comparator

Order comparison function for values of type ref.

val pair : 'a comparator -> 'b comparator -> ('a * 'b) comparator

Order comparison function for pairs of type 'a * 'b.

val triple : 'a comparator -> 'b comparator -> 'c comparator -> ('a * 'b * 'c) comparator

Order comparison function for triples of type 'a * 'b * 'c.

val invert : 'a comparator -> 'a comparator

Inverts a given comparator function.

See also: descending, ascending

Examples

let result =
  [1; 2; 3; 4; 5]
  |> List.sort (Comparator.(invert int |> to_integral)) in
assert (Equality.(list int) result [5; 4; 3; 2; 1])
val descending : 'a comparator -> 'a comparator
val ascending : 'a comparator -> 'a comparator

Ascending and descending comparators are intended to be mnemonic when used to sort elements: List.sort ~by:Comparator.(descending int).

  • descending is an alias for invert.
  • ascending is identity.
val by : ('a -> 'b) -> 'b comparator -> 'a comparator

by f comparator is a comparator that applies the projection function f before applying comparator.

This function can be used to, for example, extract fields or apply transformations on values before comparing them. The provided comparator function will be applied to the values produced by f.

Examples

let l1 = [1; 2; 3; 4; 5] in
let l2 = [1; 2; 3] in
let compare_by_length = by List.length Comparator.int in
assert (Ordering.is_greater (compare_by_length l1 l2))
val lexical : 'a comparator list -> 'a comparator

Performs a lexical comparison using a list of comparators.

(lexical comparators) a1 a2 compares the values a1 and a2 by sequentially applying functions in the comparators list. The comparison terminates as soon as the first non-Equal ordering is produced by a comparator. If the provided comparators list is empty the values are considered to be equal.

Combined with "by" this function can be used to define comparator functions for records, tuples or other complex data types.

Examples

type player = {
  name: string;
  score: int;
  health: float;
}

(* Field getters. *)
let name t = t.name
let score t = t.score
let health t = t.health

(* Compare by score, health, name. *)
let compare_players =
  let open Comparator in
  lexical [
    by score int;
    by health float;
    by name string;
  ]
val to_integral : 'a comparator -> 'a -> 'a -> int

to_integral compare produces a comparator-like function that denotes ordering by integers.

Note: This function produces comparators compatible with OCaml's standard library.

The following mapping is used:

  • Less is -1
  • Equal is 0
  • Greater is 1