Merge b6738c0 into e59ce40

jscomp/others/belt_Array.mli

@@ -25,11 +25,23 @@ external size: 'a array -> int = "%array_length"
 (** {b See} {!length} *)
 
 val get: 'a array -> int -> 'a option
+(**
+  [get arr i]
+  
+  If [i <= 0 <= length arr], returns [Some value] where [value] is the item at index [i] 
+  If [i] is out of range, returns [None]
+
+  @example {[
+    Belt.Array.get [|"a";"b";"c"|] 0 = Some "a";;
+    Belt.Array.get [|"a";"b";"c"|] 4 = None;;
+    Belt.Array.get [|"a";"b";"c"|] (-1) = None;;
+  ]}
+*)
 
 val getExn: 'a array -> int -> 'a  
 (** [getExn arr i]
 
-    {b raise} an exception if [i] is out of range
+    {b raise} an exception if [i] is out of range, otherwise return the value at index [i] in [arr]
 *)
 
 external getUnsafe: 'a array -> int -> 'a = "%array_unsafe_get"
@@ -63,23 +75,53 @@ val setExn: 'a array -> int -> 'a -> unit
 external setUnsafe: 'a array -> int -> 'a -> unit = "%array_unsafe_set"
 
 val shuffleInPlace: 'a array -> unit
+(** [shuffleInPlace arr] randomly re-orders the items in [arr] *)
 
 val shuffle: 'a array -> 'a array  
 (** [shuffle xs]
-    @return a fresh array *)
+    @return a fresh array with items in original array randomly shuffled *)
 
 val reverseInPlace: 'a array -> unit
+(** [reverseInPlace arr] reverses items in [arr] in place
+
+  @example {[
+    let arr = [|10;11;12;13;14|];;
+    let () = reverseInPlace arr;;
+    arr = [|14;13;12;11;10|];;
+  ]}
+*)
 
 val reverse: 'a array -> 'a array
-(** [reverse x]
-    @return a fresh array *)
+(** [reverse arr]
+    @return a fresh array with items in [arr] in reverse order
+    
+    @example {[
+      reverse [|10;11;12;13;14|] = [|14;13;12;11;10|];;
+    ]}
+*)
 
 external makeUninitialized: int -> 'a Js.undefined array = "Array" [@@bs.new]
+(**
+  [makeUninitialized n] creates an array of length [n] filled with the undefined value.
+  You must specify the type of data that will eventually fill the array.
+  
+  @example {[
+    let arr: string Js.undefined array = makeUninitialized 5;;
+    getExn arr 0 = Js.undefined;;
+  ]}
+*)
 
 external makeUninitializedUnsafe: int -> 'a array = "Array" [@@bs.new]
 (** [makeUninitializedUnsafe n]
 
-    {b Unsafe}   
+    {b Unsafe}
+    
+    @example {[
+    let arr = Belt.Array.makeUninitializedUnsafe 5;;
+    let () = Js.log(Belt.Array.getExn arr 0);; (* undefined *)
+    Belt.Array.setExn arr 0 "example";;
+    let () = Js.log(Belt.Array.getExn arr 0 = "example");;
+    ]}
 *)
 
 
@@ -122,7 +164,8 @@ val makeBy: int -> (int -> 'a ) -> 'a array
     return an array of size [n] populated by [f i] start from [0] to [n - 1]
 
     @example {[
-      makeBy 5 (fun i -> i) = [|0;1;2;3;4|]
+      makeBy 5 (fun i -> i) = [|0;1;2;3;4|];;
+      makeBy 5 (fun i -> i * i) = [|0;1;4;9;16|]
     ]}
 *)
 
@@ -137,10 +180,11 @@ val makeByAndShuffle: int -> (int -> 'a ) -> 'a array
 val zip: 'a array -> 'b array -> ('a * 'b) array
 (** [zip a b] 
     
+    Create an array of tuples from corresponding elements of [a] and [b].
     Stop with the shorter array
 
     @example {[
-      zip [|1;2] [|1;2;3|] = [| (1,2); (2;2)|]
+      zip [|1;2] [|3;4;5|] = [| (1,3); (2;4) |]
     ]}
  *)
 
@@ -150,9 +194,14 @@ val zip: 'a array -> 'b array -> ('a * 'b) array
  (**
     [zipBy xs ys f]
    
+    Create an array by applying [f] to corresponding elements of [xs] and [ys]
     Stops with shorter array
 
     Equivalent to [map (zip xs ys) (fun (a,b) -> f a b) ]
+    
+    @example {[
+      zipBy [|1;2;3|] [|4;5|] (fun a b -> 2 * a + b) = [|6;9|];;
+    ]}
  *)
 
 val concat: 'a array -> 'a array -> 'a array
@@ -161,50 +210,70 @@ val concat: 'a array -> 'a array -> 'a array
     @return a fresh array containing the
     concatenation of the arrays [v1] and [v2], so even if [v1] or [v2]
     is empty, it can not be shared 
+    
+    @example {[
+      concat [|1;2;3|] [|4;5|] = [|1;2;3;4;5|];;
+      concat [| |] [|"a";"b";"c"|] = [|"a";"b";"c"|];;
+    ]}
 *)
 
 val concatMany: 'a array array -> 'a array
 (**
     [concatMany xss]
 
-    @return a fresh array as the concatenation of [xss]
+    @return a fresh array as the concatenation of [xss] (an array of arrays)
+    
+    @example {[
+      concatMany [| [|1;2;3|]; [|4;5;6|]; [|7;8|] |] = [|1;2;3;4;5;6;7;8|];;
+    ]}
 *)
 
 val slice: 'a array -> offset:int -> len:int -> 'a array
