API / Belt / Set

You are currently looking at the v6.0 - v8.2 docs (Reason v3.6 syntax edition). You can find the latest API docs here.

(These docs cover all versions between v3 to v8 and are equivalent to the old BuckleScript docs before the rebrand)

Set

A immutable sorted set module which allows customize compare behavior. The implementation uses balanced binary trees, and therefore searching and insertion take time logarithmic in the size of the map.

It also has three specialized inner modules Belt.Set.Int, Belt.Set.String and Belt.Set.Dict - This module separates data from function which is more verbose but slightly more efficient

RE
module PairComparator =
  Belt.Id.MakeComparable({
    type t = (int, int);
    let cmp = ((a0, a1), (b0, b1)) =>
      switch (Pervasives.compare(a0, b0)) {
      | 0 => Pervasives.compare(a1, b1)
      | c => c
      };
  });

let mySet = Belt.Set.make(~id=(module PairComparator));
let mySet2 = Belt.Set.add(mySet, (1, 2));

Note: This module's examples will assume a predeclared module for integers called IntCmp. It is declared like this:

RE
module IntCmp =
  Belt.Id.MakeComparable({
    type t = int;
    let cmp = Pervasives.compare;
  });

t

RE
type t('value, 'identity);

'value is the element type

'identity the identity of the collection

id

RE
type id('value, 'id) = Belt_Id.comparable('value, 'id);

The identity needed for making a set from scratch

make

RE
let make: (~id: id('value, 'id)) => t('value, 'id);

Creates a new set by taking in the comparator

RE
let set = Belt.Set.make(~id=(module IntCmp));

fromArray

