Merge pull request #2768 from cristianoc/sets_maps_mli_cleanup

[Belt] More consistency in mli for Maps and Sets.

Author: bobzhang

jscomp/others/belt_MapDict.mli

@@ -22,7 +22,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *)
 
-type ('key,  'value, 'id) t
+type ('key, 'value, 'id) t
 
 type ('key, 'id) cmp = ('key, 'id) Belt_Id.cmp
 
@@ -31,119 +31,140 @@ val empty: ('k, 'v, 'id) t
 val isEmpty: ('k, 'v, 'id) t -> bool
 
 val has:
-  ('k, 'a, 'id) t -> 'k  ->
-  cmp:('k, 'id) cmp -> 
-  bool    
+  ('k, 'a, 'id) t -> 'k ->
+  cmp:('k, 'id) cmp ->
+  bool
 
-val cmpU: 
-    ('k, 'v, 'id) t -> 
+val cmpU:
+    ('k, 'v, 'id) t ->
     ('k, 'v, 'id) t ->
     kcmp:('k, 'id) cmp ->
     vcmp:('v -> 'v -> int [@bs]) -> 
      int
 val cmp: 
-    ('k, 'v, 'id) t -> 
+    ('k, 'v, 'id) t ->
     ('k, 'v, 'id) t ->
     kcmp:('k, 'id) cmp ->
-    vcmp:('v -> 'v -> int) -> 
+    vcmp:('v -> 'v -> int) ->
      int
 
-val eqU:  
-    ('k, 'a, 'id) t -> 
+val eqU:
+    ('k, 'a, 'id) t ->
     ('k, 'a, 'id) t ->
     kcmp:('k, 'id) cmp ->
-    veq:('a -> 'a -> bool [@bs]) -> 
+    veq:('a -> 'a -> bool [@bs]) ->
     bool
-val eq:  
-    ('k, 'a, 'id) t -> 
+val eq:
+    ('k, 'a, 'id) t ->
     ('k, 'a, 'id) t ->
     kcmp:('k, 'id) cmp ->
-    veq:('a -> 'a -> bool) -> 
+    veq:('a -> 'a -> bool) ->
     bool
 (** [eq m1 m2 cmp] tests whether the maps [m1] and [m2] are
     equal, that is, contain equal keys and associate them with
     equal data.  [cmp] is the equality predicate used to compare
     the data associated with the keys. *)
-    
-val forEachU:  ('k, 'a, 'id) t -> ('k -> 'a -> unit [@bs]) -> unit
-val forEach:  ('k, 'a, 'id) t -> ('k -> 'a -> unit) -> unit  
+
+val forEachU: ('k, 'a, 'id) t -> ('k -> 'a -> unit [@bs]) -> unit
+val forEach: ('k, 'a, 'id) t -> ('k -> 'a -> unit) -> unit
 (** [forEach m f] applies [f] to all bindings in map [m].
-    [f] receives the 'k as first argument, and the associated value
-    as second argument.  The bindings are passed to [f] in increasing
+    [f] receives the key as first argument, and the associated value
+    as second argument. The bindings are passed to [f] in increasing
     order with respect to the ordering over the type of the keys. *)
-    
-val reduceU: ('k, 'a, 'id) t -> 'b ->  ('b -> 'k -> 'a -> 'b [@bs]) ->  'b
-val reduce: ('k, 'a, 'id) t -> 'b ->  ('b -> 'k -> 'a -> 'b) ->  'b  
+
+val reduceU: ('k, 'a, 'id) t -> 'b -> ('b -> 'k -> 'a -> 'b [@bs]) -> 'b
+val reduce: ('k, 'a, 'id) t -> 'b -> ('b -> 'k -> 'a -> 'b) -> 'b
 (** [reduce m a f] computes [(f kN dN ... (f k1 d1 a)...)],
     where [k1 ... kN] are the keys of all bindings in [m]
     (in increasing order), and [d1 ... dN] are the associated data. *)
 
-val everyU: ('k, 'a, 'id) t -> ('k -> 'a -> bool [@bs]) ->  bool
-val every: ('k, 'a, 'id) t -> ('k -> 'a -> bool) ->  bool  
+val everyU: ('k, 'a, 'id) t -> ('k -> 'a -> bool [@bs]) -> bool
+val every: ('k, 'a, 'id) t -> ('k -> 'a -> bool) -> bool
 (** [every m p] checks if all the bindings of the map
     satisfy the predicate [p]. Order unspecified *)
-    
-val someU: ('k, 'a, 'id) t -> ('k -> 'a -> bool [@bs]) ->  bool
-val some: ('k, 'a, 'id) t -> ('k -> 'a -> bool) ->  bool  
+
+val someU: ('k, 'a, 'id) t -> ('k -> 'a -> bool [@bs]) -> bool
+val some: ('k, 'a, 'id) t -> ('k -> 'a -> bool) -> bool
 (** [some m p] checks if at least one binding of the map
     satisfy the predicate [p]. Order unspecified *)
 
 val size: ('k, 'a, 'id) t -> int
+
 val toList: ('k, 'a, 'id) t -> ('k * 'a) list
-(** In increasing order*)
+(** In increasing order. *)
+
 val toArray: ('k, 'a, 'id) t -> ('k * 'a) array
+
 val ofArray: ('k * 'a) array -> cmp:('k,'id) cmp -> ('k,'a,'id) t
 [@@ocaml.deprecated "Use fromArray instead"]
+
 val fromArray: ('k * 'a) array -> cmp:('k,'id) cmp -> ('k,'a,'id) t
-val keysToArray: ('k, 'a, 'id) t -> 'k  array
-val valuesToArray: ('k, 'a, 'id) t -> 'a  array
+
+val keysToArray: ('k, 'a, 'id) t -> 'k array
+
+val valuesToArray: ('k, 'a, 'id) t -> 'a array
+
 val minKey: ('k, _, _) t -> 'k option
+
 val minKeyUndefined: ('k, _, _) t -> 'k Js.undefined
+
 val maxKey: ('k, _, _) t -> 'k option
+
 val maxKeyUndefined: ('k, _, _) t -> 'k Js.undefined
-val minimum: ('k, 'a,  _) t -> ('k * 'a) option
+
+val minimum: ('k, 'a, _) t -> ('k * 'a) option
+
 val minUndefined: ('k, 'a, _) t -> ('k * 'a) Js.undefined
+
 val maximum: ('k, 'a, _) t -> ('k * 'a) option
+
 val maxUndefined:('k, 'a, _) t -> ('k * 'a) Js.undefined
+
 val get:
   ('k, 'a, 'id) t -> 'k ->
-  cmp:('k, 'id) cmp -> 
+  cmp:('k, 'id) cmp ->
   'a option
+
 val getUndefined:
   ('k, 'a, 'id) t -> 'k ->
   cmp:('k, 'id) cmp ->
   'a Js.undefined
-    
+
 val getWithDefault:
-    ('k, 'a, 'id) t -> 'k ->  'a ->
+    ('k, 'a, 'id) t -> 'k -> 'a ->
     cmp:('k, 'id) cmp ->
-    'a 
+    'a
+
 val getExn:
   ('k, 'a, 'id) t -> 'k ->
   cmp:('k, 'id) cmp ->
   'a
-  
+
 val checkInvariantInternal: _ t -> unit
 (**
    {b raise} when invariant is not held
-*)  
+*)
 
 val remove:
   ('a, 'b, 'id) t -> 'a ->
   cmp:('a, 'id) cmp ->
   ('a, 'b, 'id) t
-
+(** [remove m x] returns a map containing the same bindings as
+   [m], except for [x] which is unbound in the returned map. *)
 
 val removeMany:
   ('a, 'b, 'id) t ->
   'a array ->
   cmp:('a, 'id) cmp ->
   ('a, 'b, 'id) t
-  
+
 val set:
   ('a, 'b, 'id) t -> 'a -> 'b ->
   cmp:('a, 'id) cmp ->
   ('a, 'b, 'id) t
+(** [add m x y] returns a map containing the same bindings as
+   [m], plus a binding of [x] to [y]. If [x] was already bound
+   in [m], its previous binding disappears. *)
 
 val updateU:
   ('a, 'b, 'id) t ->
@@ -160,37 +181,41 @@ val update:
 
 val mergeU:
   ('a, 'b, 'id) t ->
-  ('a, 'c, 'id) t -> 
+  ('a, 'c, 'id) t ->
   ('a -> 'b option -> 'c option -> 'd option [@bs]) ->
   cmp:('a, 'id) cmp -> ('a, 'd, 'id) t
 val merge:
   ('a, 'b, 'id) t ->
-  ('a, 'c, 'id) t -> 
+  ('a, 'c, 'id) t ->
   ('a -> 'b option -> 'c option -> 'd option) ->
   cmp:('a, 'id) cmp -> ('a, 'd, 'id) t
+(** [merge m1 m2 f] computes a map whose keys is a subset of keys of [m1]
+    and of [m2]. The presence of each such binding, and the corresponding
+    value, is determined with the function [f].
+ *)
 
 val mergeMany:
   ('a, 'b, 'id) t ->
   ('a * 'b) array ->
   cmp:('a, 'id) cmp ->
   ('a, 'b, 'id) t
 
-val keepU: 
-    ('k, 'a, 'id) t -> 
-    ('k -> 'a -> bool [@bs]) -> 
+val keepU:
+    ('k, 'a, 'id) t ->
+    ('k -> 'a -> bool [@bs]) ->
     ('k, 'a, 'id) t
-val keep: 
-    ('k, 'a, 'id) t -> 
-    ('k -> 'a -> bool) -> 
+val keep:
+    ('k, 'a, 'id) t ->
+    ('k -> 'a -> bool) ->
     ('k, 'a, 'id) t
 (** [keep m p] returns the map with all the bindings in [m]
     that satisfy predicate [p]. *)
-    
-val partitionU: 
+
+val partitionU:
     ('k, 'a, 'id) t ->
-    ('k -> 'a -> bool [@bs]) -> 
+    ('k -> 'a -> bool [@bs]) ->
     ('k, 'a, 'id) t * ('k, 'a, 'id) t
-val partition: 
+val partition:
     ('k, 'a, 'id) t ->
     ('k -> 'a -> bool) -> 
     ('k, 'a, 'id) t * ('k, 'a, 'id) t
@@ -205,10 +230,17 @@ val split:
   'a ->
   cmp:('a, 'id) cmp ->
   (('a,'b,'id) t * ('a, 'b, 'id) t) * 'b option
-
-
-val mapU: ('k, 'a, 'id) t -> ('a -> 'b [@bs]) ->  ('k ,'b,'id ) t
-val map: ('k, 'a, 'id) t -> ('a -> 'b) ->  ('k ,'b,'id ) t    
+(** [split x m] returns a triple [(l, data, r)], where
+      [l] is the map with all the bindings of [m] whose key
+    is strictly less than [x];
+      [r] is the map with all the bindings of [m] whose key
+    is strictly greater than [x];
+      [data] is [None] if [m] contains no binding for [x],
+      or [Some v] if [m] binds [v] to [x].
+ *)
+
+val mapU: ('k, 'a, 'id) t -> ('a -> 'b [@bs]) -> ('k ,'b,'id) t
+val map: ('k, 'a, 'id) t -> ('a -> 'b) -> ('k ,'b,'id) t
 (** [map m f] returns a map with same domain as [m], where the
     associated value [a] of all bindings of [m] has been
     replaced by the result of the application of [f] to [a].

jscomp/others/belt_MapInt.ml

@@ -140,7 +140,7 @@ let removeMany t keys =
   | None -> N.empty
   | Some t ->  removeMany0 t keys 0 len
 
-let mergeArray h arr =   
+let mergeMany h arr =   
   let len = A.length arr in 
   let v = ref h in  
   for i = 0 to len - 1 do 
@@ -149,6 +149,8 @@ let mergeArray h arr =
   done ;
   !v 
 
+let mergeArray = mergeMany
+
 let has = I.has
 let cmpU = I.cmpU
 let cmp = I.cmp