@tellahq/rescript 10.1.4-republish-2 → 10.1.4-republish-3

package/lib/ocaml/js_array.ml

@@ -0,0 +1,970 @@
+(* Copyright (C) 2015-2016 Bloomberg Finance L.P.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * In addition to the permissions granted to you by the LGPL, you may combine
+ * or link a "work that uses the Library" with a publicly distributed version
+ * of this file to produce a combined library or application, then distribute
+ * that combined work under the terms of your choosing, with no requirement
+ * to comply with the obligations normally placed on you by section 4 of the
+ * LGPL version 3 (or the corresponding section of a later version of the LGPL
+ * should you choose to use a later version).
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *)
+
+(**
+  Provides bindings to JavaScript’s `Array` functions. These bindings are
+  optimized for pipe-last (`|>`), where the array to be processed is the last
+  parameter in the function.
+
+  Here is an example to find the sum of squares of all even numbers in an array.
+  Without pipe last, we must call the functions in reverse order:
+
+  ```res example
+  let isEven = x => mod(x, 2) == 0
+  let square = x => x * x
+  let result = {
+    open Js.Array
+    reduce(\"+", 0, map(square, filter(isEven, [5, 2, 3, 4, 1])))
+  }
+  ```
+
+  With pipe last, we call the functions in the “natural” order:
+
+  ```res example
+  let isEven = x => mod(x, 2) == 0
+  let square = x => x * x
+  let result = {
+    open Js.Array
+    [5, 2, 3, 4, 1] |> filter(isEven) |> map(square) |> reduce(\"+", 0)
+  }
+  ```
+*)
+
+[@@@warning "-103"]
+
+type 'a t = 'a array
+(**
+  The type used to describe a JavaScript array.
+*)
+
+type 'a array_like = 'a Js_array2.array_like
+(**
+  A type used to describe JavaScript objects that are like an array or are iterable.
+*)
+
+(* commented out until bs has a plan for iterators
+   type 'a array_iter = 'a array_like
+*)
+
+external from : 'a array_like -> 'a array = "Array.from"
+  [@@bs.val]
+(**
+  Creates a shallow copy of an array from an array-like object. See [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) on MDN.
+
+  ```res example
+  let strArr = Js.String.castToArrayLike("abcd")
+  Js.Array.from(strArr) == ["a", "b", "c", "d"]
+  ```
+*)
+(* ES2015 *)
+
+external fromMap : 'a array_like -> (('a -> 'b)[@bs.uncurry]) -> 'b array
+  = "Array.from"
+  [@@bs.val]
+(**
+  Creates a new array by applying a function (the second argument) to each item
+  in the `array_like` first argument.  See
+  [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from)
+  on MDN.
+
+  ```res example
+  let strArr = Js.String.castToArrayLike("abcd")
+  let code = s => Js.String.charCodeAt(0, s)
+  Js.Array.fromMap(strArr, code) == [97.0, 98.0, 99.0, 100.0]
+  ```
+*)
+(* ES2015 *)
+
+external isArray : 'a -> bool = "Array.isArray" [@@bs.val]
+(* ES2015 *)
+(*
+  Returns `true` if its argument is an array; `false` otherwise. This is a
+  runtime check, which is why the second example returns `true` — a list is
+  internally represented as a nested JavaScript array.
+
+  ```res example
+  Js.Array.isArray([5, 2, 3, 1, 4]) == true
+  Js.Array.isArray(list{5, 2, 3, 1, 4}) == true
+  Js.Array.isArray("abcd") == false
+  ```
+*)
+
+external length : 'a array -> int = "length"
+  [@@bs.get]
+(**
+  Returns the number of elements in the array. See [`Array.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length) on MDN.
+*)
+
+(* Mutator functions *)
+
+external copyWithin : to_:int -> 'this = "copyWithin"
+  [@@bs.send.pipe: 'a t as 'this]
+(** 
+  Copies from the first element in the given array to the designated `~to_` position, returning the resulting array. *This function modifies the original array.* See [`Array.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) on MDN.
+
+  ```res example
+  let arr = [100, 101, 102, 103, 104]
+  Js.Array.copyWithin(~to_=2, arr) == [100, 101, 100, 101, 102]
+  arr == [100, 101, 100, 101, 102]
+  ```
+*)
+(* ES2015 *)
+
+external copyWithinFrom : to_:int -> from:int -> 'this = "copyWithin"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Copies starting at element `~from` in the given array to the designated `~to_` position, returning the resulting array. *This function modifies the original array.* See [`Array.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) on MDN.
+
+  ```res example
+  let arr = [100, 101, 102, 103, 104]
+  Js.Array.copyWithinFrom(~from=2, ~to_=0, arr) == [102, 103, 104, 103, 104]
+  arr == [102, 103, 104, 103, 104]
+  ```
+*)
+(* ES2015 *)
+
+external copyWithinFromRange : to_:int -> start:int -> end_:int -> 'this
+  = "copyWithin"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Copies starting at element `~start` in the given array up to but not including `~end_` to the designated `~to_` position, returning the resulting array. *This function modifies the original array.* See [`Array.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) on MDN.
+
+  ```res example
+  let arr = [100, 101, 102, 103, 104, 105]
+  Js.Array.copyWithinFromRange(~start=2, ~end_=5, ~to_=1, arr) == [100, 102, 103, 104, 104, 105]
+  arr == [100, 102, 103, 104, 104, 105]
+  ```
+*)
+(* ES2015 *)
+
+external fillInPlace : 'a -> 'this = "fill"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Sets all elements of the given array (the second arumgent) to the designated value (the first argument), returning the resulting array. *This function modifies the original array.* See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN.
+
+  ```res example
+  let arr = [100, 101, 102, 103, 104]
+  Js.Array.fillInPlace(99, arr) == [99, 99, 99, 99, 99]
+  arr == [99, 99, 99, 99, 99]
+  ```
+*)
+(* ES2015 *)
+
+external fillFromInPlace : 'a -> from:int -> 'this = "fill"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Sets all elements of the given array (the last arumgent) from position `~from` to the end to the designated value (the first argument), returning the resulting array. *This function modifies the original array.* See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN.
+
+  ```res example
+  let arr = [100, 101, 102, 103, 104]
+  Js.Array.fillFromInPlace(99, ~from=2, arr) == [100, 101, 99, 99, 99]
+  arr == [100, 101, 99, 99, 99]
+  ```
+*)
+(* ES2015 *)
+
+external fillRangeInPlace : 'a -> start:int -> end_:int -> 'this = "fill"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Sets the elements of the given array (the last arumgent) from position `~start` up to but not including position `~end_` to the designated value (the first argument), returning the resulting array. *This function modifies the original array.* See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN.
+
+  ```res example
+  let arr = [100, 101, 102, 103, 104]
+  Js.Array.fillRangeInPlace(99, ~start=1, ~end_=4, arr) == [100, 99, 99, 99, 104]
+  arr == [100, 99, 99, 99, 104]
+  ```
+*)
+(* ES2015 *)
+
+external pop : 'a option = "pop"
+  [@@bs.send.pipe: 'a t as 'this] [@@bs.return undefined_to_opt]
+(**
+  If the array is not empty, removes the last element and returns it as `Some(value)`; returns `None` if the array is empty. *This function modifies the original array.* See [`Array.pop`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/pop) on MDN.
+
+  ```res example
+  let arr = [100, 101, 102, 103, 104]
+  Js.Array.pop(arr) == Some(104)
+  arr == [100, 101, 102, 103]
+
+  let empty: array<int> = []
+  Js.Array.pop(empty) == None
+  ```
+*)
+
+external push : 'a -> int = "push"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Appends the given value to the array, returning the number of elements in the updated array. *This function modifies the original array.* See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) on MDN.
+
+  ```res example
+  let arr = ["ant", "bee", "cat"]
+  Js.Array.push("dog", arr) == 4
+  arr == ["ant", "bee", "cat", "dog"]
+  ```
+*)
+
+external pushMany : 'a array -> int = "push"
+  [@@bs.send.pipe: 'a t as 'this] [@@bs.splice]
+(**
+  Appends the values from one array (the first argument) to another (the second argument), returning the number of elements in the updated array. *This function modifies the original array.* See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) on MDN.
+
+  ```res example
+  let arr = ["ant", "bee", "cat"]
+  Js.Array.pushMany(["dog", "elk"], arr) == 5
+  arr == ["ant", "bee", "cat", "dog", "elk"]
+  ```
+*)
+
+external reverseInPlace : 'this = "reverse"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Returns an array with the elements of the input array in reverse order. *This function modifies the original array.* See [`Array.reverse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) on MDN.
+
+  ```res example
+  let arr = ["ant", "bee", "cat"]
+  Js.Array.reverseInPlace(arr) == ["cat", "bee", "ant"]
+  arr == ["cat", "bee", "ant"]
+  ```
+*)
+
+external shift : 'a option = "shift"
+  [@@bs.send.pipe: 'a t as 'this] [@@bs.return { undefined_to_opt }]
+(**
+  If the array is not empty, removes the first element and returns it as `Some(value)`; returns `None` if the array is empty. *This function modifies the original array.* See [`Array.shift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/shift) on MDN.
+
+  ```res example
+  let arr = [100, 101, 102, 103, 104]
+  Js.Array.shift(arr) == Some(100)
+  arr == [101, 102, 103, 104]
+
+  let empty: array<int> = []
+  Js.Array.shift(empty) == None
+  ```
+*)
+
+external sortInPlace : 'this = "sort"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Sorts the given array in place and returns the sorted array. JavaScript sorts the array by converting the arguments to UTF-16 strings and sorting them. See the second example with sorting numbers, which does not do a numeric sort. *This function modifies the original array.* See [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) on MDN.
+
+  ```res example
+  let words = ["bee", "dog", "ant", "cat"]
+  Js.Array.sortInPlace(words) == ["ant", "bee", "cat", "dog"]
+  words == ["ant", "bee", "cat", "dog"]
+
+  let numbers = [3, 30, 10, 1, 20, 2]
+  Js.Array.sortInPlace(numbers) == [1, 10, 2, 20, 3, 30]
+  numbers == [1, 10, 2, 20, 3, 30]
+  ```
+*)
+
+external sortInPlaceWith : (('a -> 'a -> int)[@bs.uncurry]) -> 'this = "sort"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Sorts the given array in place and returns the sorted array. *This function modifies the original array.*
+
+  The first argument to `sortInPlaceWith()` is a function that compares two items from the array and returns:
+
+  * an integer less than zero if the first item is less than the second item
+  * zero if the items are equal
+  * an integer greater than zero if the first item is greater than the second item
+
+  See [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) on MDN.
+
+  ```res example
+  // sort by word length
+  let words = ["horse", "aardvark", "dog", "camel"]
+  let byLength = (s1, s2) => Js.String.length(s1) - Js.String.length(s2)
+
+  Js.Array.sortInPlaceWith(byLength, words) == ["dog", "horse", "camel", "aardvark"]
+
+  // sort in reverse numeric order
+  let numbers = [3, 30, 10, 1, 20, 2]
+  let reverseNumeric = (n1, n2) => n2 - n1
+  Js.Array.sortInPlaceWith(reverseNumeric, numbers) == [30, 20, 10, 3, 2, 1]
+  ```
+*)
+
+external spliceInPlace : pos:int -> remove:int -> add:'a array -> 'this
+  = "splice"
+  [@@bs.send.pipe: 'a t as 'this] [@@bs.splice]
+(**
+  Starting at position `~pos`, remove `~remove` elements and then add the
+  elements from the `~add` array. Returns an array consisting of the removed
+  items. *This function modifies the original array.* See
+  [`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice)
+  on MDN.
+
+  ```res example
+  let arr = ["a", "b", "c", "d", "e", "f"]
+  Js.Array.spliceInPlace(~pos=2, ~remove=2, ~add=["x", "y", "z"], arr) == ["c", "d"]
+  arr == ["a", "b", "x", "y", "z", "e", "f"]
+
+  let arr2 = ["a", "b", "c", "d"]
+  Js.Array.spliceInPlace(~pos=3, ~remove=0, ~add=["x", "y"], arr2) == []
+  arr2 == ["a", "b", "c", "x", "y", "d"]
+
+  let arr3 = ["a", "b", "c", "d", "e", "f"]
+  Js.Array.spliceInPlace(~pos=9, ~remove=2, ~add=["x", "y", "z"], arr3) == []
+  arr3 == ["a", "b", "c", "d", "e", "f", "x", "y", "z"]
+  ```
+*)
+
+external removeFromInPlace : pos:int -> 'this = "splice"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Removes elements from the given array starting at position `~pos` to the end
+  of the array, returning the removed elements. *This function modifies the
+  original array.* See
+  [`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice)
+  on MDN.
+
+  ```res example
+  let arr = ["a", "b", "c", "d", "e", "f"]
+  Js.Array.removeFromInPlace(~pos=4, arr) == ["e", "f"]
+  arr == ["a", "b", "c", "d"]
+  ```
+*)
+
+external removeCountInPlace : pos:int -> count:int -> 'this = "splice"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Removes `~count` elements from the given array starting at position `~pos`,
+  returning the removed elements. *This function modifies the original array.*
+  See
+  [`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice)
+  on MDN.
+
+  ```res example
+  let arr = ["a", "b", "c", "d", "e", "f"]
+  Js.Array.removeCountInPlace(~pos=2, ~count=3, arr) == ["c", "d", "e"]
+  arr == ["a", "b", "f"]
+  ```
+*)
+
+external unshift : 'a -> int = "unshift"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Adds the given element to the array, returning the new number of elements in
+  the array. *This function modifies the original array.* See
+  [`Array.unshift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift)
+  on MDN.
+
+  ```res example
+  let arr = ["b", "c", "d"]
+  Js.Array.unshift("a", arr) == 4
+  arr == ["a", "b", "c", "d"]
+  ```
+*)
+
+external unshiftMany : 'a array -> int = "unshift"
+  [@@bs.send.pipe: 'a t as 'this] [@@bs.splice]
+(**
+  Adds the elements in the first array argument at the beginning of the second
+  array argument, returning the new number of elements in the array. *This
+  function modifies the original array.* See
+  [`Array.unshift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift)
+  on MDN.
+
+  ```res example
+  let arr = ["d", "e"]
+  Js.Array.unshiftMany(["a", "b", "c"], arr) == 5
+  arr == ["a", "b", "c", "d", "e"]
+  ```
+*)
+
+(* Accessor functions
+*)
+external concat : 'this -> 'this = "concat"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Concatenates the first array argument to the second array argument, returning
+  a new array. The original arrays are not modified. See
+  [`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat)
+  on MDN.
+
+  ```res example
+  Js.Array.concat(["c", "d", "e"], ["a", "b"]) == ["a", "b", "c", "d", "e"]
+  ```
+*)
+
+external concatMany : 'this array -> 'this = "concat"
+  [@@bs.send.pipe: 'a t as 'this] [@@bs.splice]
+(**
+  The first argument to `concatMany()` is an array of arrays; these are added
+  at the end of the second argument, returning a new array. See
+  [`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat)
+  on MDN.
+
+  ```res example
+  Js.Array.concatMany([["d", "e"], ["f", "g", "h"]], ["a", "b", "c"]) == [
+      "a",
+      "b",
+      "c",
+      "d",
+      "e",
+      "f",
+      "g",
+      "h",
+    ]
+  ```
+*)
+
+(* ES2016 *)
+external includes : 'a -> bool = "includes"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Returns true if the given value is in the array, `false` otherwise. See
+  [`Array.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes)
+  on MDN.
+
+  ```res example
+  Js.Array.includes("b", ["a", "b", "c"]) == true
+  Js.Array.includes("x", ["a", "b", "c"]) == false
+  ```
+*)
+
+external indexOf : 'a -> int = "indexOf"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Returns the index of the first element in the array that has the given value.
+  If the value is not in the array, returns -1. See
+  [`Array.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf)
+  on MDN.
+
+  ```res example
+  Js.Array.indexOf(102, [100, 101, 102, 103]) == 2
+  Js.Array.indexOf(999, [100, 101, 102, 103]) == -1
+  ```
+*)
+
+external indexOfFrom : 'a -> from:int -> int = "indexOf"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Returns the index of the first element in the array with the given value. The
+  search starts at position `~from`. See
+  [`Array.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf)
+  on MDN.
+
+  ```res example
+  Js.Array.indexOfFrom("a", ~from=2, ["a", "b", "a", "c", "a"]) == 2
+  Js.Array.indexOfFrom("a", ~from=3, ["a", "b", "a", "c", "a"]) == 4
+  Js.Array.indexOfFrom("b", ~from=2, ["a", "b", "a", "c", "a"]) == -1
+  ```
+*)
+
+external join : 'a t -> string = "join"
+  [@@bs.send] [@@deprecated "please use joinWith instead"]
+(**
+  @deprecated: Use `joinWith` instead.
+*)
+
+external joinWith : string -> string = "join"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  This function converts each element of the array to a string (via JavaScript)
+and concatenates them, separated by the string given in the first argument,
+into a single string. See
+[`Array.join`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join)
+on MDN.
+
+  ```res example
+  Js.Array.joinWith("--", ["ant", "bee", "cat"]) == "ant--bee--cat"
+  Js.Array.joinWith("", ["door", "bell"]) == "doorbell"
+  Js.Array.joinWith("/", [2020, 9, 4]) == "2020/9/4"
+  Js.Array.joinWith(";", [2.5, 3.6, 3e-2]) == "2.5;3.6;0.03"
+  ```
+*)
+
+external lastIndexOf : 'a -> int = "lastIndexOf"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Returns the index of the last element in the array that has the given value.
+  If the value is not in the array, returns -1. See
+  [`Array.lastIndexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf)
+  on MDN.
+
+  ```res example
+  Js.Array.lastIndexOf("a", ["a", "b", "a", "c"]) == 2
+  Js.Array.lastIndexOf("x", ["a", "b", "a", "c"]) == -1
+  ```
+*)
+
+external lastIndexOfFrom : 'a -> from:int -> int = "lastIndexOf"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Returns the index of the last element in the array that has the given value,
+  searching from position `~from` down to the start of the array. If the value
+  is not in the array, returns -1. See
+  [`Array.lastIndexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf)
+  on MDN.
+
+  ```res example
+  Js.Array.lastIndexOfFrom("a", ~from=3, ["a", "b", "a", "c", "a", "d"]) == 2
+  Js.Array.lastIndexOfFrom("c", ~from=2, ["a", "b", "a", "c", "a", "d"]) == -1
+  ```
+*)
+
+external slice : start:int -> end_:int -> 'this = "slice"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Returns a shallow copy of the given array from the `~start` index up to but
+  not including the `~end_` position. Negative numbers indicate an offset from
+  the end of the array. See
+  [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice)
+  on MDN.
+
+  ```res example
+  let arr = [100, 101, 102, 103, 104, 105, 106]
+  Js.Array.slice(~start=2, ~end_=5, arr) == [102, 103, 104]
+  Js.Array.slice(~start=-3, ~end_=-1, arr) == [104, 105]
+  Js.Array.slice(~start=9, ~end_=10, arr) == []
+  ```
+*)
+
+external copy : 'this = "slice"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Returns a copy of the entire array. Same as `Js.Array.Slice(~start=0,
+  ~end_=Js.Array.length(arr), arr)`. See
+  [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice)
+  on MDN.
+*)
+
+external sliceFrom : int -> 'this = "slice"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Returns a shallow copy of the given array from the given index to the end. See [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) on MDN.
+
+  ```res example
+  Js.Array.sliceFrom(2, [100, 101, 102, 103, 104]) == [102, 103, 104]
+  ```
+*)
+
+external toString : string = "toString"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Converts the array to a string. Each element is converted to a string using
+  JavaScript. Unlike the JavaScript `Array.toString()`, all elements in a
+  ReasonML array must have the same type. See
+  [`Array.toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString)
+  on MDN.
+
+  ```res example
+  Js.Array.toString([3.5, 4.6, 7.8]) == "3.5,4.6,7.8"
+  Js.Array.toString(["a", "b", "c"]) == "a,b,c"
+  ```
+*)
+
+external toLocaleString : string = "toLocaleString"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Converts the array to a string using the conventions of the current locale.
+  Each element is converted to a string using JavaScript. Unlike the JavaScript
+  `Array.toLocaleString()`, all elements in a ReasonML array must have the same
+type. See
+[`Array.toLocaleString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toLocaleString)
+on MDN.
+
+  ```res example
+  Js.Array.toLocaleString([Js.Date.make()])
+  // returns "3/19/2020, 10:52:11 AM" for locale en_US.utf8
+  // returns "2020-3-19 10:52:11" for locale de_DE.utf8
+  ```
+*)
+
+(* Iteration functions
+*)
+(* commented out until bs has a plan for iterators
+   external entries : (int * 'a) array_iter = "" [@@bs.send.pipe: 'a t as 'this] (* ES2015 *)
+*)
+
+external every : (('a -> bool)[@bs.uncurry]) -> bool = "every"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  The first argument to `every()` is a predicate function that returns a boolean. The `every()` function returns `true` if the predicate function is true for all items in the given array. If given an empty array, returns `true`. See [`Array.every`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) on MDN.
+
+  ```res example
+  let isEven = x => mod(x, 2) == 0
+  Js.Array.every(isEven, [6, 22, 8, 4]) == true
+  Js.Array.every(isEven, [6, 22, 7, 4]) == false
+  ```
+*)
+
+external everyi : (('a -> int -> bool)[@bs.uncurry]) -> bool = "every"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  The first argument to `everyi()` is a predicate function with two arguments: an array element and that element’s index; it returns a boolean. The `everyi()` function returns `true` if the predicate function is true for all items in the given array. If given an empty array, returns `true`. See [`Array.every`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) on MDN.
+
+  ```res example
+  // determine if all even-index items are positive
+  let evenIndexPositive = (item, index) => mod(index, 2) == 0 ? item > 0 : true
+
+  Js.Array.everyi(evenIndexPositive, [6, -3, 5, 8]) == true
+  Js.Array.everyi(evenIndexPositive, [6, 3, -5, 8]) == false
+  ```
+*)
+
+external filter : (('a -> bool)[@bs.uncurry]) -> 'this = "filter"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Applies the given predicate function to each element in the array; the result is an array of those elements for which the predicate function returned `true`. See [`Array.filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) on MDN.
+
+  ```res example
+  let nonEmpty = s => s != ""
+  Js.Array.filter(nonEmpty, ["abc", "", "", "def", "ghi"]) == ["abc", "def", "ghi"]
+  ```
+*)
+
+external filteri : (('a -> int -> bool)[@bs.uncurry]) -> 'this = "filter"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Each element of the given array are passed to the predicate function. The
+  return value is an array of all those elements for which the predicate
+  function returned `true`.  See
+  [`Array.filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter)
+  on MDN.
+
+  ```res example
+  // keep only positive elements at odd indices
+  let positiveOddElement = (item, index) => mod(index, 2) == 1 && item > 0
+
+  Js.Array.filteri(positiveOddElement, [6, 3, 5, 8, 7, -4, 1]) == [3, 8]
+```
+*)
+
+external find : (('a -> bool)[@bs.uncurry]) -> 'a option = "find"
+  [@@bs.send.pipe: 'a t as 'this] [@@bs.return { undefined_to_opt }]
+(**
+  Returns `Some(value)` for the first element in the array that satisifies the
+  given predicate function, or `None` if no element satisifies the predicate.
+  See
+  [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find)
+  on MDN.
+
+  ```res example
+  // find first negative element
+  Js.Array.find(x => x < 0, [33, 22, -55, 77, -44]) == Some(-55)
+  Js.Array.find(x => x < 0, [33, 22, 55, 77, 44]) == None
+  ```
+*)
+
+external findi : (('a -> int -> bool)[@bs.uncurry]) -> 'a option = "find"
+  [@@bs.send.pipe: 'a t as 'this] [@@bs.return { undefined_to_opt }]
+(**
+  Returns `Some(value)` for the first element in the array that satisifies the given predicate function, or `None` if no element satisifies the predicate. The predicate function takes an array element and an index as its parameters. See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN.
+
+  ```res example
+  // find first positive item at an odd index
+  let positiveOddElement = (item, index) => mod(index, 2) == 1 && item > 0
+
+  Js.Array.findi(positiveOddElement, [66, -33, 55, 88, 22]) == Some(88)
+  Js.Array.findi(positiveOddElement, [66, -33, 55, -88, 22]) == None
+  ```
+*)
+
+external findIndex : (('a -> bool)[@bs.uncurry]) -> int = "findIndex"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Returns the index of the first element in the array that satisifies the given predicate function, or -1 if no element satisifies the predicate. See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN.
+
+  ```res example
+  Js.Array.findIndex(x => x < 0, [33, 22, -55, 77, -44]) == 2
+  Js.Array.findIndex(x => x < 0, [33, 22, 55, 77, 44]) == -1
+  ```
+*)
+
+external findIndexi : (('a -> int -> bool)[@bs.uncurry]) -> int = "findIndex"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Returns `Some(value)` for the first element in the array that satisifies the given predicate function, or `None` if no element satisifies the predicate. The predicate function takes an array element and an index as its parameters. See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN.
+
+  ```res example
+  // find index of first positive item at an odd index
+  let positiveOddElement = (item, index) => mod(index, 2) == 1 && item > 0
+
+  Js.Array.findIndexi(positiveOddElement, [66, -33, 55, 88, 22]) == 3
+  Js.Array.findIndexi(positiveOddElement, [66, -33, 55, -88, 22]) == -1
+  ```
+*)
+
+external forEach : (('a -> unit)[@bs.uncurry]) -> unit = "forEach"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  The `forEach()` function applies the function given as the first argument to each element in the array. The function you provide returns `unit`, and the `forEach()` function also returns `unit`. You use `forEach()` when you need to process each element in the array but not return any new array or value; for example, to print the items in an array. See [`Array.forEach`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) on MDN.
+
+  ```res example
+  // display all elements in an array
+  Js.Array.forEach(x => Js.log(x), ["a", "b", "c"]) == ()
+  ```
+*)
+
+external forEachi : (('a -> int -> unit)[@bs.uncurry]) -> unit = "forEach"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  The `forEachi()` function applies the function given as the first argument to each element in the array. The function you provide takes an item in the array and its index number, and returns `unit`. The `forEachi()` function also returns `unit`. You use `forEachi()` when you need to process each element in the array but not return any new array or value; for example, to print the items in an array. See [`Array.forEach`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) on MDN.
+
+  ```res example
+  // display all elements in an array as a numbered list
+  Js.Array.forEachi((item, index) => Js.log2(index + 1, item), ["a", "b", "c"]) == ()
+  ```
+*)
+
+(* commented out until bs has a plan for iterators
+   external keys : int array_iter = "" [@@bs.send.pipe: 'a t as 'this] (* ES2015 *)
+*)
+
+external map : (('a -> 'b)[@bs.uncurry]) -> 'b t = "map"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Applies the function (given as the first argument) to each item in the array,
+  returning a new array. The result array does not have to have elements of the
+  same type as the input array. See
+  [`Array.map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)
+  on MDN.
+
+  ```res example
+  Js.Array.map(x => x * x, [12, 4, 8]) == [144, 16, 64]
+  Js.Array.map(Js.String.length, ["animal", "vegetable", "mineral"]) == [6, 9, 7]
+  ```
+*)
+
+external mapi : (('a -> int -> 'b)[@bs.uncurry]) -> 'b t = "map"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+  Applies the function (given as the first argument) to each item in the array,
+  returning a new array. The function acceps two arguments: an item from the
+  array and its index number. The result array does not have to have elements
+  of the same type as the input array. See
+  [`Array.map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)
+  on MDN.
+
+  ```res example
+  // multiply each item in array by its position
+  let product = (item, index) => item * index
+  Js.Array.mapi(product, [10, 11, 12]) == [0, 11, 24]
+  ```
+*)
+
+external reduce : (('b -> 'a -> 'b)[@bs.uncurry]) -> 'b -> 'b = "reduce"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+The `reduce()` function takes three parameters: a *reducer function*, a
+beginning accumulator value, and an array. The reducer function has two
+parameters: an accumulated value and an element of the array.
+
+`reduce()` first calls the reducer function with the beginning value and the
+first element in the array. The result becomes the new accumulator value, which
+is passed in to the reducer function along with the second element in the
+array. `reduce()` proceeds through the array, passing in the result of each
+stage as the accumulator to the reducer function.
+
+When all array elements are processed, the final value of the accumulator
+becomes the return value of `reduce()`. See
+[`Array.reduce`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce)
+on MDN.
+
+```res example
+let sumOfSquares = (accumulator, item) => accumulator + item * item
+
+Js.Array.reduce(sumOfSquares, 0, [10, 2, 4]) == 120
+Js.Array.reduce(\"*", 1, [10, 2, 4]) == 80
+Js.Array.reduce(
+  (acc, item) => acc + Js.String.length(item),
+  0,
+  ["animal", "vegetable", "mineral"],
+) == 22 // 6 + 9 + 7
+Js.Array.reduce((acc, item) => item /. acc, 1.0, [2.0, 4.0]) == 2.0 // 4.0 / (2.0 / 1.0)
+```
+*)
+
+external reducei : (('b -> 'a -> int -> 'b)[@bs.uncurry]) -> 'b -> 'b = "reduce"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+The `reducei()` function takes three parameters: a *reducer function*, a
+beginning accumulator value, and an array. The reducer function has three
+parameters: an accumulated value, an element of the array, and the index of
+that element.
+
+`reducei()` first calls the reducer function with the beginning value, the
+first element in the array, and zero (its index). The result becomes the new
+accumulator value, which is passed to the reducer function along with the
+second element in the array and one (its index). `reducei()` proceeds from left
+to right through the array, passing in the result of each stage as the
+accumulator to the reducer function.
+
+When all array elements are processed, the final value of the accumulator
+becomes the return value of `reducei()`. See
+[`Array.reduce`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce)
+on MDN.
+
+```res example
+// find sum of even-index elements in array
+let sumOfEvens = (accumulator, item, index) =>
+  if mod(index, 2) == 0 {
+    accumulator + item
+  } else {
+    accumulator
+  }
+
+Js.Array.reducei(sumOfEvens, 0, [2, 5, 1, 4, 3]) == 6
+```
+*)
+
+external reduceRight : (('b -> 'a -> 'b)[@bs.uncurry]) -> 'b -> 'b
+  = "reduceRight"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+The `reduceRight()` function takes three parameters: a *reducer function*, a
+beginning accumulator value, and an array. The reducer function has two
+parameters: an accumulated value and an element of the array.
+
+`reduceRight()` first calls the reducer function with the beginning value and
+the last element in the array. The result becomes the new accumulator value,
+which is passed in to the reducer function along with the next-to-last element
+in the array. `reduceRight()` proceeds from right to left through the array,
+passing in the result of each stage as the accumulator to the reducer function.
+
+When all array elements are processed, the final value of the accumulator
+becomes the return value of `reduceRight()`.  See
+[`Array.reduceRight`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduceRight)
+on MDN.
+
+**NOTE:** In many cases, `reduce()` and `reduceRight()` give the same result. However, see the last example here and compare it to the example from `reduce()`, where order makes a difference.
+
+```res example
+let sumOfSquares = (accumulator, item) => accumulator + item * item
+
+Js.Array.reduceRight(sumOfSquares, 0, [10, 2, 4]) == 120
+Js.Array.reduceRight((acc, item) => item /. acc, 1.0, [2.0, 4.0]) == 0.5 // 2.0 / (4.0 / 1.0)
+```
+*)
+
+external reduceRighti : (('b -> 'a -> int -> 'b)[@bs.uncurry]) -> 'b -> 'b
+  = "reduceRight"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+The `reduceRighti()` function takes three parameters: a *reducer function*, a
+beginning accumulator value, and an array. The reducer function has three
+parameters: an accumulated value, an element of the array, and the index of
+that element. `reduceRighti()` first calls the reducer function with the
+beginning value, the last element in the array, and its index (length of array
+minus one). The result becomes the new accumulator value, which is passed in to
+the reducer function along with the second element in the array and one (its
+index). `reduceRighti()` proceeds from right to left through the array, passing
+in the result of each stage as the accumulator to the reducer function.
+
+When all array elements are processed, the final value of the accumulator
+becomes the return value of `reduceRighti()`. See
+[`Array.reduceRight`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduceRight)
+on MDN.
+
+**NOTE:** In many cases, `reducei()` and `reduceRighti()` give the same result.
+However, there are cases where the order in which items are processed makes a
+difference.
+
+```res example
+// find sum of even-index elements in array
+let sumOfEvens = (accumulator, item, index) =>
+  if mod(index, 2) == 0 {
+    accumulator + item
+  } else {
+    accumulator
+  }
+
+Js.Array.reduceRighti(sumOfEvens, 0, [2, 5, 1, 4, 3]) == 6
+```
+*)
+
+external some : (('a -> bool)[@bs.uncurry]) -> bool = "some"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+Returns `true` if the predicate function given as the first argument to
+`some()` returns `true` for any element in the array; `false` otherwise.
+
+```res example
+let isEven = x => mod(x, 2) == 0
+
+Js.Array.some(isEven, [3, 7, 5, 2, 9]) == true
+Js.Array.some(isEven, [3, 7, 5, 1, 9]) == false
+```
+*)
+
+external somei : (('a -> int -> bool)[@bs.uncurry]) -> bool = "some"
+  [@@bs.send.pipe: 'a t as 'this]
+(**
+Returns `true` if the predicate function given as the first argument to
+`somei()` returns `true` for any element in the array; `false` otherwise. The
+predicate function has two arguments: an item from the array and the index
+value
+
+```res example
+// Does any string in the array
+// have the same length as its index?
+
+let sameLength = (str, index) => Js.String.length(str) == index
+
+// "ef" has length 2 and is it at index 2
+Js.Array.somei(sameLength, ["ab", "cd", "ef", "gh"]) == true
+// no item has the same length as its index
+Js.Array.somei(sameLength, ["a", "bc", "def", "gh"]) == false
+```
+*)
+
+(* commented out until bs has a plan for iterators
+   external values : 'a array_iter = "" [@@bs.send.pipe: 'a t as 'this] (* ES2015 *)
+*)
+external unsafe_get : 'a array -> int -> 'a = "%array_unsafe_get"
+(**
+Returns the value at the given position in the array if the position is in
+bounds; returns the JavaScript value `undefined` otherwise.
+
+```res example
+let arr = [100, 101, 102, 103]
+Js.Array.unsafe_get(arr, 3) == 103
+Js.Array.unsafe_get(arr, 4) // returns undefined
+```
+*)
+
+external unsafe_set : 'a array -> int -> 'a -> unit = "%array_unsafe_set"
+(**
+Sets the value at the given position in the array if the position is in bounds.
+If the index is out of bounds, well, “here there be dragons.“ *This function
+  modifies the original array.*
+
+```res example
+let arr = [100, 101, 102, 103]
+Js.Array.unsafe_set(arr, 3, 99)
+// result is [100, 101, 102, 99]
+
+Js.Array.unsafe_set(arr, 4, 88)
+// result is [100, 101, 102, 99, 88]
+
+Js.Array.unsafe_set(arr, 6, 77)
+// result is [100, 101, 102, 99, 88, <1 empty item>, 77]
+
+Js.Array.unsafe_set(arr, -1, 66)
+// you don't want to know.
+```
+*)