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.