List.equal, List.compare (#9668)

`List.equal f foo bar` is nicer than
`List.length foo = List.length bar && List.for_all2 f foo bar`.

Note: with List.compare there is a risk of users having opened the
List module, and then using 'compare' from the stdlib unqualified. For
example:

    List.(sort compare foo bar)

Such code will break (type error), and has to be fixed by using
Stdlib.compare. Stdlib is available since OCaml 4.07; people wishing
to support both 4.12 and older releases would have to avoid opening
List, or rebind 'compare' locally.

1 files changed, 32 insertions, 0 deletions

diff --git a/stdlib/listLabels.mli b/stdlib/listLabels.mli
index f3a5098dd5..2067340263 100644
--- a/stdlib/listLabels.mli
+++ b/stdlib/listLabels.mli
@@ -123,6 +123,38 @@ val flatten : 'a list list -> 'a list
  *)
 
 
+(** {1 Comparison} *)
+
+val equal : eq:('a -> 'a -> bool) -> 'a list -> 'a list -> bool
+(** [equal eq [a1; ...; an] [b1; ..; bm]] holds when
+    the two input lists have the same length, and for each
+    pair of elements [ai], [bi] at the same position we have
+    [eq ai bi].
+
+    Note: the [eq] function may be called even if the
+    lists have different length. If you know your equality
+    function is costly, you may want to check {!compare_lengths}
+    first.
+
+    @since 4.12.0
+*)
+
+val compare : cmp:('a -> 'a -> int) -> 'a list -> 'a list -> int
+(** [compare cmp [a1; ...; an] [b1; ...; bm]] performs
+    a lexicographic comparison of the two input lists,
+    using the same ['a -> 'a -> int] interface as {!Stdlib.compare}:
+
+    - [a1 :: l1] is smaller than [a2 :: l2] (negative result)
+      if [a1] is smaller than [a2], or if they are equal (0 result)
+      and [l1] is smaller than [l2]
+    - the empty list [[]] is strictly smaller than non-empty lists
+
+    Note: the [cmp] function will be called even if the lists have
+    different lengths.
+
+    @since 4.12.0
+*)
+
 (** {1 Iterators} *)