package numeric_string

  1. Overview
  2. Docs
Module type
Class type
type t = Base.string

Numeric string comparison, also sometimes called "natural comparison", is the string ordering that orders numeric subcomponents as numbers, so that e.g. "xyz2" comes before "xyz10", rather than after (as it does when they are compared as plain strings). As a spec this is incomplete, and various implementations around the web fill in the missing details differently. This one errs on the side of doing less, rather than more, and in particular doesn't do any special handling of minus signs or decimal points.

Precisely: first, split both input strings into a possibly-empty initial segment of non-numeric characters, followed by alternating non-empty segments of numeric characters and non-numeric characters. Then compare corresponding segments, using string comparison on non-numeric segments and integer comparison on numeric segments; if you run out of segments on one side, the shorter segment list compares smaller. (Allowing the initial non-numeric segment to be empty ensures we always compare corresponding segments of the same kind).

Leading zeroes in numeric components complicate the above spec a little, since they mean two distinct strings can have equal numeric value. The choice we make is to sort by numeric value first, but break ties by string length, so that e.g. "1" < "01" < "2" < "02". This ensures that numeric string equality coincides with ordinary string equality, so that e.g. sets and maps of strings behave as you'd expect (although they have distinct serializations / orderings, so they're not identical). See the README for more discussion.

The comparison functions do not allocate, so that they can be used in as wide a variety of contexts as possible.

include Base.Comparable.S with type t := t
include Base.Comparisons.S with type t := t
include Base.Comparisons.Infix with type t := t
val (>=) : t -> t -> bool
val (<=) : t -> t -> bool
val (=) : t -> t -> bool
val (>) : t -> t -> bool
val (<) : t -> t -> bool
val (<>) : t -> t -> bool
val equal : t -> t -> bool
val compare : t -> t -> int

compare t1 t2 returns 0 if t1 is equal to t2, a negative integer if t1 is less than t2, and a positive integer if t1 is greater than t2.

val min : t -> t -> t
val max : t -> t -> t
val ascending : t -> t -> int

ascending is identical to compare. descending x y = ascending y x. These are intended to be mnemonic when used like List.sort ~compare:ascending and List.sort ~cmp:descending, since they cause the list to be sorted in ascending or descending order, respectively.

val descending : t -> t -> int
val between : t -> low:t -> high:t -> bool

between t ~low ~high means low <= t <= high

val clamp_exn : t -> min:t -> max:t -> t

clamp_exn t ~min ~max returns t', the closest value to t such that between t' ~low:min ~high:max is true.

Raises if not (min <= max).

val clamp : t -> min:t -> max:t -> t Base.Or_error.t
include Base.Comparator.S with type t := t
type comparator_witness
include Base.Sexpable.S with type t := t
val t_of_sexp : Sexplib0.Sexp.t -> t
val sexp_of_t : t -> Sexplib0.Sexp.t