RE
let fromArray: (array('value), ~id: id('value, 'id)) => t('value, 'id);

Creates new set from array of elements.

RE
let s0 = Belt.Set.fromArray([|1, 3, 2, 4|], ~id=(module IntCmp))

s0->Belt.Set.toArray; /* [|1, 2, 3, 4|] */

fromSortedArrayUnsafe

RE
let fromSortedArrayUnsafe: (array('value), ~id: id('value, 'id)) => t('value, 'id);

The same as [fromArray][#fromarray] except it is after assuming the input array is already sorted.

isEmpty

RE
let isEmpty: t('a, 'b) => bool;

Checks if set is empty.

RE
let empty = Belt.Set.fromArray([||], ~id=(module IntCmp));
let notEmpty = Belt.Set.fromArray([|1|],~id=(module IntCmp));

Belt.Set.isEmpty(empty); /* true */
Belt.Set.isEmpty(notEmpty); /* false */

has

RE
let has: (t('value, 'id), 'value) => bool;

Checks if element exists in set.

RE
let set = Belt.Set.fromArray([|1, 4, 2, 5|], ~id=(module IntCmp));

set->Belt.Set.has(3) /* false */
set->Belt.Set.has(1) /* true */

add

RE
let add: (t('value, 'id), 'value) => t('value, 'id);

Adds element to set. If element existed in set, value is unchanged.

RE
let s0 = Belt.Set.make(~id=(module IntCmp));
let s1 = s0->Belt.Set.add(1);
let s2 = s1->Belt.Set.add(2);
let s3 = s2->Belt.Set.add(2);
s0->Belt.Set.toArray; /* [||] */
s1->Belt.Set.toArray; /* [|1|] */
s2->Belt.Set.toArray; /* [|1, 2|] */
s3->Belt.Set.toArray; /* [|1,2 |] */
s2 == s3; /* true */

mergeMany

RE
let mergeMany: (t('value, 'id), array('value)) => t('value, 'id);

Adds each element of array to set. Unlike add, the reference of return value might be changed even if all values in array already exist in set

RE
let set = Belt.Set.make(~id=(module IntCmp));

let newSet = set->Belt.Set.mergeMany([|5, 4, 3, 2, 1|]);
newSet->Belt.Set.toArray; /* [|1, 2, 3, 4, 5|] */

remove

RE
let remove: (t('value, 'id), 'value) => t('value, 'id);

Removes element from set. If element wasn't existed in set, value is unchanged.

RE
let s0 = Belt.Set.fromArray([|2,3,1,4,5|], ~id=(module IntCmp));
let s1 = s0->Belt.Set.remove(1);
let s2 = s1->Belt.Set.remove(3);
let s3 = s2->Belt.Set.remove(3);

s1->Belt.Set.toArray; /* [|2,3,4,5|] */
s2->Belt.Set.toArray; /* [|2,4,5|] */
s2 == s3; /* true */

removeMany

RE
let removeMany: (t('value, 'id), array('value)) => t('value, 'id);

Removes each element of array from set. Unlike remove, the reference of return value might be changed even if any values in array not existed in set.

RE
let set = Belt.Set.fromArray([|1, 2, 3, 4|],~id=(module IntCmp));

let newSet = set->Belt.Set.removeMany([|5, 4, 3, 2, 1|]);
newSet->Belt.Set.toArray; /* [||] */

union

RE
let union: (t('value, 'id), t('value, 'id)) => t('value, 'id);

Returns union of two sets.

RE
let s0 = Belt.Set.fromArray([|5,2,3,5,6|], ~id=(module IntCmp));
let s1 = Belt.Set.fromArray([|5,2,3,1,5,4|], ~id=(module IntCmp));
let union = Belt.Set.union(s0, s1);
union->Belt.Set.toArray; /* [|1,2,3,4,5,6|] */

intersect

RE
let intersect: (t('value, 'id), t('value, 'id)) => t('value, 'id);

Returns intersection of two sets.

RE
let s0 = Belt.Set.fromArray([|5,2,3,5,6|], ~id=(module IntCmp));
let s1 = Belt.Set.fromArray([|5,2,3,1,5,4|], ~id=(module IntCmp));
let intersect = Belt.Set.intersect(s0, s1);
intersect->Belt.Set.toArray; /* [|2,3,5|] */

diff

RE
let diff: (t('value, 'id), t('value, 'id)) => t('value, 'id);

Returns elements from first set, not existing in second set.

RE
let s0 = Belt.Set.fromArray([|5,2,3,5,6|], ~id=(module IntCmp));
let s1 = Belt.Set.fromArray([|5,2,3,1,5,4|], ~id=(module IntCmp));
Belt.Set.toArray(Belt.Set.diff(s0, s1)); /* [|6|] */
Belt.Set.toArray(Belt.Set.diff(s1,s0)); /* [|1,4|] */

subset

RE
let subset: (t('value, 'id), t('value, 'id)) => bool;

Checks if second set is subset of first set.

RE
let s0 = Belt.Set.fromArray([|5,2,3,5,6|], ~id=(module IntCmp));
let s1 = Belt.Set.fromArray([|5,2,3,1,5,4|], ~id=(module IntCmp));
let s2 = Belt.Set.intersect(s0, s1);
Belt.Set.subset(s2, s0); /* true */
Belt.Set.subset(s2, s1); /* true */
Belt.Set.subset(s1, s0); /* false */

cmp

RE
let cmp: (t('value, 'id), t('value, 'id)) => int;

Total ordering between sets. Can be used as the ordering function for doing sets of sets. It compares size first and then iterates over each element following the order of elements.

eq

RE
let eq: (t('value, 'id), t('value, 'id)) => bool;

Checks if two sets are equal.

RE
let s0 = Belt.Set.fromArray([|5,2,3|], ~id=(module IntCmp));
let s1 = Belt.Set.fromArray([|3,2,5|], ~id=(module IntCmp));

Belt.Set.eq(s0, s1); /* true */

forEachU

RE
let forEachU: (t('value, 'id), [@bs] ('value => unit)) => unit;

Same as forEach but takes uncurried functon.

forEach

RE
let forEach: (t('value, 'id), 'value => unit) => unit;

Applies function f in turn to all elements of set in increasing order.

RE
let s0 = Belt.Set.fromArray([|5,2,3,5,6|], ~id=(module IntCmp));
let acc = ref([]);
s0->Belt.Set.forEach(x => {
  acc := Belt.List.add(acc^, x)
});
acc; /* [6,5,3,2] */

reduceU

RE
let reduceU: (t('value, 'id), 'a, [@bs] (('a, 'value) => 'a)) => 'a;

reduce

RE
let reduce: (t('value, 'id), 'a, ('a, 'value) => 'a) => 'a;

Applies function f to each element of set in increasing order. Function f has two parameters: the item from the set and an “accumulator”, which starts with a value of initialValue. reduce returns the final value of the accumulator.

RE
let s0 = Belt.Set.fromArray([|5,2,3,5,6|], ~id=(module IntCmp));
s0->Belt.Set.reduce([], (acc, element) =>
  acc->Belt.List.add(element)
); /* [6,5,3,2] */

everyU

RE
let everyU: (t('value, 'id), [@bs] ('value => bool)) => bool;

every

RE
let every: (t('value, 'id), 'value => bool) => bool;

Checks if all elements of the set satisfy the predicate. Order unspecified.

RE
let isEven = x => x mod 2 == 0;

let s0 = Belt.Set.fromArray([|2,4,6,8|], ~id=(module IntCmp));
s0->Belt.Set.every(isEven); /* true */

someU

RE
let someU: (t('value, 'id), [@bs] ('value => bool)) => bool;

some

RE
let some: (t('value, 'id), 'value => bool) => bool;

Checks if at least one element of the set satisfies the predicate.

RE
let isOdd = x => x mod 2 != 0;

let s0 = Belt.Set.fromArray([|1,2,4,6,8|], ~id=(module IntCmp));
s0->Belt.Set.some(isOdd); /* true */

keepU

RE
let keepU: (t('value, 'id), [@bs] ('value => bool)) => t('value, 'id);

keep

RE
let keep: (t('value, 'id), 'value => bool) => t('value, 'id);

Returns the set of all elements that satisfy the predicate.

RE
let isEven = x => x mod 2 == 0;

let s0 = Belt.Set.fromArray([|1,2,3,4,5|], ~id=(module IntCmp));
let s1 = s0->Belt.Set.keep(isEven);

s1->Belt.Set.toArray; /* [|2,4|] */

partitionU

RE
let partitionU: (t('value, 'id), [@bs] ('value => bool)) => (t('value, 'id), t('value, 'id));

partition

RE
let partition: (t('value, 'id), 'value => bool) => (t('value, 'id), t('value, 'id));

Returns a pair of sets, where first is the set of all the elements of set that satisfy the predicate, and second is the set of all the elements of set that do not satisfy the predicate.

RE
let isOdd = x => x mod 2 != 0;

let s0 = Belt.Set.fromArray([|1,2,3,4,5|], ~id=(module IntCmp));
let (s1, s2) = s0->Belt.Set.partition(isOdd);

s1->Belt.Set.toArray; /* [|1,3,5|] */
s2->Belt.Set.toArray; /* [|2,4|] */

size

RE
let size: t('value, 'id) => int;

Returns size of the set.

RE
let s0 = Belt.Set.fromArray([|1,2,3,4|], ~id=(module IntCmp));

s0->Belt.Set.size; /* 4 */

toArray

RE
let toArray: t('value, 'id) => array('value);

Returns array of ordered set elements.

RE
let s0 = Belt.Set.fromArray([|3,2,1,5|], ~id=(module IntCmp));

s0->Belt.Set.toArray; /* [|1,2,3,5|] */

toList

RE
let toList: t('value, 'id) => list('value);

Returns list of ordered set elements.

RE
let s0 = Belt.Set.fromArray([|3,2,1,5|], ~id=(module IntCmp));

s0->Belt.Set.toList; /* [1,2,3,5] */

minimum

RE
let minimum: t('value, 'id) => option('value);

Returns minimum value of the collection. None if collection is empty.

RE
let s0 = Belt.Set.make(~id=(module IntCmp));
let s1 = Belt.Set.fromArray([|3,2,1,5|], ~id=(module IntCmp));

s0->Belt.Set.minimum; /* None */
s1->Belt.Set.minimum; /* Some(1) */

minUndefined

RE
let minUndefined: t('value, 'id) => Js.undefined('value);

Returns minimum value of the collection. undefined if collection is empty.

RE
let s0 = Belt.Set.make(~id=(module IntCmp));
let s1 = Belt.Set.fromArray([|3,2,1,5|], ~id=(module IntCmp));

s0->Belt.Set.minUndefined; /* undefined */
s1->Belt.Set.minUndefined; /* 1 */

maximum

Returns maximum value of the collection. None if collection is empty.

RE
let s0 = Belt.Set.make(~id=(module IntCmp));
let s1 = Belt.Set.fromArray([|3,2,1,5|], ~id=(module IntCmp));

s0->Belt.Set.maximum; /* None */
s1->Belt.Set.maximum; /* Some(5) */

maxUndefined

RE
let maxUndefined: t('value, 'id) => Js.undefined('value);

Returns maximum value of the collection. undefined if collection is empty.

RE
let s0 = Belt.Set.make(~id=(module IntCmp));
let s1 = Belt.Set.fromArray([|3,2,1,5|], ~id=(module IntCmp));

s0->Belt.Set.maxUndefined; /* undefined */
s1->Belt.Set.maxUndefined; /* 5 */

get

RE
let get: (t('value, 'id), 'value) => option('value);

Returns the reference of the value which is equivalent to value using the comparator specifiecd by this collection. Returns None if element does not exist.

RE
let s0 = Belt.Set.fromArray([|1,2,3,4,5|], ~id=(module IntCmp));

s0->Belt.Set.get(3); /* Some(3) */
s0->Belt.Set.get(20); /* None */

getUndefined

RE
let getUndefined: (t('value, 'id), 'value) => Js.undefined('value);

Same as get but returns undefined when element does not exist.

getExn

RE
let getExn: (t('value, 'id), 'value) => 'value;

Same as get but raise when element does not exist.

split

RE
let split: (t('value, 'id), 'value) => ((t('value, 'id), t('value, 'id)), bool);

Returns a tuple ((smaller, larger), present), present is true when element exist in set.

RE
let s0 = Belt.Set.fromArray([|1,2,3,4,5|], ~id=(module IntCmp));

let ((smaller, larger), present) = s0->Belt.Set.split(3);

present; /* true */
smaller->Belt.Set.toArray; /* [|1,2|] */
larger->Belt.Set.toArray; /* [|4,5|] */

getData

RE
let getData: t('value, 'id) => Belt_SetDict.t('value, 'id);

Advanced usage only

Returns the raw data (detached from comparator), but its type is still manifested, so that user can pass identity directly without boxing.

getId

RE
let getId: t('value, 'id) => id('value, 'id);

Advanced usage only

Returns the identity of set.

packIdData

RE
let packIdData: (~id: id('value, 'id), ~data: Belt_SetDict.t('value, 'id)) => t('value, 'id);

Advanced usage only

Returns the packed collection.