[feature] libbase: Taking an element to show the difference between …

…two set/map

    Usefull to explain why two sets are not equal.

libbase/baseMap.ml

@@ -580,6 +580,16 @@ struct
     | Empty -> None
     | Node(_, k, v, _r, _) -> Some (k, v)
 
+  let example_diff s1 s2 =
+    let diff_ = diff s1 s2 in
+    match choose_opt diff_ with
+    | Some elt -> Some elt
+    | None ->
+        let diff = diff s2 s1 in
+        match choose_opt diff with
+        | Some elt -> Some elt
+        | None -> None
+
   let from_sorted_array keys vals =
     let len_keys = Array.length keys in
     let len_vals = Array.length vals in

libbase/baseMapSig.ml

@@ -208,6 +208,13 @@ sig
   *)
   val diff2 : 'a t -> _ t -> _ t -> 'a t
 
+  (**
+     If the two set have different key, give back an element in the left set not
+     in the right one, or in the right one not in the left one, or None.
+     See also [BaseSetSig.S.example_diff]
+  *)
+  val example_diff : 'a t -> 'a t -> (key * 'a) option
+
   (**
      Optimized initialization for huge maps, to avoid temporary unused balancing.
      The key array should be sorted in increasing order, using the same order than the set.

libbase/baseSet.ml

@@ -325,6 +325,16 @@ struct
     | Empty -> None
     | Node (_, v, _r, _) -> Some v
 
+  let example_diff s1 s2 =
+    let diff_ = diff s1 s2 in
+    match choose_opt diff_ with
+    | Some elt -> Some elt
+    | None ->
+        let diff = diff s2 s1 in
+        match choose_opt diff with
+        | Some elt -> Some elt
+        | None -> None
+
   let complete_join big small =
     fold add small big
 

libbase/baseSetSig.ml

@@ -67,6 +67,15 @@ sig
      Returns an arbitrary element of the set if it is not empty
   *)
   val choose_opt : t -> elt option
+
+  (**
+     If the two set are different, give back an element in the left set not in
+     the right one, or in the right one not in the left one, or None
+     We cannot use there [elt Base.either option], because this would create
+     a circular build. If needed, we can return a variant indicating where
+     the element was found.
+  *)
+  val example_diff : t -> t -> elt option
   val split : elt -> t -> t * bool * t
   val draw : t -> elt * t
   val size : t -> int

libbase/intMap.ml

@@ -463,4 +463,14 @@ let diff2 map1 map2 map3 =
             add k v acc
        ) map1 empty
 
+  let example_diff s1 s2 =
+    let diff_ = diff s1 s2 in
+    match choose_opt diff_ with
+    | Some elt -> Some elt
+    | None ->
+        let diff = diff s2 s1 in
+        match choose_opt diff with
+        | Some elt -> Some elt
+        | None -> None
+
 let from_sorted_array _ = assert false

libbase/intSet.ml

@@ -76,6 +76,16 @@ let choose_opt (set:t) =
   | None -> None
   | Some (a, _) -> Some a
 
+let example_diff s1 s2 =
+  let diff_ = diff s1 s2 in
+  match choose_opt diff_ with
+  | Some elt -> Some elt
+  | None ->
+      let diff = diff s2 s1 in
+      match choose_opt diff with
+      | Some elt -> Some elt
+      | None -> None
+
 let split int set =
   fold
     (fun i (inf, b, sup) ->