API / Js / Array

Array

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:

Examples

RESCRIPT
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:

RESCRIPT
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)
}

t

RESCRIPT
type t<'a> = array<'a>

The type used to describe a JavaScript array.

array_like

RESCRIPT
type array_like<'a> = Js_array2.array_like<'a>

A type used to describe JavaScript objects that are like an array or are iterable.

from

RESCRIPT
let from: array_like<'a> => array<'a>

Creates a shallow copy of an array from an array-like object. See Array.from on MDN.

Examples

RESCRIPT
let strArr = Js.String.castToArrayLike("abcd")
Js.Array.from(strArr) == ["a", "b", "c", "d"]

fromMap

RESCRIPT
let fromMap: (array_like<'a>, 'a => 'b) => array<'b>

Creates a new array by applying a function (the second argument) to each item in the array_like first argument. See Array.from on MDN.

Examples

RESCRIPT
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]

isArray

RESCRIPT
let isArray: 'a => bool

length

RESCRIPT
let length: array<'a> => int

Returns the number of elements in the array. See Array.length on MDN.

copyWithin

RESCRIPT
let copyWithin: (~to_: int, t<'a>) => t<'a>

copyWithinFrom

RESCRIPT
let copyWithinFrom: (~to_: int, ~from: int, t<'a>) => t<'a>

copyWithinFromRange

RESCRIPT
let copyWithinFromRange: (~to_: int, ~start: int, ~end_: int, t<'a>) => t<'a>

fillInPlace

RESCRIPT
let fillInPlace: ('a, t<'a>) => t<'a>

fillFromInPlace

RESCRIPT
let fillFromInPlace: ('a, ~from: int, t<'a>) => t<'a>

fillRangeInPlace

RESCRIPT
let fillRangeInPlace: ('a, ~start: int, ~end_: int, t<'a>) => t<'a>

pop

RESCRIPT
let pop: t<'a> => option<'a>

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 on MDN.

Examples

RESCRIPT
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

push

RESCRIPT
let push: ('a, t<'a>) => int

pushMany

RESCRIPT
let pushMany: (array<'a>, t<'a>) => int

reverseInPlace

RESCRIPT
let reverseInPlace: t<'a> => t<'a>

Returns an array with the elements of the input array in reverse order. This function modifies the original array. See Array.reverse on MDN.

Examples

RESCRIPT
let arr = ["ant", "bee", "cat"]
Js.Array.reverseInPlace(arr) == ["cat", "bee", "ant"]
arr == ["cat", "bee", "ant"]

shift

RESCRIPT
let shift: t<'a> => option<'a>

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 on MDN.

Examples

RESCRIPT
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

sortInPlace

RESCRIPT
let sortInPlace: t<'a> => t<'a>

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 on MDN.

Examples

RESCRIPT
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]

sortInPlaceWith

RESCRIPT
let sortInPlaceWith: (('a, 'a) => int, t<'a>) => t<'a>

spliceInPlace

RESCRIPT
let spliceInPlace: (~pos: int, ~remove: int, ~add: array<'a>, t<'a>) => t<'a>

removeFromInPlace

RESCRIPT
let removeFromInPlace: (~pos: int, t<'a>) => t<'a>

removeCountInPlace

RESCRIPT
let removeCountInPlace: (~pos: int, ~count: int, t<'a>) => t<'a>

unshift

RESCRIPT
let unshift: ('a, t<'a>) => int

unshiftMany

RESCRIPT
let unshiftMany: (array<'a>, t<'a>) => int

concat

RESCRIPT
let concat: (t<'a>, t<'a>) => t<'a>

concatMany

RESCRIPT
let concatMany: (array<t<'a>>, t<'a>) => t<'a>

includes

RESCRIPT
let includes: ('a, t<'a>) => bool

indexOf

RESCRIPT
let indexOf: ('a, t<'a>) => int

indexOfFrom

RESCRIPT
let indexOfFrom: ('a, ~from: int, t<'a>) => int

join

Deprecated

please use joinWith instead

RESCRIPT
let join: t<'a> => string

joinWith

RESCRIPT
let joinWith: (string, t<'a>) => string

lastIndexOf

RESCRIPT
let lastIndexOf: ('a, t<'a>) => int

lastIndexOfFrom

RESCRIPT
let lastIndexOfFrom: ('a, ~from: int, t<'a>) => int

slice

RESCRIPT
let slice: (~start: int, ~end_: int, t<'a>) => t<'a>

copy

RESCRIPT
let copy: t<'a> => t<'a>

Returns a copy of the entire array. Same as Js.Array.Slice(~start=0, ~end_=Js.Array.length(arr), arr). See Array.slice on MDN.

sliceFrom

RESCRIPT
let sliceFrom: (int, t<'a>) => t<'a>

toString

RESCRIPT
let toString: t<'a> => string

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 on MDN.

Examples

RESCRIPT
Js.Array.toString([3.5, 4.6, 7.8]) == "3.5,4.6,7.8"
Js.Array.toString(["a", "b", "c"]) == "a,b,c"

toLocaleString

RESCRIPT
let toLocaleString: t<'a> => string

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 on MDN.

Examples

RESCRIPT
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

every

RESCRIPT
let every: ('a => bool, t<'a>) => bool

everyi

RESCRIPT
let everyi: (('a, int) => bool, t<'a>) => bool

filter

RESCRIPT
let filter: ('a => bool, t<'a>) => t<'a>

filteri

RESCRIPT
let filteri: (('a, int) => bool, t<'a>) => t<'a>

find

RESCRIPT
let find: ('a => bool, t<'a>) => option<'a>

findi

RESCRIPT
let findi: (('a, int) => bool, t<'a>) => option<'a>

findIndex

RESCRIPT
let findIndex: ('a => bool, t<'a>) => int

findIndexi

RESCRIPT
let findIndexi: (('a, int) => bool, t<'a>) => int

forEach

RESCRIPT
let forEach: ('a => unit, t<'a>) => unit

forEachi

RESCRIPT
let forEachi: (('a, int) => unit, t<'a>) => unit

map

RESCRIPT
let map: ('a => 'b, t<'a>) => t<'b>

mapi

RESCRIPT
let mapi: (('a, int) => 'b, t<'a>) => t<'b>

reduce

RESCRIPT
let reduce: (('a, 'b) => 'a, 'a, t<'b>) => 'a

reducei

RESCRIPT
let reducei: (('a, 'b, int) => 'a, 'a, t<'b>) => 'a

reduceRight

RESCRIPT
let reduceRight: (('a, 'b) => 'a, 'a, t<'b>) => 'a

reduceRighti

RESCRIPT
let reduceRighti: (('a, 'b, int) => 'a, 'a, t<'b>) => 'a

some

RESCRIPT
let some: ('a => bool, t<'a>) => bool

somei

RESCRIPT
let somei: (('a, int) => bool, t<'a>) => bool

unsafe_get

RESCRIPT
let unsafe_get: (array<'a>, int) => 'a

Returns the value at the given position in the array if the position is in bounds; returns the JavaScript value undefined otherwise.

Examples

RESCRIPT
let arr = [100, 101, 102, 103]
Js.Array.unsafe_get(arr, 3) == 103
Js.Array.unsafe_get(arr, 4) // returns undefined

unsafe_set

RESCRIPT
let unsafe_set: (array<'a>, int, 'a) => unit

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.

Examples

RESCRIPT
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.