document different in cmp between array and list, make reduceReverse stack safe, more docs/tests

Author: bobzhang

jscomp/others/belt_Array.ml

@@ -327,6 +327,17 @@ let reduceReverseU a x f =
 
 let reduceReverse a x f = reduceReverseU a x (fun[@bs] a b -> f a b)
 
+let reduceReverse2U a b x f =
+  let r = ref x in
+  let len = min (length a) (length b) in
+  for i = len - 1 downto  0 do
+    r := f !r (getUnsafe a i) (getUnsafe b i) [@bs]
+  done;
+  !r 
+
+let reduceReverse2 a b x f =
+  reduceReverse2U a b x (fun [@bs] a b c -> f a b c)
+
 let rec everyAux arr i b len =   
   if i = len then true 
   else if b (getUnsafe arr i) [@bs] then 

jscomp/others/belt_Array.mli

@@ -300,6 +300,16 @@ val reduceReverse: 'b array -> 'a -> ('a -> 'b ->  'a ) ->  'a
     ]}
 *)
 
+val reduceReverse2U:
+  'a array -> 'b array -> 'c  -> ('c -> 'a -> 'b ->  'c [@bs]) ->  'c
+val reduceReverse2:  
+  'a array -> 'b array -> 'c  -> ('c -> 'a -> 'b ->  'c) ->  'c
+(**
+   @example {[
+     reduceReverse2 [|1;2;3|] [|1;2|] 0 (fun acc x y -> acc + x + y) = 6
+   ]}
+*)
+  
 val someU: 'a array -> ('a -> bool [@bs]) -> bool
 val some: 'a array -> ('a -> bool) -> bool
 (** [some xs p]

jscomp/others/belt_List.ml

@@ -511,11 +511,19 @@ let rec reduceU l accu f   =
 let reduce l accu f =   
   reduceU l accu (fun[@bs] acc x -> f acc x )
 
-let rec reduceReverseU l accu f  =
+
+let rec reduceReverseUnsafeU l accu f  =
   match l with
     [] -> accu
-  | a::l -> f a (reduceReverseU l accu f) [@bs]
+  | a::l -> f (reduceReverseUnsafeU l accu f) a [@bs]
 
+let reduceReverseU (type a ) (type b) (l : a list) (acc : b) f =
+  let len = length  l in
+  if len < 1000 then
+    reduceReverseUnsafeU l acc f
+  else
+    A.reduceReverseU (toArray l) acc f
+      
 let reduceReverse l accu f =   
   reduceReverseU l accu (fun [@bs] a b -> f a b)
 
@@ -544,13 +552,23 @@ let rec reduce2U l1 l2 accu f =
 
 let reduce2 l1 l2 acc f = reduce2U l1 l2 acc (fun[@bs] a b c -> f a b c )  
 
-let rec reduceReverse2U l1 l2 accu f  =
+let rec reduceReverse2UnsafeU l1 l2 accu f  =
   match (l1, l2) with
     ([], []) -> accu
-  | (a1::l1, a2::l2) -> f a1 a2 (reduceReverse2U l1 l2 accu f) [@bs]
+  | (a1::l1, a2::l2) ->
+    f (reduceReverse2UnsafeU l1 l2 accu f)  a1 a2 [@bs]
   | _, [] | [], _ -> accu
 
-let reduceReverse2 l1 l2 acc f = reduceReverse2U l1 l2 acc (fun [@bs] a b c -> f a b c)  
+let reduceReverse2U (type a ) (type b ) (type c)
+    (l1 : a list) (l2 : b list) (acc : c) f  =
+  let len = length l1 in
+  if len < 1000 then
+    reduceReverse2UnsafeU l1 l2 acc f
+  else
+    A.reduceReverse2U (toArray l1) (toArray l2) acc f
+      
+let reduceReverse2 l1 l2 acc f =
+  reduceReverse2U l1 l2 acc (fun [@bs] a b c -> f a b c)  
 
 let rec everyU xs p = 
   match xs with 
@@ -573,6 +591,14 @@ let rec every2U l1 l2  p =
 
 let every2 l1 l2 p = every2U l1 l2 (fun[@bs] a b -> p a b)  
 
+let rec cmpByLength l1 l2 = 
+  match l1, l2 with
+  | [], [] -> 0
+  | _,  [] -> 1
+  | [], _ -> -1
+  | _ :: l1s , _ :: l2s ->
+    cmpByLength l1s l2s
+               
 let rec cmpU l1 l2  p =
   match (l1, l2) with
   | [], [] -> 0
@@ -583,9 +609,10 @@ let rec cmpU l1 l2  p =
     if c = 0 then
       cmpU l1 l2 p
     else c
-      
+
 let cmp l1 l2 f = cmpU l1 l2 (fun [@bs] x y -> f x y)    
 
+
 let rec eqU l1 l2  p =
   match (l1, l2) with
   | [], [] -> true

jscomp/others/belt_List.mli

@@ -304,8 +304,8 @@ val reduce:  'a t -> 'b -> ('b -> 'a -> 'b) -> 'b
     ]}
 *)
 