-(** [slice arr offset len]
+(** [slice arr offset len] creates a new array with the [len] elements of [arr] starting at [offset] for
     
-    [offset] can be negative,
+    [offset] can be negative, and is evaluated as [length arr - offset]
     [slice arr -1 1] means get the last element as a singleton array
 
-    [slice arr -(very_large_index) len] will do a copy of the array
+    [slice arr (-len) len] will return a copy of the array
     
     if the array does not have enough data, [slice] extracts through
-    the end of sequence
+    the end of sequence.
+    
+    if [len] is negative, returns the empty array.
+    
+    @example {[
+      slice [|10;11;12;13;14;15;16|] ~offset: 2 ~len: 3 = [|12;13;14|];;
+      slice [|10;11;12;13;14;15;16|] ~offset: (-4) ~len: 3 = [|13;14;15|];;
+      slice [|10;11;12;13;14;15;16|] ~offset:4  ~len:9 = [|14;15;16|];;
+    ]}
 *)
 
 
 val copy: 'a array -> 'a array
 (** [copy a] 
 
     @return a copy of [a], that is, a fresh array
-   containing the same elements as [a]. *)
+   containing the same elements as [a]. 
+*)
 
 val fill: 'a array -> offset:int -> len:int -> 'a -> unit
 (** [fill arr ~offset ~len x] 
 
     Modifies [arr] in place,
     storing [x] in elements number [offset] to [offset + len - 1].
 
-    [offset] can be negative
+    [offset] can be negative, and is evaluated as [length arr - offset]
 
     [fill arr offset:(-1) len:1 ] means fill the last element,
     if the array does not have enough data, [fill] will ignore it
 
     @example {[
 
       let arr = makeBy 5 (fun i -> i) ;;
-      fill arr ~offset:2 ~len:2 0 ;;
-      arr = [|0;1;0;0;4|];;
+      fill arr ~offset:2 ~len:2 9 ;;
+      arr = [|0;1;9;9;4|];;
+      fill arr ~offset:7 ~len:2 8;;
+      arr = [|0;1;9;9;4|];;
     ]}
  *)
 
@@ -287,7 +356,8 @@ val reduce:  'b array -> 'a -> ('a -> 'b -> 'a ) ->'a
 (** [reduce xs init f]
 
     @example {[
-      reduce [|2;3;4|] 1 (+) = 10
+      reduce [|2;3;4|] 1 (+) = 10;;
+      reduce [|"a";"b";"c";"d"|] "" (^) = "abcd";;
     ]}
    
 *)
@@ -296,7 +366,7 @@ val reduceReverseU: 'b array -> 'a -> ('a -> 'b ->  'a [@bs]) ->  'a
 val reduceReverse: 'b array -> 'a -> ('a -> 'b ->  'a ) ->  'a
 (** [reduceReverse xs init f]
     @example {[
-      reduceReverse [|1;2;3;4|] 100 (-) = 90 
+      reduceReverse [|"a";"b";"c";"d"|] "" (^) = "dcba";;
     ]}
 *)
 
@@ -305,6 +375,10 @@ val reduceReverse2U:
 val reduceReverse2:  
   'a array -> 'b array -> 'c  -> ('c -> 'a -> 'b ->  'c) ->  'c
 (**
+   [reduceReverse2 xs ys init f]
+   Reduces two arrays [xs] and [ys], taking items starting at [min (length xs) (length ys)]
+   down to and including zero.
+   
    @example {[
      reduceReverse2 [|1;2;3|] [|1;2|] 0 (fun acc x y -> acc + x + y) = 6
    ]}
@@ -314,18 +388,28 @@ val someU: 'a array -> ('a -> bool [@bs]) -> bool
 val some: 'a array -> ('a -> bool) -> bool
 (** [some xs p]
     @return true if one of element satifies [p]
+
+    @example {[
+      some [|2; 3; 4|] (fun x -> x mod 2 = 1) = true;;
+      some [|-1; -3; -5|] (fun x -> x > 0) = false;;
+    ]}
 *)
 
 val everyU: 'a array -> ('a -> bool [@bs]) -> bool
 val every: 'a array -> ('a -> bool ) -> bool
 (** [every xs p]
     @return true if all elements satisfy [p]
+    
+    @example {[
+      every [|1; 3; 5|] (fun x -> x mod 2 = 1) = true;;
+      every [|1; -3; 5|] (fun x -> x > 0) = false;;
+    ]}
 *)
 
 val every2U: 'a array -> 'b array -> ('a -> 'b -> bool [@bs]) -> bool
 val every2: 'a array -> 'b array -> ('a -> 'b -> bool ) -> bool
