Array
Utilities for Array functions.
Note about index syntax
Code like arr[0] does not compile to JavaScript arr[0]. Reason transforms
the [] index syntax into a function: Array.get(arr, 0). By default, this
uses the default standard library's Array.get function, which may raise an
exception if the index isn't found. If you open Belt, it will use the
Belt.Array.get function which returns options instead of raising exceptions.
See this for more information.
t
type t<'a> = array<'a>length
let length: t<'a> => intsize
let size: t<'a> => intget
let get: (t<'a>, int) => option<'a>If i <= 0 <= length(arr) returns Some(value) where value is the item at index i.
If i is out of range returns None.
Examples
RESCRIPTBelt.Array.get(["a", "b", "c"], 0) == Some("a")
Belt.Array.get(["a", "b", "c"], 3) == None
Belt.Array.get(["a", "b", "c"], -1) == None
getExn
let getExn: (t<'a>, int) => 'aRaise an exception if i is out of range.
Otherwise return the value at index i in arr.
getUnsafe
let getUnsafe: (t<'a>, int) => 'agetUnsafe(arr, i)
Unsafe
no bounds checking; this would cause type error if i does not stay within range
getUndefined
let getUndefined: (t<'a>, int) => Js.undefined<'a>getUndefined(arr, i)
It does the samething in the runtime as getUnsafe;
it is type safe since the return type still track whether it is
in range or not
set
let set: (t<'a>, int, 'a) => boolset(arr, n, x) modifies arr in place; it replaces the nth element of arr
with x. Returning false means not updated due to out of range.
setExn
let setExn: (t<'a>, int, 'a) => unitsetExn(arr, i, x) raise an exception if i is out of range.
setUnsafe
let setUnsafe: (t<'a>, int, 'a) => unitshuffleInPlace
let shuffleInPlace: t<'a> => unitshuffleInPlace(arr) randomly re-orders the items in arr
shuffle
let shuffle: t<'a> => t<'a>Returns a fresh array with items in original array randomly shuffled.
reverseInPlace
let reverseInPlace: t<'a> => unitreverseInPlace(arr) reverses items in arr in place.
Examples
RESCRIPTlet arr = [10, 11, 12, 13, 14]
let () = Belt.Array.reverseInPlace(arr)
arr == [14, 13, 12, 11, 10]
reverse
let reverse: t<'a> => t<'a>reverse(arr) returns a fresh array with items in arr in reverse order.
Examples
RESCRIPTBelt.Array.reverse([10, 11, 12, 13, 14]) == [14, 13, 12, 11, 10]
makeUninitialized
let makeUninitialized: int => array<Js.undefined<'a>>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.
Examples
RESCRIPTlet arr: array<Js.undefined<string>> = Belt.Array.makeUninitialized(5)
Belt.Array.getExn(arr, 0) == Js.undefined
makeUninitializedUnsafe
let makeUninitializedUnsafe: int => t<'a>Unsafe
Examples
RESCRIPTlet arr = Belt.Array.makeUninitializedUnsafe(5)
Js.log(Belt.Array.getExn(arr, 0)) // undefined
Belt.Array.setExn(arr, 0, "example")
Js.log(Belt.Array.getExn(arr, 0) == "example")
make
let make: (int, 'a) => t<'a>make(n, e) return an array of size n filled with value e.
Returns an empty array when n is negative.
range
let range: (int, int) => array<int>range(start, finish) create an inclusive array.
Examples
RESCRIPTBelt.Array.range(0, 3) == [0, 1, 2, 3]
Belt.Array.range(3, 0) == []
Belt.Array.range(3, 3) == [3]
rangeBy
let rangeBy: (int, int, ~step: int) => array<int>rangeBy(start, finish, ~step) returns empty array when step is 0 or negative.
It also return an empty array when start > finish.
Examples
RESCRIPTBelt.Array.rangeBy(0, 10, ~step=3) == [0, 3, 6, 9]
Belt.Array.rangeBy(0, 12, ~step=3) == [0, 3, 6, 9, 12]
Belt.Array.rangeBy(33, 0, ~step=1) == []
Belt.Array.rangeBy(33, 0, ~step=-1) == []
Belt.Array.rangeBy(3, 12, ~step=-1) == []
Belt.Array.rangeBy(3, 3, ~step=0) == []
Belt.Array.rangeBy(3, 3, ~step=1) == [3]
makeByU
let makeByU: (int, int => 'a) => t<'a>makeBy
let makeBy: (int, int => 'a) => t<'a>makeBy(n, f) return an empty array when n is negative return an array of size
n populated by f(i) start from 0 to n - 1.
Examples
RESCRIPTBelt.Array.makeBy(5, (i) => i) == [0, 1, 2, 3, 4]
Belt.Array.makeBy(5, (i) => i * i) == [0, 1, 4, 9, 16]
makeByAndShuffleU
let makeByAndShuffleU: (int, int => 'a) => t<'a>makeByAndShuffle
let makeByAndShuffle: (int, int => 'a) => t<'a>Equivalent to shuffle(makeBy(n, f))
zip
let zip: (t<'a>, array<'b>) => array<('a, 'b)>zip(a, b) create an array of pairs from corresponding elements of a and b.
Stop with the shorter array.
Examples
RESCRIPTBelt.Array.zip([1, 2], [3, 4, 5]) == [(1, 3), (2, 4)]
zipByU
let zipByU: (t<'a>, array<'b>, ('a, 'b) => 'c) => array<'c>zipBy
let zipBy: (t<'a>, array<'b>, ('a, 'b) => 'c) => array<'c>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), ((a, b)) => f(a, b))
Examples
RESCRIPTBelt.Array.zipBy([1, 2, 3], [4, 5], (a, b) => 2 * a + b) == [6, 9]
unzip
let unzip: array<('a, 'b)> => (t<'a>, array<'b>)unzip(a) takes an array of pairs and creates a pair of arrays. The first array
contains all the first items of the pairs; the second array contains all the
second items.
Examples
RESCRIPTBelt.Array.unzip([(1, 2), (3, 4)]) == ([1, 3], [2, 4])
Belt.Array.unzip([(1, 2), (3, 4), (5, 6), (7, 8)]) == ([1, 3, 5, 7], [2, 4, 6, 8])
concat
let concat: (t<'a>, t<'a>) => t<'a>concat(xs, ys) returns 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.
Examples
RESCRIPTBelt.Array.concat([1, 2, 3], [4, 5]) == [1, 2, 3, 4, 5]
Belt.Array.concat([], ["a", "b", "c"]) == ["a", "b", "c"]
concatMany
let concatMany: array<t<'a>> => t<'a>concatMany(xss) returns a fresh array as the concatenation of xss (an array of arrays)
Examples
RESCRIPTBelt.Array.concatMany([[1, 2, 3], [4, 5, 6], [7, 8]]) == [1, 2, 3, 4, 5, 6, 7, 8]
slice
let slice: (t<'a>, ~offset: int, ~len: int) => t<'a>slice(xs, offset, len) creates a new array with the len elements of xs
starting at offset for offset can be negative;and is evaluated as
length(xs) - offset(slice, xs) - 1(1) means get the last element as a
singleton array slice(xs, ~-len, len) will return a copy of the array if the
array does not have enough data; slice extracts through the end of sequence.
if len is negative; returns the empty array.
Examples
RESCRIPTBelt.Array.slice([10, 11, 12, 13, 14, 15, 16], ~offset=2, ~len=3) == [12, 13, 14]
Belt.Array.slice([10, 11, 12, 13, 14, 15, 16], ~offset=-4, ~len=3) == [13, 14, 15]
Belt.Array.slice([10, 11, 12, 13, 14, 15, 16], ~offset=4, ~len=9) == [14, 15, 16]
sliceToEnd
let sliceToEnd: (t<'a>, int) => t<'a>sliceToEnd(xs, offset) creates a new array with the elements of xs starting
at offset
offset can be negative; and is evaluated as length(xs) - offset(sliceToEnd, xs) - 1
means get the last element as a singleton array
sliceToEnd(xs, 0) will return a copy of the array
Examples
RESCRIPTBelt.Array.sliceToEnd([10, 11, 12, 13, 14, 15, 16], 2) == [12, 13, 14, 15, 16]
Belt.Array.sliceToEnd([10, 11, 12, 13, 14, 15, 16], -4) == [13, 14, 15, 16]
copy
let copy: t<'a> => t<'a>copy(a) returns a copy of a; that is; a fresh array containing the same
elements as a.
fill
let fill: (t<'a>, ~offset: int, ~len: int, 'a) => unitfill(arr, ~offset, ~len, x) modifies arr in place, storing x in elements
number offset to offset + len - 1. 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
Examples
RESCRIPTlet arr = Belt.Array.makeBy(5, (i) => i)
Belt.Array.fill(arr, ~offset=2, ~len=2, 9)
arr == [0, 1, 9, 9, 4]
Belt.Array.fill(arr, ~offset=7, ~len=2, 8)
arr == [0, 1, 9, 9, 4]
blit
let blit: (
~src: t<'a>,
~srcOffset: int,
~dst: t<'a>,
~dstOffset: int,
~len: int,
) => unitblit(~src=v1, ~srcOffset=o1, ~dst=v2, ~dstOffset=o2, ~len) copies len elements
from array v1;starting at element number o1;to array v2, starting at element
number o2. It works correctly even if v1 and v2 are the same array and the
source and destination chunks overlap.
offset can be negative; -1 means len - 1; if len + offset is still negative;it will be set as 0
For each of the examples;presume that v1 == [10, 11, 12, 13, 14, 15, 16, 17] and v2 == [20, 21, 22, 23, 24, 25, 26, 27]. The result shown is the content of the destination array.
Examples
RESCRIPTlet v1 = [10, 11, 12, 13, 14, 15, 16, 17]
let v2 = [20, 21, 22, 23, 24, 25, 26, 27]
Belt.Array.blit(~src=v1, ~srcOffset=4, ~dst=v2, ~dstOffset=2, ~len=3)
v2 == [20, 21, 14, 15, 16, 25, 26, 27]
Belt.Array.blit(~src=v1, ~srcOffset=4, ~dst=v1, ~dstOffset=2, ~len=3)
v1 == [10, 11, 14, 15, 16, 15, 16, 17]
blitUnsafe
let blitUnsafe: (
~src: t<'a>,
~srcOffset: int,
~dst: t<'a>,
~dstOffset: int,
~len: int,
) => unitUnsafe blit without bounds checking.
forEachU
let forEachU: (t<'a>, 'a => unit) => unitforEach
let forEach: (t<'a>, 'a => unit) => unitforEach(xs, f)
Call f on each element of xs from the beginning to end. f returns unit
so no new array is created. Use forEach when you are primarily concerned with
repetitively creating side effects.
Examples
RESCRIPTBelt.Array.forEach(["a", "b", "c"], x => Js.log("Item: " ++ x))
/*
prints:
Item: a
Item: b
Item: c
*/
let total = ref(0)
Belt.Array.forEach([1, 2, 3, 4], x => total := total.contents + x)
total.contents == 1 + 2 + 3 + 4
mapU
let mapU: (t<'a>, 'a => 'b) => array<'b>map
let map: (t<'a>, 'a => 'b) => array<'b>map(xs, f) returns a new array by calling f for each element of xs from
the beginning to end.
Examples
RESCRIPTBelt.Array.map([1, 2], (x) => x + 1) == [3, 4]
flatMapU
let flatMapU: (t<'a>, 'a => array<'b>) => array<'b>flatMap
let flatMap: (t<'a>, 'a => array<'b>) => array<'b>flatMap(xs, f) returns a new array by calling f for each element of xs from
the beginning to end, concatenating the results.
Examples
RESCRIPTBelt.Array.flatMap([1, 2], x => [x + 10, x + 20]) == [11, 21, 12, 22]
getByU
let getByU: (t<'a>, 'a => bool) => option<'a>getBy
let getBy: (t<'a>, 'a => bool) => option<'a>getBy(xs, p) returns Some(value) for the first value in xs that satisifies
the predicate function p; returns None if no element satisifies the function.
Examples
RESCRIPTBelt.Array.getBy([1, 4, 3, 2], (x) => mod(x, 2) == 0) == Some(4)
Belt.Array.getBy([15, 13, 11], (x) => mod(x, 2) == 0) == None
getIndexByU
let getIndexByU: (t<'a>, 'a => bool) => option<int>getIndexBy
let getIndexBy: (t<'a>, 'a => bool) => option<int>getIndexBy(xs, p) returns Some(index) for the first value in xs that
satisifies the predicate function p; returns None if no element satisifies
the function.
Examples
RESCRIPTBelt.Array.getIndexBy([1, 4, 3, 2], (x) => mod(x, 2) == 0) == Some(1)
Belt.Array.getIndexBy([15, 13, 11], (x) => mod(x, 2) == 0) == None
keepU
let keepU: (t<'a>, 'a => bool) => t<'a>keep
let keep: (t<'a>, 'a => bool) => t<'a>keep(xs, p) returns a new array that keep all elements satisfy p.
keepWithIndexU
let keepWithIndexU: (t<'a>, ('a, int) => bool) => t<'a>keepWithIndex
let keepWithIndex: (t<'a>, ('a, int) => bool) => t<'a>keepWithIndex(xs, p) returns a new array that keep all elements satisfy p.
Examples
RESCRIPTBelt.Array.keepWithIndex([1, 2, 3], (_x, i) => i == 1) == [2]
keepMapU
let keepMapU: (t<'a>, 'a => option<'b>) => array<'b>keepMap
let keepMap: (t<'a>, 'a => option<'b>) => array<'b>keepMap(xs, p) returns a new array that keep all elements that return a non
None applied p.
Examples
RESCRIPTBelt.Array.keepMap([1, 2, 3], x =>
if mod(x, 2) == 0 {
Some(x)
} else {
None
}
)
== [2]
forEachWithIndexU
let forEachWithIndexU: (t<'a>, (int, 'a) => unit) => unitforEachWithIndex
let forEachWithIndex: (t<'a>, (int, 'a) => unit) => unitforEachWithIndex(xs, f) same as Belt.Array.forEach, except that f is
supplied two arguments: the index starting from 0 and the element from xs.
Examples
RESCRIPTBelt.Array.forEachWithIndex(["a", "b", "c"], (i, x) => Js.log("Item " ++ Belt.Int.toString(i) ++ " is " ++ x))
/*
prints:
Item 0 is a
Item 1 is b
Item 2 is cc
*/
let total = ref(0)
Belt.Array.forEachWithIndex([10, 11, 12, 13], (i, x) => total := total.contents + x + i)
total.contents == 0 + 10 + 1 + 11 + 2 + 12 + 3 + 13
mapWithIndexU
let mapWithIndexU: (t<'a>, (int, 'a) => 'b) => array<'b>mapWithIndex
let mapWithIndex: (t<'a>, (int, 'a) => 'b) => array<'b>mapWithIndex(xs, f) applies f to each element of xs. Function f takes
two arguments: the index starting from 0 and the element from xs.
Examples
RESCRIPTBelt.Array.mapWithIndex([1, 2, 3], (i, x) => i + x) == [0 + 1, 1 + 2, 2 + 3]
partitionU
let partitionU: (t<'a>, 'a => bool) => (t<'a>, t<'a>)partition
let partition: (t<'a>, 'a => bool) => (t<'a>, t<'a>)partition(f, a) split array into tuple of two arrays based on predicate f;
first of tuple where predicate cause true, second where predicate cause false
Examples
RESCRIPTBelt.Array.partition([1, 2, 3, 4, 5], (x) => mod(x, 2) == 0) == ([2, 4], [1, 3, 5])
Belt.Array.partition([1, 2, 3, 4, 5], (x) => mod(x, 2) != 0) == ([1, 3, 5], [2, 4])
reduceU
let reduceU: (array<'b>, 'a, ('a, 'b) => 'a) => 'areduce
let reduce: (array<'b>, 'a, ('a, 'b) => 'a) => 'areduce(xs, init, f) applies f to each element of xs from beginning to end.
Function f has two parameters: the item from the list and an “accumulator”;
which starts with a value of init. reduce returns the final value of the
accumulator.
Examples
RESCRIPTBelt.Array.reduce([2, 3, 4], 1, (a, b) => a + b) == 10
Belt.Array.reduce(["a", "b", "c", "d"], "", (a, b) => a ++ b) == "abcd"
reduceReverseU
let reduceReverseU: (array<'b>, 'a, ('a, 'b) => 'a) => 'areduceReverse
let reduceReverse: (array<'b>, 'a, ('a, 'b) => 'a) => 'areduceReverse(xs, init, f) works like Belt.Array.reduce except that
function f is applied to each item of xs from the last back to the first.
Examples
RESCRIPTBelt.Array.reduceReverse(["a", "b", "c", "d"], "", (a, b) => a ++ b) == "dcba"
reduceReverse2U
let reduceReverse2U: (t<'a>, array<'b>, 'c, ('c, 'a, 'b) => 'c) => 'creduceReverse2
let reduceReverse2: (t<'a>, array<'b>, 'c, ('c, 'a, 'b) => 'c) => 'creduceReverse2(xs, ys, init, f) reduces two arrays xs and ys;taking items
starting at min(length(xs), length(ys)) down to and including zero.
Examples
RESCRIPTBelt.Array.reduceReverse2([1, 2, 3], [1, 2], 0, (acc, x, y) => acc + x + y) == 6
reduceWithIndexU
let reduceWithIndexU: (t<'a>, 'b, ('b, 'a, int) => 'b) => 'breduceWithIndex
let reduceWithIndex: (t<'a>, 'b, ('b, 'a, int) => 'b) => 'bApplies f to each element of xs from beginning to end. Function f has
three parameters: the item from the array and an “accumulator”, which starts
with a value of init and the index of each element. reduceWithIndex returns
the final value of the accumulator.
Examples
RESCRIPTBelt.Array.reduceWithIndex([1, 2, 3, 4], 0, (acc, x, i) => acc + x + i) == 16
joinWithU
let joinWithU: (t<'a>, string, 'a => string) => stringjoinWith
let joinWith: (t<'a>, string, 'a => string) => stringjoinWith(xs, sep, toString)
Concatenates all the elements of xs converted to string with toString, each
separated by sep, the string given as the second argument, into a single string.
If the array has only one element, then that element will be returned without
using the separator. If the array is empty, the empty string will be returned.
Examples
RESCRIPTBelt.Array.joinWith([0, 1], ", ", Js.Int.toString) == "0, 1"
Belt.Array.joinWith([], " ", Js.Int.toString) == ""
Belt.Array.joinWith([1], " ", Js.Int.toString) == "1"
someU
let someU: (t<'a>, 'a => bool) => boolsome
let some: (t<'a>, 'a => bool) => boolsome(xs, p) returns true if at least one of the elements in xs satifies p;
where p is a predicate: a function taking an element and returning a bool.
Examples
RESCRIPTBelt.Array.some([2, 3, 4], (x) => mod(x, 2) == 1) == true
Belt.Array.some([(-1), (-3), (-5)], (x) => x > 0) == false
everyU
let everyU: (t<'a>, 'a => bool) => boolevery
let every: (t<'a>, 'a => bool) => boolevery(xs, p) returns true if all elements satisfy p; where p is a
predicate: a function taking an element and returning a bool.
Examples
RESCRIPTBelt.Array.every([1, 3, 5], (x) => mod(x, 2) == 1) == true
Belt.Array.every([1, (-3), 5], (x) => x > 0) == false
every2U
let every2U: (t<'a>, array<'b>, ('a, 'b) => bool) => boolevery2
let every2: (t<'a>, array<'b>, ('a, 'b) => bool) => boolevery2(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)))
Examples
RESCRIPTBelt.Array.every2([1, 2, 3], [0, 1], (a, b) => a > b) == true
Belt.Array.every2([], [1], (x, y) => x > y) == true
Belt.Array.every2([2, 3], [1], (x, y) => x > y) == true
Belt.Array.every2([0, 1], [5, 0], (x, y) => x > y) == false
some2U
let some2U: (t<'a>, array<'b>, ('a, 'b) => bool) => boolsome2
let some2: (t<'a>, array<'b>, ('a, 'b) => bool) => boolsome2(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)))
Examples
RESCRIPTBelt.Array.some2([0, 2], [1, 0, 3], (a, b) => a > b) == true
Belt.Array.some2([], [1], (x, y) => x > y) == false
Belt.Array.some2([2, 3], [1, 4], (x, y) => x > y) == true
cmpU
let cmpU: (t<'a>, t<'a>, ('a, 'a) => int) => intcmp
let cmp: (t<'a>, t<'a>, ('a, 'a) => int) => intcmp(xs, ys, f) compared by length if length(xs) != length(ys); returning -1
if length(xs) < length(ys) or 1 if length(xs) > length(ys). Otherwise
compare one by one f(x, y). f returns a negative number if x is “less than” y
zero if x is “equal to” y a positive number if x is “greater than”
y. The comparison returns the first non-zero result of f; or zero if f
returns zero for all x and y.
Examples
RESCRIPTBelt.Array.cmp([1, 3, 5], [1, 4, 2], (a, b) => compare(a, b)) == -1
Belt.Array.cmp([1, 3, 5], [1, 2, 3], (a, b) => compare(a, b)) == 1
Belt.Array.cmp([1, 3, 5], [1, 3, 5], (a, b) => compare(a, b)) == 0
eqU
let eqU: (t<'a>, t<'a>, ('a, 'a) => bool) => booleq
let eq: (t<'a>, t<'a>, ('a, 'a) => bool) => booleq(xs, ys) return false if length is not the same otherwise compare items
one by one using f(xi, yi); and return true if all results are true false otherwise
Examples
RESCRIPTBelt.Array.eq([1, 2, 3], [(-1), (-2), (-3)], (a, b) => abs(a) == abs(b)) == true
truncateToLengthUnsafe
let truncateToLengthUnsafe: (t<'a>, int) => unitUnsafe 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.
Examples
RESCRIPTlet arr = ["ant", "bee", "cat", "dog", "elk"]
Belt.Array.truncateToLengthUnsafe(arr, 3)
arr == ["ant", "bee", "cat"]
initU
let initU: (int, int => 'a) => t<'a>init
let init: (int, int => 'a) => t<'a>push
let push: (t<'a>, 'a) => unitarr->push(item) pushes an element item into an array arr.