-val reduceReverseU: 'a t -> 'b -> ('a -> 'b -> 'b [@bs]) -> 'b
-val reduceReverse: 'a t -> 'b -> ('a -> 'b -> 'b) -> 'b
+val reduceReverseU: 'a t -> 'b -> ('b -> 'a ->  'b [@bs]) -> 'b
+val reduceReverse: 'a t -> 'b -> ('b -> 'a ->  'b) -> 'b
 (** [reduceReverse xs f]
 
     @example {[
@@ -342,9 +342,9 @@ val reduce2:
 *)
 
 val reduceReverse2U:
-  'a t -> 'b t -> 'c -> ('a -> 'b -> 'c -> 'c [@bs]) -> 'c
+  'a t -> 'b t -> 'c -> ('c -> 'a -> 'b ->  'c [@bs]) -> 'c
 val reduceReverse2:
-  'a t -> 'b t -> 'c -> ('a -> 'b -> 'c -> 'c) -> 'c
+  'a t -> 'b t -> 'c -> ('c -> 'a -> 'b ->  'c) -> 'c
 (**
    [reduceReverse2 xs ys init f ]
 
@@ -391,14 +391,26 @@ val some2:  'a t -> 'b t -> ('a -> 'b -> bool) -> bool
       (some2 [2;3] [1;4] (fun   x y -> x > y)) = true;;
     ]}
 *)
+
+val cmpByLength: 'a t -> 'a t -> int
+(** [cmpByLength l1 l2]
+
+    Compare two lists solely by length
+*)
+  
 val cmpU: 'a t -> 'a t -> ('a -> 'a -> int [@bs]) -> int
 val cmp: 'a t -> 'a t -> ('a -> 'a -> int) -> int
 (**
     [cmp xs ys cmpElem]
     compare lists [xs] and [ys] using [cmpElem] to compare elements
     @example {[
-      cmp [1;2;3] [1;2;3] compare = 0
+      cmp [1;2;3] [1;2;3] compare = 0;;
+      cmp [1;2;3] [0;1;2;3] compare = 1 ;;]
   ]}
+
+   {b Attention}: The total ordering of List is different from Array,
+   for Array, we compare the length first and one by one later, while
+   for lists, we just compare one by one 
 *)
 
 
@@ -441,7 +453,14 @@ val keep: 'a t ->  ('a -> bool) -> 'a t
 *)
 val keepMapU: 'a t -> ('a -> 'b option [@bs]) -> 'b t
 val keepMap: 'a t -> ('a -> 'b option) -> 'b t
+(** [keepMap xs f]
 
+    @example {[
+      keepMap [1;2;3;4] (fun x -> if x mod 2 = 0 then Some (-x ) else None)
+      =
+      [-2;-4]
+    ]}
+*)
 val partitionU: 'a t -> ('a -> bool [@bs]) ->  'a t * 'a t
 val partition: 'a t -> ('a -> bool) ->  'a t * 'a t
 (** [partition xs p]
@@ -452,7 +471,12 @@ val partition: 'a t -> ('a -> bool) ->  'a t * 'a t
     ]}
 *)
 val unzip: ('a * 'b) t -> 'a t * 'b t
+(** [unzip xs]
 
+    @example {[
+      unzip [(1,2) ; (3,4)] = ([1;3], [2;4])
+    ]}
+*)
 val getAssocU: ('a * 'c) t -> 'b ->  ('a -> 'b -> bool [@bs])  -> 'c option
 val getAssoc: ('a * 'c) t -> 'b ->  ('a -> 'b -> bool)  -> 'c option
 (** [getAssoc xs k eq]