-(** [every2 xs ys p] only tests the length of shorter
-
+(** [every2 xs ys p] returns true if [p xi yi] is true for all pairs of elements
+  up to the shorter length (i.e. [min (length xs) (length ys)])
     @example {[
       every2 [|1;2;3|] [|0;1|] (>) = true;;
       (every2 [||] [|1|] (fun   x y -> x > y)) = true;;
@@ -335,7 +419,8 @@ val every2: 'a array -> 'b array -> ('a -> 'b -> bool ) -> bool
 
 val some2U: 'a array -> 'b array -> ('a -> 'b -> bool [@bs]) -> bool
 val some2: 'a array -> 'b array -> ('a -> 'b -> bool ) -> bool
-(** [some2 xs ys p] only tests the length of shorter
+(** [some2 xs ys p] returns true if [p xi yi] is true for any pair of elements
+  up to the shorter length (i.e. [min (length xs) (length ys)])
 
     @example {[
       some2 [|0;2|] [|1;0;3|] (>) = true ;;
@@ -348,17 +433,44 @@ val cmpU: 'a array -> 'a array -> ('a -> 'a -> int [@bs]) -> int
 val cmp: 'a array -> 'a array -> ('a -> 'a -> int ) -> int
 (** [cmp a b]
     
-    - Compared by length if [length a <> length b] 
-    - Otherwise compare one by one [f ai bi]
+    - Compared by length if [length a <> length b], returning -1 if [length a < length b] or 1 if [length a > length b]
+    - Otherwise compare one by one [f ai bi]. [f] returns
+      - a negative number if [ai] is “less than” [bi]
+      - zero if [ai] is “equal to” [bi]
+      - a positive number if [ai] is “greater than” [bi]
+    - The comparison returns the first non-zero result of [f], or zero if [f] returns zero for all [ai] and [bi].
+    
+    @example {[
+      cmp [|1; 3; 5|] [|1; 4; 2|] (fun a b -> compare a b) = -1;;
+      cmp [|1; 3; 5|] [|1; 2; 3|] (fun a b -> compare a b) = 1;;
+      cmp [|1; 3; 5|] [|1; 3; 5|] (fun a b -> compare a b) = 0;;
+    ]}
 *)
 
 val eqU:  'a array -> 'a array -> ('a -> 'a -> bool [@bs]) -> bool
 val eq:  'a array -> 'a array -> ('a -> 'a -> bool ) -> bool
 (** [eq a b]
     
     - return false if length is not the same
-    - equal one by one using [f ai bi]
+    - otherwise compare items one by one using [f ai bi], and return true if all results are true, false otherwise
+    
+    @example {[
+      eq [|1; 2; 3|] [|-1; -2; -3|] (fun a b -> abs a = abs b) = true
+    ]}
 *)
 
 external truncateToLengthUnsafe: 'a array -> int ->  unit = "length" [@@bs.set]
-(** {b Unsafe}  *)
+(** {b Unsafe}
+  [truncateToLengthUnsafe xs n] sets length of array [xs] to [n].
+  
+  If [n] is greater than the length of [xs], the extra elements are set to [Js.Null_undefined.null]
+  
+  If [n] is less than zero, raises a [RangeError].
+  
+  @example {[
+    let arr = [|"ant", "bee", "cat", "dog", "elk"|] in
+    let () = truncateToLengthUnsafe arr 3 in
+    arr = [|"ant", "bee", "cat"|] = true;;
+  ]}
+  
+*)

jscomp/others/js_string.ml

@@ -154,7 +154,7 @@ external concatMany : t array -> t = "concat" [@@bs.send.pipe: t] [@@bs.splice]
 *)
 external endsWith : t -> bool = "" [@@bs.send.pipe: t] 
 
-(** [endsWithFrom ending len str] returns [true] if the first [len] characters of [str] end with [ending], [false] otherwise. If [n] is greater than or equal to the length of [str], then it works like [endsWith]. (Honestly, this should have been named [endsWithAt], but oh well.)
+(** [endsWithFrom ending len str] returns [true] if the first [len] characters of [str] end with [ending], [false] otherwise. If [n] is greater than or equal to the length of [str], then it works like [endsWith].
 
 @example {[
   endsWithFrom "cd" 4 "abcd" = true;;