diff --git a/jscomp/others/belt_MutableSetInt.mli b/jscomp/others/belt_MutableSetInt.mli index 48fb77f8f9..0167754d4a 100644 --- a/jscomp/others/belt_MutableSetInt.mli +++ b/jscomp/others/belt_MutableSetInt.mli @@ -30,92 +30,419 @@ and identity is not needed(using the built-in one) **See** [`Belt.MutableSet`]() + + This module is [Belt.MutableSet](mutable-set) specialized with key type to be a `int` type. + It is more efficient in general, the API is the same with [Belt.MutableSet](mutable-set) except its key type is fixed, and identity is not needed (using the built-in one). *) # 38 "others/setm.cppo.mli" type value = int - + # 42 "others/setm.cppo.mli" (** The type of the set elements. *) type t -(** The type of sets. *) +(** + The type of sets. +*) val make: unit -> t +(** + Returns empty set. + + ```res example + let set = Belt.MutableSet.Int.make() + ``` +*) val fromArray: value array -> t +(** + Creates new set from array of elements. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([1, 3, 2, 4]) + + s0->Belt.MutableSet.Int.toArray /* [1, 2, 3, 4] */ + ``` +*) + val fromSortedArrayUnsafe: value array -> t +(** + The same as [fromArray][#fromarray] except it is after assuming the input array is already sorted. +*) val copy: t -> t +(** + Returns copy of a set. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([1, 3, 2, 4]) + + let copied = s0->Belt.MutableSet.Int.copy + copied->Belt.MutableSet.Int.toArray /* [1, 2, 3, 4] */ + ``` +*) + val isEmpty: t -> bool +(** + Checks if set is empty. + + ```res example + let empty = Belt.MutableSet.Int.fromArray([]) + let notEmpty = Belt.MutableSet.Int.fromArray([1]) + + Belt.MutableSet.Int.isEmpty(empty) /* true */ + Belt.MutableSet.Int.isEmpty(notEmpty) /* false */ + ``` +*) + val has: t -> value -> bool +(** + Checks if element exists in set. + + ```res example + let set = Belt.MutableSet.Int.fromArray([1, 4, 2, 5]) + + set->Belt.MutableSet.Int.has(3) /* false */ + set->Belt.MutableSet.Int.has(1) /* true */ + ``` +*) val add: t -> value -> unit +(** + Adds element to set. If element existed in set, value is unchanged. + + ```res example + let s0 = Belt.MutableSet.Int.make() + s0->Belt.MutableSet.Int.add(1) + s0->Belt.MutableSet.Int.add(2) + s0->Belt.MutableSet.Int.add(2) + + s0->Belt.MutableSet.Int.toArray /* [1, 2] */ + ``` +*) + val addCheck: t -> value -> bool + val mergeMany: t -> value array -> unit +(** + Adds each element of array to set. Unlike [add](#add), the reference of return value might be changed even if all values in array already exist in set + + ```res example + let set = Belt.MutableSet.Int.make() + + set->Belt.MutableSet.Int.mergeMany([5, 4, 3, 2, 1]) + set->Belt.MutableSet.Int.toArray /* [1, 2, 3, 4, 5] */ + ``` +*) + val remove: t -> value -> unit +(** + Removes element from set. If element wasn't existed in set, value is unchanged. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([2, 3, 1, 4, 5]) + s0->Belt.MutableSet.Int.remove(1) + s0->Belt.MutableSet.Int.remove(3) + s0->Belt.MutableSet.Int.remove(3) + + s0->Belt.MutableSet.Int.toArray /* [2,4,5] */ + ``` +*) + val removeCheck: t -> value -> bool + val removeMany: t -> value array -> unit +(** + Removes each element of array from set. + + ```res example + let set = Belt.MutableSet.Int.fromArray([1, 2, 3, 4]) + + set->Belt.MutableSet.Int.removeMany([5, 4, 3, 2, 1]) + set->Belt.MutableSet.Int.toArray /* [] */ + ``` +*) val union: t -> t -> t +(** + Returns union of two sets. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([5, 2, 3, 5, 6]) + let s1 = Belt.MutableSet.Int.fromArray([5, 2, 3, 1, 5, 4]) + let union = Belt.MutableSet.Int.union(s0, s1) + union->Belt.MutableSet.Int.toArray /* [1,2,3,4,5,6] */ + ``` +*) + val intersect: t -> t -> t +(** + Returns intersection of two sets. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([5, 2, 3, 5, 6]) + let s1 = Belt.MutableSet.Int.fromArray([5, 2, 3, 1, 5, 4]) + let intersect = Belt.MutableSet.Int.intersect(s0, s1) + intersect->Belt.MutableSet.Int.toArray /* [2,3,5] */ + ``` +*) + val diff: t -> t -> t +(** + Returns elements from first set, not existing in second set. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([5, 2, 3, 5, 6]) + let s1 = Belt.MutableSet.Int.fromArray([5, 2, 3, 1, 5, 4]) + Belt.MutableSet.Int.toArray(Belt.MutableSet.Int.diff(s0, s1)) /* [6] */ + Belt.MutableSet.Int.toArray(Belt.MutableSet.Int.diff(s1, s0)) /* [1,4] */ + ``` +*) + val subset: t -> t -> bool +(** + Checks if second set is subset of first set. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([5, 2, 3, 5, 6]) + let s1 = Belt.MutableSet.Int.fromArray([5, 2, 3, 1, 5, 4]) + let s2 = Belt.MutableSet.Int.intersect(s0, s1) + Belt.MutableSet.Int.subset(s2, s0) /* true */ + Belt.MutableSet.Int.subset(s2, s1) /* true */ + Belt.MutableSet.Int.subset(s1, s0) /* false */ + ``` +*) val cmp: t -> t -> 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. +*) + val eq: t -> t -> bool +(** + Checks if two sets are equal. + ```res example + let s0 = Belt.MutableSet.Int.fromArray([5, 2, 3]) + let s1 = Belt.MutableSet.Int.fromArray([3, 2, 5]) + + Belt.MutableSet.Int.eq(s0, s1) /* true */ + ``` +*) val forEachU: t -> (value -> unit [@bs]) -> unit +(** + Same as [forEach](##forEach) but takes uncurried functon. +*) + val forEach: t -> (value -> unit ) -> unit -(** In increasing order*) +(** + Applies function `f` in turn to all elements of set in increasing order. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([5, 2, 3, 5, 6]) + let acc = ref(list{}) + s0->Belt.MutableSet.Int.forEach(x => acc := Belt.List.add(acc.contents, x)) + acc /* [6,5,3,2] */ + ``` +*) val reduceU: t -> 'a -> ('a -> value -> 'a [@bs]) -> 'a + val reduce: t -> 'a -> ('a -> value -> 'a ) -> 'a -(** Iterate in increasing order. *) +(** + 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. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([5, 2, 3, 5, 6]) + s0->Belt.MutableSet.Int.reduce(list{}, (acc, element) => + acc->Belt.List.add(element) + ) /* [6,5,3,2] */ + ``` +*) val everyU: t -> (value -> bool [@bs]) -> bool + val every: t -> (value -> bool) -> bool -(** `every p s` checks if all elements of the set - satisfy the predicate `p`. Order unspecified. *) +(** + Checks if all elements of the set satisfy the predicate. Order unspecified. + + ```res example + let isEven = x => mod(x, 2) == 0 + + let s0 = Belt.MutableSet.Int.fromArray([2, 4, 6, 8]) + s0->Belt.MutableSet.Int.every(isEven) /* true */ + ``` +*) val someU: t -> (value -> bool [@bs]) -> bool + val some: t -> (value -> bool) -> bool -(** `some p s` checks if at least one element of - the set satisfies the predicate `p`. Oder unspecified. *) +(** + Checks if at least one element of the set satisfies the predicate. + + ```res example + let isOdd = x => mod(x, 2) != 0 + + let s0 = Belt.MutableSet.Int.fromArray([1, 2, 4, 6, 8]) + s0->Belt.MutableSet.Int.some(isOdd) /* true */ + ``` +*) val keepU: t -> (value -> bool [@bs]) -> t + val keep: t -> (value -> bool) -> t -(** `keep s p` returns a fresh copy of the set of all elements in `s` - that satisfy predicate `p`. *) +(** + Returns the set of all elements that satisfy the predicate. + + ```res example + let isEven = x => mod(x, 2) == 0 + + let s0 = Belt.MutableSet.Int.fromArray([1, 2, 3, 4, 5]) + let s1 = s0->Belt.MutableSet.Int.keep(isEven) + + s1->Belt.MutableSet.Int.toArray /* [2, 4] */ + ``` +*) val partitionU: t -> (value -> bool [@bs]) -> t * t + val partition: t -> (value -> bool) -> t * t -(** `partition s p` returns a fresh copy pair of sets `(s1, s2)`, where - `s1` is the set of all the elements of `s` that satisfy the - predicate `p`, and `s2` is the set of all the elements of - `s` that do not satisfy `p`. *) +(** + ```res example + let isOdd = x => mod(x, 2) != 0 + + let s0 = Belt.MutableSet.Int.fromArray([1, 2, 3, 4, 5]) + let (s1, s2) = s0->Belt.MutableSet.Int.partition(isOdd) + + s1->Belt.MutableSet.Int.toArray /* [1,3,5] */ + s2->Belt.MutableSet.Int.toArray /* [2,4] */ + ``` +*) val size: t -> int +(** + Returns size of the set. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([1, 2, 3, 4]) + + s0->Belt.MutableSet.Int.size /* 4 */ + ``` +*) + val toList: t -> value list -(** In increasing order with respect *) +(** + Returns list of ordered set elements. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([3, 2, 1, 5]) + + s0->Belt.MutableSet.Int.toList /* [1,2,3,5] */ + ``` +*) val toArray: t -> value array -(** In increasing order with respect *) +(** + Returns array of ordered set elements. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([3, 2, 1, 5]) + + s0->Belt.MutableSet.Int.toArray /* [1,2,3,5] */ + ``` +*) val minimum: t -> value option +(** + Returns minimum value of the collection. `None` if collection is empty. + + ```res example + let s0 = Belt.MutableSet.Int.make() + let s1 = Belt.MutableSet.Int.fromArray([3, 2, 1, 5]) + + s0->Belt.MutableSet.Int.minimum /* None */ + s1->Belt.MutableSet.Int.minimum /* Some(1) */ + ``` +*) + val minUndefined: t -> value Js.undefined +(** + Returns minimum value of the collection. `undefined` if collection is empty. + + ```res example + let s0 = Belt.MutableSet.Int.make() + let s1 = Belt.MutableSet.Int.fromArray([3, 2, 1, 5]) + + s0->Belt.MutableSet.Int.minUndefined /* undefined */ + s1->Belt.MutableSet.Int.minUndefined /* 1 */ + ``` +*) + val maximum: t -> value option +(** + Returns maximum value of the collection. `None` if collection is empty. + + ```res example + let s0 = Belt.MutableSet.Int.make() + let s1 = Belt.MutableSet.Int.fromArray([3, 2, 1, 5]) + + s0->Belt.MutableSet.Int.maximum /* None */ + s1->Belt.MutableSet.Int.maximum /* Some(5) */ + ``` +*) + val maxUndefined: t -> value Js.undefined +(** + Returns maximum value of the collection. `undefined` if collection is empty. + + ```res example + let s0 = Belt.MutableSet.Int.make() + let s1 = Belt.MutableSet.Int.fromArray([3, 2, 1, 5]) + + s0->Belt.MutableSet.Int.maxUndefined /* undefined */ + s1->Belt.MutableSet.Int.maxUndefined /* 5 */ + ``` +*) val get: t -> value -> value option +(** + 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. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([1, 2, 3, 4, 5]) + + s0->Belt.MutableSet.Int.get(3) /* Some(3) */ + s0->Belt.MutableSet.Int.get(20) /* None */ + ``` +*) + val getUndefined: t -> value -> value Js.undefined +(** + Same as [get](#get) but returns `undefined` when element does not exist. +*) + val getExn: t -> value -> value +(** + Same as [get](#get) but raise when element does not exist. +*) + val split: t -> value -> (t * t) * bool (** - `split s key` return a fresh copy of each + Returns a tuple `((smaller, larger), present)`, `present` is true when element exist in set. + + ```res example + let s0 = Belt.MutableSet.Int.fromArray([1, 2, 3, 4, 5]) + + let ((smaller, larger), present) = s0->Belt.MutableSet.Int.split(3) + + present /* true */ + smaller->Belt.MutableSet.Int.toArray /* [1,2] */ + larger->Belt.MutableSet.Int.toArray /* [4,5] */ + ``` *) val checkInvariantInternal: t -> unit diff --git a/jscomp/others/belt_MutableSetString.mli b/jscomp/others/belt_MutableSetString.mli index 937064d27e..9235e9b011 100644 --- a/jscomp/others/belt_MutableSetString.mli +++ b/jscomp/others/belt_MutableSetString.mli @@ -29,93 +29,425 @@ It is more efficient in general, the API is the same with [`Belt.MutableSet`]() except its key type is fixed, and identity is not needed(using the built-in one) + This module is [Belt.MutableSet](mutable-set) specialized with key type to be a `string` type. + It is more efficient in general, the API is the same with [Belt.MutableSet](mutable-set) except its key type is fixed, and identity is not needed (using the built-in one) + **See** [`Belt.MutableSet`]() *) # 36 "others/setm.cppo.mli" type value = string - +(** + The type of the set elements. +*) + # 42 "others/setm.cppo.mli" (** The type of the set elements. *) type t -(** The type of sets. *) +(** + The type of sets. +*) val make: unit -> t +(** + Returns empty set. + + ```res example + let set = Belt.MutableSet.String.make() + ``` +*) val fromArray: value array -> t +(** + Creates new set from array of elements. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["apple", "orange", "banana"]) + + s0->Belt.MutableSet.String.toArray /* ["apple", "banana", "orange"] */ + ``` +*) + val fromSortedArrayUnsafe: value array -> t +(** + The same as [fromArray][#fromarray] except it is after assuming the input array is already sorted. +*) val copy: t -> t +(** + Returns copy of a set. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["orange", "apple"]) + + let copied = s0->Belt.MutableSet.String.copy + copied->Belt.MutableSet.String.toArray /* ["apple", "orange"] */ + ``` +*) + val isEmpty: t -> bool +(** + Checks if set is empty. + + ```res example + let empty = Belt.MutableSet.String.fromArray([]) + let notEmpty = Belt.MutableSet.String.fromArray(["apple"]) + + Belt.MutableSet.String.isEmpty(empty) /* true */ + Belt.MutableSet.String.isEmpty(notEmpty) /* false */ + ``` +*) + val has: t -> value -> bool +(** + Checks if element exists in set. + + ```res example + let set = Belt.MutableSet.String.fromArray(["apple", "orange", "banana"]) + + set->Belt.MutableSet.String.has("strawberry") /* false */ + set->Belt.MutableSet.String.has("apple") /* true */ + ``` +*) val add: t -> value -> unit +(** + Adds element to set. If element existed in set, value is unchanged. + + ```res example + let s0 = Belt.MutableSet.String.make() + s0->Belt.MutableSet.String.add("apple") + s0->Belt.MutableSet.String.add("banana") + s0->Belt.MutableSet.String.add("banana") + + s0->Belt.MutableSet.String.toArray /* ["apple", "banana"] */ + ``` +*) + val addCheck: t -> value -> bool + val mergeMany: t -> value array -> unit +(** + Adds each element of array to set. + + ```res example + let set = Belt.MutableSet.String.make() + + set->Belt.MutableSet.String.mergeMany(["apple", "banana", "orange", "strawberry"]) + set->Belt.MutableSet.String.toArray /* ["apple", "banana", "orange", "strawberry"] */ + ``` +*) + val remove: t -> value -> unit +(** + Removes element from set. If element wasn't existed in set, value is unchanged. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["orange", "banana", "apple"]) + s0->Belt.MutableSet.String.remove("apple") + s0->Belt.MutableSet.String.remove("banana") + s0->Belt.MutableSet.String.remove("banana") + + s0->Belt.MutableSet.String.toArray /* ["orange"] */ + ``` +*) + val removeCheck: t -> value -> bool + val removeMany: t -> value array -> unit +(** + Removes each element of array from set. + + ```res example + let set = Belt.MutableSet.String.fromArray(["apple", "banana", "orange"]) + + set->Belt.MutableSet.String.removeMany(["strawberry", "apple", "banana", "orange"]) + set->Belt.MutableSet.String.toArray /* [] */ + ``` +*) val union: t -> t -> t +(** + Returns union of two sets. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["apple", "banana", "orange", "carrot"]) + let s1 = Belt.MutableSet.String.fromArray(["apple", "banana", "orange", "strawberry"]) + let union = Belt.MutableSet.String.union(s0, s1) + union->Belt.MutableSet.String.toArray /* ["apple", "banana", "carrot", "orange", "strawberry"] */ + ``` +*) + val intersect: t -> t -> t +(** + Returns intersection of two sets. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["apple", "banana", "orange", "carrot"]) + let s1 = Belt.MutableSet.String.fromArray(["apple", "banana", "orange", "strawberry"]) + let intersect = Belt.MutableSet.String.intersect(s0, s1) + intersect->Belt.MutableSet.String.toArray /* ["apple", "banana", "orange"] */ + ``` +*) + val diff: t -> t -> t +(** + Returns elements from first set, not existing in second set. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["apple", "banana", "orange", "carrot"]) + let s1 = Belt.MutableSet.String.fromArray(["apple", "banana", "orange", "strawberry"]) + Belt.MutableSet.String.toArray(Belt.MutableSet.String.diff(s0, s1)) /* ["carrot"] */ + Belt.MutableSet.String.toArray(Belt.MutableSet.String.diff(s1, s0)) /* ["strawberry"] */ + ``` +*) + val subset: t -> t -> bool +(** + Checks if second set is subset of first set. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["5", "2", "3", "5", "6"]) + let s1 = Belt.MutableSet.String.fromArray(["5", "2", "3", "1", "5", "4"]) + let s2 = Belt.MutableSet.String.intersect(s0, s1) + Belt.MutableSet.String.subset(s2, s0) /* true */ + Belt.MutableSet.String.subset(s2, s1) /* true */ + Belt.MutableSet.String.subset(s1, s0) /* false */ + ``` +*) val cmp: t -> t -> 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. +*) + val eq: t -> t -> bool +(** + Checks if two sets are equal. + ```res example + let s0 = Belt.MutableSet.String.fromArray(["apple", "orange"]) + let s1 = Belt.MutableSet.String.fromArray(["orange", "apple"]) + + Belt.MutableSet.String.eq(s0, s1) /* true */ + ``` +*) val forEachU: t -> (value -> unit [@bs]) -> unit +(** + Same as [forEach](##forEach) but takes uncurried functon. +*) + val forEach: t -> (value -> unit ) -> unit -(** In increasing order*) +(** + Applies function `f` in turn to all elements of set in increasing order. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["banana", "orange", "apple"]) + let acc = ref(list{}) + s0->Belt.MutableSet.String.forEach(x => acc := Belt.List.add(acc.contents, x)) + acc /* ["orange", "banana", "apple"] */ + ``` +*) val reduceU: t -> 'a -> ('a -> value -> 'a [@bs]) -> 'a + val reduce: t -> 'a -> ('a -> value -> 'a ) -> 'a -(** Iterate in increasing order. *) +(** + 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. + + 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. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["apple", "orange"]) + s0->Belt.MutableSet.String.reduce(0, (acc, element) => acc + String.length(element)) /* 11 */ + ``` +*) val everyU: t -> (value -> bool [@bs]) -> bool + val every: t -> (value -> bool) -> bool -(** `every p s` checks if all elements of the set - satisfy the predicate `p`. Order unspecified. *) +(** + Checks if all elements of the set satisfy the predicate. Order unspecified. + + ```res example + let hasAtLeastFiveChars = x => String.length(x) >= 5 + + let s0 = Belt.MutableSet.String.fromArray(["apple", "carrot"]) + s0->Belt.MutableSet.String.every(hasAtLeastFiveChars) /* true */ + ``` +*) val someU: t -> (value -> bool [@bs]) -> bool + val some: t -> (value -> bool) -> bool -(** `some p s` checks if at least one element of - the set satisfies the predicate `p`. Oder unspecified. *) +(** + Checks if at least one element of the set satisfies the predicate. + + ```res example + let hasFiveChars = x => String.length(x) == 5 + + let s0 = Belt.MutableSet.String.fromArray(["strawberry", "apple"]) + s0->Belt.MutableSet.String.some(hasFiveChars) /* true */ + ``` +*) val keepU: t -> (value -> bool [@bs]) -> t + val keep: t -> (value -> bool) -> t -(** `keep s p` returns a fresh copy of the set of all elements in `s` - that satisfy predicate `p`. *) +(** + Returns the set of all elements that satisfy the predicate. + + ```res example + let hasFiveChars = x => String.length(x) == 5 + + let s0 = Belt.MutableSet.String.fromArray(["apple", "orange", "banana"]) + let s1 = s0->Belt.MutableSet.String.keep(hasFiveChars) + + s1->Belt.MutableSet.String.toArray /* ["apple"] */ + ``` +*) val partitionU: t -> (value -> bool [@bs]) -> t * t + val partition: t -> (value -> bool) -> t * t -(** `partition s p` returns a fresh copy pair of sets `(s1, s2)`, where - `s1` is the set of all the elements of `s` that satisfy the - predicate `p`, and `s2` is the set of all the elements of - `s` that do not satisfy `p`. *) +(** + 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. + + ```res example + let hasFiveChars = x => String.length(x) == 5 + + let s0 = Belt.MutableSet.String.fromArray(["apple", "carrot"]) + let (s1, s2) = s0->Belt.MutableSet.String.partition(hasFiveChars) + + s1->Belt.MutableSet.String.toArray /* ["apple"] */ + s2->Belt.MutableSet.String.toArray /* ["carrot"] */ + ``` +*) val size: t -> int +(** + Returns size of the set. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["apple"]) + + s0->Belt.MutableSet.String.size /* 1 */ + ``` +*) + val toList: t -> value list -(** In increasing order with respect *) +(** + Returns list of ordered set elements. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["apple", "watermelon"]) + + s0->Belt.MutableSet.String.toList /* ["apple", "watermelon"] */ + ``` +*) val toArray: t -> value array -(** In increasing order with respect *) +(** + Returns array of ordered set elements. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["apple", "watermelon"]) + + s0->Belt.MutableSet.String.toArray /* ["apple", "watermelon"] */ + ``` +*) val minimum: t -> value option +(** + Returns minimum value of the collection. `None` if collection is empty. + + ```res example + let s0 = Belt.MutableSet.String.make() + let s1 = Belt.MutableSet.String.fromArray(["apple", "orange"]) + + s0->Belt.MutableSet.String.minimum /* None */ + s1->Belt.MutableSet.String.minimum /* Some("apple") */ + ``` +*) + val minUndefined: t -> value Js.undefined +(** + Returns minimum value of the collection. `undefined` if collection is empty. + + ```res example + let s0 = Belt.MutableSet.String.make() + let s1 = Belt.MutableSet.String.fromArray(["apple", "orange"]) + + s0->Belt.MutableSet.String.minUndefined /* undefined */ + s1->Belt.MutableSet.String.minUndefined /* "apple" */ + ``` +*) + val maximum: t -> value option +(** + Returns maximum value of the collection. `None` if collection is empty. + + ```res example + let s0 = Belt.MutableSet.String.make() + let s1 = Belt.MutableSet.String.fromArray(["apple", "orange"]) + + s0->Belt.MutableSet.String.maximum /* None */ + s1->Belt.MutableSet.String.maximum /* Some("orange") */ + ``` +*) + val maxUndefined: t -> value Js.undefined +(** + Returns maximum value of the collection. `undefined` if collection is empty. + + ```res example + let s0 = Belt.MutableSet.String.make() + let s1 = Belt.MutableSet.String.fromArray(["apple", "orange"]) + + s0->Belt.MutableSet.String.maxUndefined /* undefined */ + s1->Belt.MutableSet.String.maxUndefined /* orange */ + ``` +*) val get: t -> value -> value option +(** + 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. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["apple", "carrot"]) + + s0->Belt.MutableSet.String.get("carrot") /* Some("carrot") */ + s0->Belt.MutableSet.String.get("watermelon") /* None */ + ``` +*) + val getUndefined: t -> value -> value Js.undefined +(** + Same as [get](#get) but returns `undefined` when element does not exist. +*) + val getExn: t -> value -> value +(** + Same as [get](#get) but raise when element does not exist. +*) + val split: t -> value -> (t * t) * bool (** - `split s key` return a fresh copy of each + Returns a tuple `((smaller, larger), present)`, `present` is true when element exist in set. + + ```res example + let s0 = Belt.MutableSet.String.fromArray(["apple", "banana", "orange"]) + + let ((smaller, larger), present) = s0->Belt.MutableSet.String.split("banana") + + present /* true */ + smaller->Belt.MutableSet.String.toArray /* ["apple"] */ + larger->Belt.MutableSet.String.toArray /* ["orange"] */ + ``` *) val checkInvariantInternal: t -> unit diff --git a/jscomp/others/belt_Set.mli b/jscomp/others/belt_Set.mli index ce18f3a52f..88a81b2faf 100644 --- a/jscomp/others/belt_Set.mli +++ b/jscomp/others/belt_Set.mli @@ -22,7 +22,7 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *) -(** A _immutable_ sorted set module which allows customize _compare_ behavior. +(** An _immutable_ sorted set module which allows customized _compare_ behavior. The implementation uses balanced binary trees, and therefore searching and insertion take time logarithmic in the size of the map. @@ -32,20 +32,31 @@ Example usage: + ```res example + 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)) ``` - module PairComparator = Belt.Id.MakeComparable(struct - type t = int * int - let cmp (a0, a1) (b0, b1) = - match Pervasives.compare a0 b0 with - | 0 -> Pervasives.compare a1 b1 - | c -> c - end) - - let mySet = Belt.Set.make ~id:(module PairComparator) - let mySet2 = Belt.Set.add mySet (1, 2) - ``` - The API documentation below will assume a predeclared comparator module for integers, IntCmp + **Note:** This module's examples will assume a predeclared module for integers + called `IntCmp`. It is declared like this: + + ```res example + module IntCmp = + Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + ``` *) (** Specalized when value type is `int`, more efficient @@ -59,7 +70,7 @@ module Int = Belt_SetInt module String = Belt_SetString -(** This module seprate identity from data, it is a bit more verboe but slightly +(** This module seprate identity from data, it is a bit more verbose but slightly more efficient due to the fact that there is no need to pack identity and data back after each operation *) @@ -67,8 +78,7 @@ module Dict = Belt_SetDict type ('value, 'identity) t -(** `('value, 'identity) t` - +(** `'value` is the element type `'identity` the identity of the collection @@ -76,279 +86,406 @@ type ('value, 'identity) t type ('value, 'id) id = ('value, 'id) Belt_Id.comparable -(** The identity needed for making a set from scratch +(** + The identity needed for making a set from scratch *) val make: id:('value, 'id) id -> ('value, 'id) t -(** `make ~id` creates a new set by taking in the comparator - ``` - let s = make ~id:(module IntCmp) - ``` +(** + Creates a new set by taking in the comparator + ```res example + let set = Belt.Set.make(~id=module(IntCmp)) + ``` *) val fromArray: 'value array -> id:('value, 'id) id -> ('value, 'id) t -(** `fromArray xs ~id` +(** + Creates new set from array of elements. - ``` - toArray (fromArray [1;3;2;4] (module IntCmp)) = [1;2;3;4] + ```res example + let s0 = Belt.Set.fromArray([1, 3, 2, 4], ~id=module(IntCmp)) + + s0->Belt.Set.toArray /* [1, 2, 3, 4] */ ``` *) val fromSortedArrayUnsafe: 'value array -> id:('value, 'id) id -> ('value,'id) t -(** `fromSortedArrayUnsafe xs ~id` - - The same as [`fromArray`]() except it is after assuming the input array `x` is already sorted - - **Unsafe** +(** + The same as [fromArray][#fromarray] except it is after assuming the input array is already sorted. *) val isEmpty: _ t -> bool (** - ``` - isEmpty (fromArray [||] ~id:(module IntCmp)) = true;; - isEmpty (fromArray [|1|] ~id:(module IntCmp)) = true;; + Checks if set is empty. + + ```res example + 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 */ ``` *) val has: ('value, 'id) t -> 'value -> bool (** - ``` - let v = fromArray [|1;4;2;5|] ~id:(module IntCmp);; - has v 3 = false;; - has v 1 = true;; + Checks if element exists in set. + + ```res example + let set = Belt.Set.fromArray([1, 4, 2, 5], ~id=module(IntCmp)) + + set->Belt.Set.has(3) /* false */ + set->Belt.Set.has(1) /* true */ ``` *) val add: ('value, 'id) t -> 'value -> ('value, 'id) t -(** `add s x` If `x` was already in `s`, `s` is returned unchanged. - - ``` - let s0 = make ~id:(module IntCmp);; - let s1 = add s0 1 ;; - let s2 = add s1 2;; - let s3 = add s2 2;; - toArray s0 = [||];; - toArray s1 = [|1|];; - toArray s2 = [|1;2|];; - toArray s3 = [|1;2|];; - s2 == s3;; +(** + Adds element to set. If element existed in set, value is unchanged. + + ```res example + 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 */ ``` *) val mergeMany: ('value, 'id) t -> 'value array -> ('value, 'id) t -(** `mergeMany s xs` +(** + Adds each element of array to set. Unlike [add](#add), the reference of return value might be changed even if all values in array already exist in set - Adding each of `xs` to `s`, note unlike [`add`](), - the reference of return value might be changed even if all values in `xs` - exist `s` + ```res example + 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] */ + ``` *) val remove: ('value, 'id) t -> 'value -> ('value, 'id) t -(** `remove m x` If `x` was not in `m`, `m` is returned reference unchanged. +(** + Removes element from set. If element wasn't existed in set, value is unchanged. - ``` - let s0 = fromArray ~id:(module IntCmp) [|2;3;1;4;5|];; - let s1 = remove s0 1 ;; - let s2 = remove s1 3 ;; - let s3 = remove s2 3 ;; - - toArray s1 = [|2;3;4;5|];; - toArray s2 = [|2;4;5|];; - s2 == s3;; + ```res example + 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 */ ``` *) val removeMany: ('value, 'id) t -> 'value array -> ('value, 'id) t -(** `removeMany s xs` +(** + Removes each element of array from set. Unlike [remove](#remove), the reference of return value might be changed even if any values in array not existed in set. - Removing each of `xs` to `s`, note unlike [`remove`](), - the reference of return value might be changed even if none in `xs` - exists `s` + ```res example + 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 /* [] */ + ``` *) val union: ('value, 'id) t -> ('value, 'id) t -> ('value, 'id) t (** - `union s0 s1` + Returns union of two sets. - ``` - let s0 = fromArray ~id:(module IntCmp) [|5;2;3;5;6|]];; - let s1 = fromArray ~id:(module IntCmp) [|5;2;3;1;5;4;|];; - toArray (union s0 s1) = [|1;2;3;4;5;6|] + ```res example + 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] */ ``` *) val intersect: ('value, 'id) t -> ('value, 'id) t -> ('value, 'id) t -(** `intersect s0 s1` - ``` - let s0 = fromArray ~id:(module IntCmp) [|5;2;3;5;6|]];; - let s1 = fromArray ~id:(module IntCmp) [|5;2;3;1;5;4;|];; - toArray (intersect s0 s1) = [|2;3;5|] - ``` +(** + Returns intersection of two sets. + ```res example + 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] */ + ``` *) val diff: ('value, 'id) t -> ('value, 'id) t -> ('value, 'id) t -(** `diff s0 s1` - ``` - let s0 = fromArray ~id:(module IntCmp) [|5;2;3;5;6|]];; - let s1 = fromArray ~id:(module IntCmp) [|5;2;3;1;5;4;|];; - toArray (diff s0 s1) = [|6|];; - toArray (diff s1 s0) = [|1;4|];; +(** + Returns elements from first set, not existing in second set. + + ```res example + 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] */ ``` *) val subset: ('value, 'id) t -> ('value, 'id) t -> bool -(** `subset s0 s1` - - ``` - let s0 = fromArray ~id:(module IntCmp) [|5;2;3;5;6|]];; - let s1 = fromArray ~id:(module IntCmp) [|5;2;3;1;5;4;|];; - let s2 = intersect s0 s1;; - subset s2 s0 = true;; - subset s2 s1 = true;; - subset s1 s0 = false;; +(** + Checks if second set is subset of first set. + + ```res example + 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 */ ``` *) val cmp: ('value, 'id) t -> ('value, 'id) t -> int -(** Total ordering between sets. Can be used as the ordering function - for doing sets of sets. - It compare `size` first and then iterate over - each element following the order of elements +(** + 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. *) val eq: ('value, 'id) t -> ('value, 'id) t -> bool -(** `eq s0 s1` +(** + Checks if two sets are equal. - **return** true if `toArray s0 = toArray s1` + ```res example + 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 */ + ``` *) val forEachU: ('value, 'id) t -> ('value -> unit [@bs]) -> unit -val forEach: ('value, 'id) t -> ('value -> unit ) -> unit -(** `forEach s f` applies `f` in turn to all elements of `s`. - In increasing order +(** + Same as [forEach](##forEach) but takes uncurried functon. +*) - ``` - let s0 = fromArray ~id:(module IntCmp) [|5;2;3;5;6|]];; - let acc = ref [] ;; - forEach s0 (fun x -> acc := x !acc);; - !acc = [6;5;3;2];; +val forEach: ('value, 'id) t -> ('value -> unit ) -> unit +(** + Applies function `f` in turn to all elements of set in increasing order. + + ```res example + let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) + let acc = ref(list{}) + s0->Belt.Set.forEach(x => { + acc := Belt.List.add(acc.contents, x) + }) + acc /* [6,5,3,2] */ ``` *) val reduceU: ('value, 'id) t -> 'a -> ('a -> 'value -> 'a [@bs]) -> 'a + val reduce: ('value, 'id) t -> 'a -> ('a -> 'value -> 'a ) -> 'a -(** In increasing order. +(** + 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. - ``` - let s0 = fromArray ~id:(module IntCmp) [|5;2;3;5;6|]];; - reduce s0 [] Bs.List.add = [6;5;3;2];; + ```res example + let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) + s0->Belt.Set.reduce(list{}, (acc, element) => + acc->Belt.List.add(element) + ) /* [6,5,3,2] */ ``` *) val everyU: ('value, 'id) t -> ('value -> bool [@bs]) -> bool + val every: ('value, 'id) t -> ('value -> bool ) -> bool -(** `every p s` checks if all elements of the set - satisfy the predicate `p`. Order unspecified. +(** + Checks if all elements of the set satisfy the predicate. Order unspecified. + + ```res example + let isEven = x => mod(x, 2) == 0 + + let s0 = Belt.Set.fromArray([2,4,6,8], ~id=module(IntCmp)) + s0->Belt.Set.every(isEven) /* true */ + ``` *) val someU: ('value, 'id) t -> ('value -> bool [@bs]) -> bool + val some: ('value, 'id) t -> ('value -> bool ) -> bool -(** `some p s` checks if at least one element of - the set satisfies the predicate `p`. *) +(** + Checks if at least one element of the set satisfies the predicate. + + ```res example + let isOdd = x => mod(x, 2) != 0 + + let s0 = Belt.Set.fromArray([1,2,4,6,8], ~id=module(IntCmp)) + s0->Belt.Set.some(isOdd) /* true */ + ``` +*) val keepU: ('value, 'id) t -> ('value -> bool [@bs]) -> ('value, 'id) t + val keep: ('value, 'id) t -> ('value -> bool ) -> ('value, 'id) t -(** `keep m p` returns the set of all elements in `s` - that satisfy predicate `p`. *) +(** + Returns the set of all elements that satisfy the predicate. + + ```res example + let isEven = x => mod(x, 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] */ + ``` +*) val partitionU: ('value, 'id) t -> ('value -> bool [@bs]) -> ('value, 'id) t * ('value, 'id) t + val partition: ('value, 'id) t -> ('value -> bool) -> ('value, 'id) t * ('value, 'id) t -(** `partition m p` returns a pair of sets `(s1, s2)`, where - `s1` is the set of all the elements of `s` that satisfy the - predicate `p`, and `s2` is the set of all the elements of - `s` that do not satisfy `p`. *) +(** + 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. -val size: ('value, 'id) t -> int -(** `size s` + ```res example + let isOdd = x => mod(x, 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] */ ``` - let s0 = fromArray ~id:(module IntCmp) [|5;2;3;5;6|]];; - size s0 = 4;; +*) + +val size: ('value, 'id) t -> int +(** + Returns size of the set. + + ```res example + let s0 = Belt.Set.fromArray([1,2,3,4], ~id=module(IntCmp)) + + s0->Belt.Set.size /* 4 */ ``` *) val toArray: ('value, 'id) t -> 'value array -(** `toArray s0` +(** + Returns array of ordered set elements. - ``` - let s0 = fromArray ~id:(module IntCmp) [|5;2;3;5;6|]];; - toArray s0 = [|2;3;5;6|];; + ```res example + let s0 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) + + s0->Belt.Set.toArray /* [1,2,3,5] */ ``` *) val toList: ('value, 'id) t -> 'value list -(** In increasing order +(** + Returns list of ordered set elements. + + ```res example + let s0 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) - **See** [`toArray`]() + s0->Belt.Set.toList /* [1,2,3,5] */ + ``` *) val minimum: ('value, 'id) t -> 'value option -(** `minimum s0` +(** + Returns minimum value of the collection. `None` if collection is empty. + + ```res example + let s0 = Belt.Set.make(~id=module(IntCmp)) + let s1 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) - **return** the minimum element of the collection, `None` if it is empty + s0->Belt.Set.minimum /* None */ + s1->Belt.Set.minimum /* Some(1) */ + ``` *) val minUndefined: ('value, 'id) t -> 'value Js.undefined -(** `minUndefined s0` +(** + Returns minimum value of the collection. `undefined` if collection is empty. - **return** the minimum element of the collection, `undefined` if it is empty + ```res example + 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 */ + ``` *) val maximum: ('value, 'id) t -> 'value option -(** `maximum s0` +(** + Returns maximum value of the collection. `None` if collection is empty. + + ```res example + let s0 = Belt.Set.make(~id=module(IntCmp)) + let s1 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) - **return** the maximum element of the collection, `None` if it is empty + s0->Belt.Set.maximum /* None */ + s1->Belt.Set.maximum /* Some(5) */ + ``` *) val maxUndefined: ('value, 'id) t -> 'value Js.undefined -(** `maxUndefined s0` +(** + Returns maximum value of the collection. `undefined` if collection is empty. - **return** the maximum element of the collection, `undefined` if it is empty + ```res example + 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 */ + ``` *) val get: ('value, 'id) t -> 'value -> 'value option -(** `get s0 k` +(** + 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. + + ```res example + let s0 = Belt.Set.fromArray([1,2,3,4,5], ~id=module(IntCmp)) - **return** the reference of the value `k'` which is equivalent to `k` - using the comparator specifiecd by this collection, `None` - if it does not exist + s0->Belt.Set.get(3) /* Some(3) */ + s0->Belt.Set.get(20) /* None */ + ``` *) val getUndefined: ('value, 'id) t -> 'value -> 'value Js.undefined -(** **See** [`get`]() +(** + Same as [get](#get) but returns `undefined` when element does not exist. *) val getExn: ('value, 'id) t -> 'value -> 'value -(** **See** [`get`]() - - **raise** if not exist +(** + Same as [get](#get) but raise when element does not exist. *) val split: ('value, 'id) t -> 'value -> (('value, 'id) t * ('value, 'id) t) * bool -(** `split set ele` +(** + Returns a tuple `((smaller, larger), present)`, `present` is true when element exist in set. - **return** a tuple `((smaller, larger), present)`, - `present` is true when `ele` exist in `set` + ```res example + 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] */ + + ``` *) (**/**) @@ -365,28 +502,22 @@ val checkInvariantInternal: _ t -> unit *) val getData: ('value, 'id) t -> ('value, 'id) Belt_SetDict.t -(** `getData s0` - +(** **Advanced usage only** - **return** the raw data (detached from comparator), - but its type is still manifested, so that user can pass identity directly - without boxing + Returns the raw data (detached from comparator), but its type is still manifested, so that user can pass identity directly without boxing. *) val getId: ('value, 'id) t -> ('value, 'id) id -(** `getId s0` - +(** **Advanced usage only** - **return** the identity of `s0` + Returns the identity of set. *) val packIdData: id:('value, 'id) id -> data:('value, 'id) Belt_SetDict.t -> ('value, 'id) t -(** `packIdData ~id ~data` - +(** **Advanced usage only** - **return** the packed collection + Returns the packed collection. *) - diff --git a/jscomp/others/belt_SetDict.mli b/jscomp/others/belt_SetDict.mli index 1e7845fb52..6ad316ac32 100644 --- a/jscomp/others/belt_SetDict.mli +++ b/jscomp/others/belt_SetDict.mli @@ -22,111 +22,543 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *) +(** + This module separates identity from data. It is a bit more verbose but slightly more efficient due to the fact that there is no need to pack identity and data back after each operation. +*) + type ('value, 'identity) t +(** + `'value` is the element type + + `'identity` the identity of the collection +*) type ('value, 'id) cmp = ('value, 'id) Belt_Id.cmp +(** + Type of compare function. +*) val empty: ('value, 'id) t - +(** + ```res example + let s0 = Belt.Set.Dict.empty + ``` +*) val fromArray: 'value array -> cmp:('value, 'id) cmp -> ('value, 'id) t +(** + Creates new set from array of elements. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([1, 3, 2, 4], ~cmp=IntCmp.cmp) + + s0->Belt.Set.Dict.toArray /* [1, 2, 3, 4] */ + ``` +*) val fromSortedArrayUnsafe: 'value array -> ('value,'id) t +(** + The same as [fromArray][#fromarray] except it is after assuming the input array is already sorted. +*) val isEmpty: _ t -> bool +(** + Checks if set is empty. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let empty = Belt.Set.Dict.fromArray([], ~cmp=IntCmp.cmp) + let notEmpty = Belt.Set.Dict.fromArray([1], ~cmp=IntCmp.cmp) + + Belt.Set.Dict.isEmpty(empty) /* true */ + Belt.Set.Dict.isEmpty(notEmpty) /* false */ + ``` +*) val has: ('value, 'id) t -> 'value -> cmp:('value, 'id) cmp -> bool +(** + Checks if an element exists in the set. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let set = Belt.Set.Dict.fromArray([1, 4, 2, 5], ~cmp=IntCmp.cmp) + + set->Belt.Set.Dict.has(3, ~cmp=IntCmp.cmp) /* false */ + set->Belt.Set.Dict.has(1, ~cmp=IntCmp.cmp) /* true */ + ``` +*) val add: ('value, 'id) t -> 'value -> cmp:('value, 'id) cmp -> ('value, 'id) t -(** `add s x` If `x` was already in `s`, `s` is returned unchanged. *) +(** + Adds element to set. If element existed in set, value is unchanged. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.empty + let s1 = s0->Belt.Set.Dict.add(1, ~cmp=IntCmp.cmp) + let s2 = s1->Belt.Set.Dict.add(2, ~cmp=IntCmp.cmp) + let s3 = s2->Belt.Set.Dict.add(2, ~cmp=IntCmp.cmp) + s0->Belt.Set.Dict.toArray /* [] */ + s1->Belt.Set.Dict.toArray /* [1] */ + s2->Belt.Set.Dict.toArray /* [1, 2] */ + s3->Belt.Set.Dict.toArray /* [1,2 ] */ + s2 == s3 /* true */ + ``` +*) val mergeMany: ('value, 'id) t -> 'value array -> cmp:('value, 'id) cmp -> ('value, 'id) t +(** + Adds each element of array to set. Unlike [add](#add), the reference of return value might be changed even if all values in array already exist in set + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let set = Belt.Set.Dict.empty + + let newSet = set->Belt.Set.Dict.mergeMany([5, 4, 3, 2, 1], ~cmp=IntCmp.cmp) + newSet->Belt.Set.Dict.toArray /* [1, 2, 3, 4, 5] */ + ``` +*) val remove: ('value, 'id) t -> 'value -> cmp:('value, 'id) cmp -> ('value, 'id) t -(** `remove m x` If `x` was not in `m`, `m` is returned reference unchanged. *) +(** + Removes element from set. If element wasn't existed in set, value is unchanged. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([2, 3, 1, 4, 5], ~cmp=IntCmp.cmp) + let s1 = s0->Belt.Set.Dict.remove(1, ~cmp=IntCmp.cmp) + let s2 = s1->Belt.Set.Dict.remove(3, ~cmp=IntCmp.cmp) + let s3 = s2->Belt.Set.Dict.remove(3, ~cmp=IntCmp.cmp) + + s1->Belt.Set.Dict.toArray /* [2,3,4,5] */ + s2->Belt.Set.Dict.toArray /* [2,4,5] */ + s2 == s3 /* true */ + ``` +*) val removeMany: ('value, 'id) t -> 'value array -> cmp:('value, 'id) cmp -> ('value, 'id) t +(** + Removes each element of array from set. Unlike [remove](#remove), the reference of return value might be changed even if any values in array not existed in set. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let set = Belt.Set.Dict.fromArray([1, 2, 3, 4], ~cmp=IntCmp.cmp) + + let newSet = set->Belt.Set.Dict.removeMany([5, 4, 3, 2, 1], ~cmp=IntCmp.cmp) + newSet->Belt.Set.Dict.toArray /* [] */ + ``` +*) val union: ('value, 'id) t -> ('value, 'id) t -> cmp:('value, 'id) cmp -> ('value, 'id) t +(** + Returns union of two sets. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) + let s1 = Belt.Set.Dict.fromArray([5, 2, 3, 1, 5, 4], ~cmp=IntCmp.cmp) + let union = Belt.Set.Dict.union(s0, s1, ~cmp=IntCmp.cmp) + union->Belt.Set.Dict.toArray /* [1,2,3,4,5,6] */ + ``` +*) val intersect: ('value, 'id) t -> ('value, 'id) t -> cmp:('value, 'id) cmp -> ('value, 'id) t +(** + Returns intersection of two sets. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) + let s1 = Belt.Set.Dict.fromArray([5, 2, 3, 1, 5, 4], ~cmp=IntCmp.cmp) + let intersect = Belt.Set.Dict.intersect(s0, s1, ~cmp=IntCmp.cmp) + intersect->Belt.Set.Dict.toArray /* [2,3,5] */ + ``` +*) val diff: ('value, 'id) t -> ('value, 'id) t -> cmp:('value, 'id) cmp -> ('value, 'id) t +(** + Returns elements from first set, not existing in second set. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) + let s1 = Belt.Set.Dict.fromArray([5, 2, 3, 1, 5, 4], ~cmp=IntCmp.cmp) + + let diff1 = Belt.Set.Dict.diff(s0, s1, ~cmp=IntCmp.cmp) + let diff2 = Belt.Set.Dict.diff(s1, s0, ~cmp=IntCmp.cmp) + + diff1->Belt.Set.Dict.toArray /* [6] */ + diff2->Belt.Set.Dict.toArray /* [1,4] */ + ``` +*) val subset: ('value, 'id) t -> ('value, 'id) t -> cmp:('value, 'id) cmp -> bool -(** `subset s1 s2` tests whether the set `s1` is a subset of - the set `s2`. *) +(** + Checks if second set is subset of first set. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) + let s1 = Belt.Set.Dict.fromArray([5, 2, 3, 1, 5, 4], ~cmp=IntCmp.cmp) + let s2 = Belt.Set.Dict.intersect(s0, s1, ~cmp=IntCmp.cmp) + Belt.Set.Dict.subset(s2, s0, ~cmp=IntCmp.cmp) /* true */ + Belt.Set.Dict.subset(s2, s1, ~cmp=IntCmp.cmp) /* true */ + Belt.Set.Dict.subset(s1, s0, ~cmp=IntCmp.cmp) /* false */ + ``` +*) val cmp: ('value, 'id) t -> ('value, 'id) t -> cmp:('value, 'id) cmp -> int -(** Total ordering between sets. Can be used as the ordering function - for doing sets of sets. *) +(** + 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. +*) val eq: ('value, 'id) t -> ('value, 'id) t -> cmp:('value, 'id) cmp -> bool -(** `eq s1 s2` tests whether the sets `s1` and `s2` are - equal, that is, contain equal elements. *) +(** + Checks if two sets are equal. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([5, 2, 3], ~cmp=IntCmp.cmp) + let s1 = Belt.Set.Dict.fromArray([3, 2, 5], ~cmp=IntCmp.cmp) + + Belt.Set.Dict.eq(s0, s1, ~cmp=IntCmp.cmp) /* true */ + ``` +*) val forEachU: ('value, 'id) t -> ('value -> unit [@bs]) -> unit +(** + Same as [forEach](##forEach) but takes uncurried functon. +*) + val forEach: ('value, 'id) t -> ('value -> unit) -> unit -(** `forEach s f` applies `f` in turn to all elements of `s`. - In increasing order *) +(** + Applies function `f` in turn to all elements of set in increasing order. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) + let acc = ref(list{}) + s0->Belt.Set.Dict.forEach(x => acc := Belt.List.add(acc.contents, x)) + acc /* [6,5,3,2] */ + ``` +*) val reduceU: ('value, 'id) t -> 'a -> ('a -> 'value -> 'a [@bs]) -> 'a + val reduce: ('value, 'id) t -> 'a -> ('a -> 'value -> 'a) -> 'a -(** Iterate in increasing order. *) +(** + 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. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) + s0->Belt.Set.Dict.reduce(list{}, (acc, element) => acc->Belt.List.add(element)) /* [6,5,3,2] */ + ``` +*) val everyU: ('value, 'id) t -> ('value -> bool [@bs]) -> bool + val every: ('value, 'id) t -> ('value -> bool) -> bool -(** `every p s` checks if all elements of the set - satisfy the predicate `p`. Order unspecified. *) +(** + Checks if all elements of the set satisfy the predicate. Order unspecified. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let isEven = x => mod(x, 2) == 0 + + let s0 = Belt.Set.Dict.fromArray([2, 4, 6, 8], ~cmp=IntCmp.cmp) + s0->Belt.Set.Dict.every(isEven) /* true */ + ``` +*) val someU: ('value, 'id) t -> ('value -> bool [@bs]) -> bool + val some: ('value, 'id) t -> ('value -> bool) -> bool -(** `some p s` checks if at least one element of - the set satisfies the predicate `p`. Oder unspecified. *) +(** + Checks if at least one element of the set satisfies the predicate. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let isOdd = x => mod(x, 2) != 0 + + let s0 = Belt.Set.Dict.fromArray([1, 2, 4, 6, 8], ~cmp=IntCmp.cmp) + s0->Belt.Set.Dict.some(isOdd) /* true */ + ``` +*) val keepU: ('value, 'id) t -> ('value -> bool [@bs]) -> ('value, 'id) t + val keep: ('value, 'id) t -> ('value -> bool) -> ('value, 'id) t -(** `keep p s` returns the set of all elements in `s` - that satisfy predicate `p`. *) +(** + Returns the set of all elements that satisfy the predicate. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let isEven = x => mod(x, 2) == 0 + + let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4, 5], ~cmp=IntCmp.cmp) + let s1 = s0->Belt.Set.Dict.keep(isEven) + + s1->Belt.Set.Dict.toArray /* [2,4] */ + ``` +*) val partitionU: ('value, 'id) t -> ('value -> bool [@bs]) -> ('value, 'id) t * ('value, 'id) t + val partition: ('value, 'id) t -> ('value -> bool) -> ('value, 'id) t * ('value, 'id) t (** - `partition p s` returns a pair of sets `(s1, s2)`, where - `s1` is the set of all the elements of `s` that satisfy the - predicate `p`, and `s2` is the set of all the elements of - `s` that do not satisfy `p`. + 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. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let isOdd = x => mod(x, 2) != 0 + + let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4, 5], ~cmp=IntCmp.cmp) + let (s1, s2) = s0->Belt.Set.Dict.partition(isOdd) + + s1->Belt.Set.Dict.toArray /* [1,3,5] */ + s2->Belt.Set.Dict.toArray /* [2,4] */ + ``` *) val size: ('value, 'id) t -> int +(** + Returns size of the set. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4], ~cmp=IntCmp.cmp) + + s0->Belt.Set.Dict.size /* 4 */ + ``` +*) val toList: ('value, 'id) t -> 'value list -(** In increasing order *) +(** + Returns list of ordered set elements. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) + + s0->Belt.Set.Dict.toList /* [1,2,3,5] */ + ``` +*) val toArray: ('value, 'id) t -> 'value array +(** + Returns array of ordered set elements. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) + + s0->Belt.Set.Dict.toArray /* [1,2,3,5] */ + ``` +*) val minimum: ('value, 'id) t -> 'value option +(** + Returns minimum value of the collection. `None` if collection is empty. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.empty + let s1 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) + + s0->Belt.Set.Dict.minimum /* None */ + s1->Belt.Set.Dict.minimum /* Some(1) */ + ``` +*) val minUndefined: ('value, 'id) t -> 'value Js.undefined +(** + Returns minimum value of the collection. `undefined` if collection is empty. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.empty + let s1 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) + + s0->Belt.Set.Dict.minUndefined /* undefined */ + s1->Belt.Set.Dict.minUndefined /* 1 */ + ``` +*) val maximum: ('value, 'id) t -> 'value option +(** + Returns maximum value of the collection. `None` if collection is empty. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.empty + let s1 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) + + s0->Belt.Set.Dict.maximum /* None */ + s1->Belt.Set.Dict.maximum /* Some(5) */ + ``` +*) val maxUndefined: ('value, 'id) t -> 'value Js.undefined +(** + Returns maximum value of the collection. `undefined` if collection is empty. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.empty + let s1 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) + + s0->Belt.Set.Dict.maxUndefined /* undefined */ + s1->Belt.Set.Dict.maxUndefined /* 5 */ + ``` +*) val get: ('value, 'id) t -> 'value -> cmp:('value, 'id) cmp -> 'value option +(** + 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. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4, 5], ~cmp=IntCmp.cmp) + + s0->Belt.Set.Dict.get(3, ~cmp=IntCmp.cmp) /* Some(3) */ + s0->Belt.Set.Dict.get(20, ~cmp=IntCmp.cmp) /* None */ + ``` +*) val getUndefined: ('value, 'id) t -> 'value -> cmp:('value, 'id) cmp -> 'value Js.undefined +(** + Same as [get](#get) but returns `undefined` when element does not exist. +*) val getExn: ('value, 'id) t -> 'value -> cmp:('value, 'id) cmp -> 'value +(** + Same as [get](#get) but raise when element does not exist. +*) val split: ('value, 'id) t -> 'value -> cmp:('value, 'id) cmp -> (('value, 'id) t * ('value, 'id) t) * bool -(** `split x s` returns a triple `(l, present, r)`, where - `l` is the set of elements of `s` that are - strictly less than `x`; - `r` is the set of elements of `s` that are - strictly greater than `x`; - `present` is `false` if `s` contains no element equal to `x`, - or `true` if `s` contains an element equal to `x`. +(** + Returns a tuple `((smaller, larger), present)`, `present` is true when element exist in set. + + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4, 5], ~cmp=IntCmp.cmp) + + let ((smaller, larger), present) = s0->Belt.Set.Dict.split(3, ~cmp=IntCmp.cmp) + + present /* true */ + smaller->Belt.Set.Dict.toArray /* [1,2] */ + larger->Belt.Set.Dict.toArray /* [4,5] */ + ``` *) val checkInvariantInternal: _ t -> unit diff --git a/jscomp/others/belt_SetInt.mli b/jscomp/others/belt_SetInt.mli index 45336e5cd2..33b665ce6c 100644 --- a/jscomp/others/belt_SetInt.mli +++ b/jscomp/others/belt_SetInt.mli @@ -28,121 +28,407 @@ It is more efficient in general, the API is the same with [`Belt_Set`]() except its value type is fixed, and identity is not needed(using the built-in one) + Specalized when value type is `int`, more efficient than the generic type, its compare behavior is fixed using the built-in comparison. + **See** [`Belt.Set`]() *) # 36 "others/belt_Set.cppo.mli" type value = int - + # 40 "others/belt_Set.cppo.mli" (** The type of the set elements. *) type t -(** The type of sets. *) +(** + Type of the sets. +*) val empty: t +(** + Empty set + ```res example + let s0 = Belt.Set.Int.empty + ``` +*) val fromArray: value array -> t +(** + Creates new set from array of elements. + + ```res example + let s0 = Belt.Set.Int.fromArray([1, 3, 2, 4]) + + s0->Belt.Set.Int.toArray /* [1, 2, 3, 4] */ + ``` +*) val fromSortedArrayUnsafe: value array -> t +(** + The same as [fromArray][#fromarray] except it is after assuming the input array is already sorted. +*) val isEmpty: t -> bool +(** + Checks if set is empty. + + ```res example + let empty = Belt.Set.Int.fromArray([]) + let notEmpty = Belt.Set.Int.fromArray([1]) + + Belt.Set.Int.isEmpty(empty) /* true */ + Belt.Set.Int.isEmpty(notEmpty) /* false */ + ``` +*) val has: t -> value -> bool +(** + Checks if element exists in set. + + ```res example + let set = Belt.Set.Int.fromArray([1, 4, 2, 5]) + + set->Belt.Set.Int.has(3) /* false */ + set->Belt.Set.Int.has(1) /* true */ + ``` +*) val add: t -> value -> t -(** `add s x` If `x` was already in `s`, `s` is returned unchanged. *) +(** + Adds element to set. If element existed in set, value is unchanged. + + ```res example + let s0 = Belt.Set.Int.empty + let s1 = s0->Belt.Set.Int.add(1) + let s2 = s1->Belt.Set.Int.add(2) + let s3 = s2->Belt.Set.Int.add(2) + s0->Belt.Set.Int.toArray /* [] */ + s1->Belt.Set.Int.toArray /* [1] */ + s2->Belt.Set.Int.toArray /* [1, 2] */ + s3->Belt.Set.Int.toArray /* [1,2 ] */ + s2 == s3 /* true */ + ``` +*) val mergeMany: t -> value array -> t +(** + Adds each element of array to set. Unlike [add](#add), the reference of return value might be changed even if all values in array already exist in set + + ```res example + let set = Belt.Set.Int.empty + + let newSet = set->Belt.Set.Int.mergeMany([5, 4, 3, 2, 1]) + newSet->Belt.Set.Int.toArray /* [1, 2, 3, 4, 5] */ + ``` +*) val remove: t -> value -> t -(** `remove m x` If `x` was not in `m`, `m` is returned reference unchanged. *) +(** + Removes element from set. If element wasn't existed in set, value is unchanged. + + ```res example + let s0 = Belt.Set.Int.fromArray([2, 3, 1, 4, 5]) + let s1 = s0->Belt.Set.Int.remove(1) + let s2 = s1->Belt.Set.Int.remove(3) + let s3 = s2->Belt.Set.Int.remove(3) + + s1->Belt.Set.Int.toArray /* [2,3,4,5] */ + s2->Belt.Set.Int.toArray /* [2,4,5] */ + s2 == s3 /* true */ + ``` +*) val removeMany: t -> value array -> t +(** + Removes each element of array from set. Unlike [remove](#remove), the reference of return value might be changed even if any values in array not existed in set. + + ```res example + let set = Belt.Set.Int.fromArray([1, 2, 3, 4]) + + let newSet = set->Belt.Set.Int.removeMany([5, 4, 3, 2, 1]) + newSet->Belt.Set.Int.toArray /* [] */ + ``` +*) val union: t -> t -> t +(** + Returns union of two sets. + + ```res example + let s0 = Belt.Set.Int.fromArray([5, 2, 3, 5, 6]) + let s1 = Belt.Set.Int.fromArray([5, 2, 3, 1, 5, 4]) + let union = Belt.Set.Int.union(s0, s1) + union->Belt.Set.Int.toArray /* [1,2,3,4,5,6] */ + ``` +*) val intersect: t -> t -> t +(** + Returns intersection of two sets. + + ```res example + let s0 = Belt.Set.Int.fromArray([5, 2, 3, 5, 6]) + let s1 = Belt.Set.Int.fromArray([5, 2, 3, 1, 5, 4]) + let intersect = Belt.Set.Int.intersect(s0, s1) + intersect->Belt.Set.Int.toArray /* [2,3,5] */ + ``` +*) val diff: t -> t -> t +(** + Returns elements from first set, not existing in second set. + + ```res example + let s0 = Belt.Set.Int.fromArray([5, 2, 3, 5, 6]) + let s1 = Belt.Set.Int.fromArray([5, 2, 3, 1, 5, 4]) + Belt.Set.Int.toArray(Belt.Set.Int.diff(s0, s1)) /* [6] */ + Belt.Set.Int.toArray(Belt.Set.Int.diff(s1, s0)) /* [1,4] */ + ``` +*) val subset: t -> t -> bool -(** `subset s1 s2` tests whether the set `s1` is a subset of - the set `s2`. *) +(** + Checks if second set is subset of first set. + + ```res example + let s0 = Belt.Set.Int.fromArray([5, 2, 3, 5, 6]) + let s1 = Belt.Set.Int.fromArray([5, 2, 3, 1, 5, 4]) + let s2 = Belt.Set.Int.intersect(s0, s1) + Belt.Set.Int.subset(s2, s0) /* true */ + Belt.Set.Int.subset(s2, s1) /* true */ + Belt.Set.Int.subset(s1, s0) /* false */ + ``` +*) val cmp: t -> t -> int -(** Total ordering between sets. Can be used as the ordering function - for doing sets of sets. *) +(** + 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. +*) val eq: t -> t -> bool -(** `eq s1 s2` tests whether the sets `s1` and `s2` are - equal, that is, contain equal elements. *) +(** + Checks if two sets are equal. + + ```res example + let s0 = Belt.Set.Int.fromArray([5, 2, 3]) + let s1 = Belt.Set.Int.fromArray([3, 2, 5]) + + Belt.Set.Int.eq(s0, s1) /* true */ + ``` +*) val forEachU: t -> (value -> unit [@bs]) -> unit +(** + Same as [forEach](##forEach) but takes uncurried functon. +*) + val forEach: t -> (value -> unit) -> unit -(** `forEach s f` applies `f` in turn to all elements of `s`. - In increasing order *) +(** + Applies function `f` in turn to all elements of set in increasing order. + + ```res example + let s0 = Belt.Set.Int.fromArray([5, 2, 3, 5, 6]) + let acc = ref(list{}) + s0->Belt.Set.Int.forEach(x => acc := Belt.List.add(acc.contents, x)) + acc /* [6,5,3,2] */ + ``` +*) val reduceU: t -> 'a -> ('a -> value -> 'a [@bs]) -> 'a + val reduce: t -> 'a -> ('a -> value -> 'a) -> 'a -(** Iterate in increasing order. *) +(** + 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. + + ```res example + let s0 = Belt.Set.Int.fromArray([5, 2, 3, 5, 6]) + s0->Belt.Set.Int.reduce(list{}, (acc, element) => acc->Belt.List.add(element)) /* [6,5,3,2] */ + ``` +*) val everyU: t -> (value -> bool [@bs]) -> bool + val every: t -> (value -> bool) -> bool -(** `every p s` checks if all elements of the set - satisfy the predicate `p`. Order unspecified. *) +(** + Checks if all elements of the set satisfy the predicate. Order unspecified. + + ```res example + let isEven = x => mod(x, 2) == 0 + + let s0 = Belt.Set.Int.fromArray([2, 4, 6, 8]) + s0->Belt.Set.Int.every(isEven) /* true */ + ``` +*) val someU: t -> (value -> bool [@bs]) -> bool + val some: t -> (value -> bool) -> bool -(** `some p s` checks if at least one element of - the set satisfies the predicate `p`. Oder unspecified. *) +(** + Checks if at least one element of the set satisfies the predicate. + + ```res example + let isOdd = x => mod(x, 2) != 0 + + let s0 = Belt.Set.Int.fromArray([1, 2, 4, 6, 8]) + s0->Belt.Set.Int.some(isOdd) /* true */ + ``` +*) val keepU: t -> (value -> bool [@bs]) -> t + val keep: t -> (value -> bool) -> t -(** `keep p s` returns the set of all elements in `s` - that satisfy predicate `p`. *) +(** + Returns the set of all elements that satisfy the predicate. + + ```res example + let isEven = x => mod(x, 2) == 0 + + let s0 = Belt.Set.Int.fromArray([1, 2, 3, 4, 5]) + let s1 = s0->Belt.Set.Int.keep(isEven) + + s1->Belt.Set.Int.toArray /* [2,4] */ + ``` +*) val partitionU: t -> (value -> bool [@bs]) -> t * t + val partition: t -> (value -> bool) -> t * t (** - `partition p s` returns a pair of sets `(s1, s2)`, where - `s1` is the set of all the elements of `s` that satisfy the - predicate `p`, and `s2` is the set of all the elements of - `s` that do not satisfy `p`. + 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. + + ```res example + let isOdd = x => mod(x, 2) != 0 + + let s0 = Belt.Set.Int.fromArray([1, 2, 3, 4, 5]) + let (s1, s2) = s0->Belt.Set.Int.partition(isOdd) + + s1->Belt.Set.Int.toArray /* [1,3,5] */ + s2->Belt.Set.Int.toArray /* [2,4] */ + ``` *) val size: t -> int +(** + Returns size of the set. + + ```res example + let s0 = Belt.Set.Int.fromArray([1, 2, 3, 4]) + + s0->Belt.Set.Int.size /* 4 */ + ``` +*) val toList: t -> value list -(** In increasing order *) +(** + Returns list of ordered set elements. + + ```res example + let s0 = Belt.Set.Int.fromArray([3, 2, 1, 5]) + + s0->Belt.Set.Int.toList /* [1,2,3,5] */ + ``` +*) val toArray: t -> value array +(** + Returns array of ordered set elements. + + ```res example + let s0 = Belt.Set.Int.fromArray([3, 2, 1, 5]) + + s0->Belt.Set.Int.toArray /* [1,2,3,5] */ + ``` +*) val minimum: t -> value option +(** + Returns minimum value of the collection. `None` if collection is empty. + + ```res example + let s0 = Belt.Set.Int.empty + let s1 = Belt.Set.Int.fromArray([3, 2, 1, 5]) + + s0->Belt.Set.Int.minimum /* None */ + s1->Belt.Set.Int.minimum /* Some(1) */ + ``` +*) val minUndefined: t -> value Js.undefined +(** + Returns minimum value of the collection. `undefined` if collection is empty. + + ```res example + let s0 = Belt.Set.Int.empty + let s1 = Belt.Set.Int.fromArray([3, 2, 1, 5]) + + s0->Belt.Set.Int.minUndefined /* undefined */ + s1->Belt.Set.Int.minUndefined /* 1 */ + ``` +*) val maximum: t -> value option +(** + Returns maximum value of the collection. `None` if collection is empty. + + ```res example + let s0 = Belt.Set.Int.empty + let s1 = Belt.Set.Int.fromArray([3, 2, 1, 5]) + + s0->Belt.Set.Int.maximum /* None */ + s1->Belt.Set.Int.maximum /* Some(5) */ + ``` +*) val maxUndefined: t -> value Js.undefined +(** + Returns maximum value of the collection. `undefined` if collection is empty. + + ```res example + let s0 = Belt.Set.Int.empty + let s1 = Belt.Set.Int.fromArray([3, 2, 1, 5]) + + s0->Belt.Set.Int.maxUndefined /* undefined */ + s1->Belt.Set.Int.maxUndefined /* 5 */ + ``` +*) val get: t -> value -> value option +(** + 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. + + ```res example + let s0 = Belt.Set.Int.fromArray([1, 2, 3, 4, 5]) + + s0->Belt.Set.Int.get(3) /* Some(3) */ + s0->Belt.Set.Int.get(20) /* None */ + ``` +*) val getUndefined: t -> value -> value Js.undefined +(** + Same as [get](#get) but returns `undefined` when element does not exist. +*) val getExn: t -> value -> value +(** + Same as [get](#get) but raise when element does not exist. +*) val split: t -> value -> (t * t) * bool (** - `split x s` returns a triple `(l, present, r)`, where - `l` is the set of elements of `s` that are - strictly less than `x`; - `r` is the set of elements of `s` that are - strictly greater than `x`; - `present` is `false` if `s` contains no element equal to `x`, - or `true` if `s` contains an element equal to `x`. + Returns a tuple `((l, r), present)`, where `l` is the set of elements of set that are strictly less than value, `r` is the set of elements of set that are strictly greater than value, `present` is `false` if set contains no element equal to value, or `true` if set contains an element equal to value. + + ```res example + let s0 = Belt.Set.Int.fromArray([1, 2, 3, 4, 5]) + + let ((smaller, larger), present) = s0->Belt.Set.Int.split(3) + + present /* true */ + smaller->Belt.Set.Int.toArray /* [1,2] */ + larger->Belt.Set.Int.toArray /* [4,5] */ + ``` *) val checkInvariantInternal: t -> unit diff --git a/jscomp/others/belt_SetString.mli b/jscomp/others/belt_SetString.mli index 742d1f1a9e..5f5ba5b8ba 100644 --- a/jscomp/others/belt_SetString.mli +++ b/jscomp/others/belt_SetString.mli @@ -28,121 +28,408 @@ It is more efficient in general, the API is the same with [`Belt_Set`]() except its value type is fixed, and identity is not needed(using the built-in one) + Specalized when value type is `string`, more efficient than the generic type, its compare behavior is fixed using the built-in comparison. + **See** [`Belt.Set`]() *) # 34 "others/belt_Set.cppo.mli" type value = string - + # 40 "others/belt_Set.cppo.mli" - (** The type of the set elements. *) +(** The type of the set elements. *) type t -(** The type of sets. *) +(** + The type of sets. +*) val empty: t +(** + Empty set + ```res example + let s0 = Belt.Set.String.empty + ``` +*) val fromArray: value array -> t +(** + Creates new set from array of elements. + + ```res example + let s0 = Belt.Set.String.fromArray(["apple", "orange", "banana"]) + + s0->Belt.Set.String.toArray /* ["apple", "banana", "orange"] */ + ``` +*) val fromSortedArrayUnsafe: value array -> t +(** + The same as [fromArray][#fromarray] except it is after assuming the input array is already sorted. +*) val isEmpty: t -> bool +(** + Checks if set is empty. + + ```res example + let empty = Belt.Set.String.fromArray([]) + let notEmpty = Belt.Set.String.fromArray(["apple"]) + + Belt.Set.String.isEmpty(empty) /* true */ + Belt.Set.String.isEmpty(notEmpty) /* false */ + ``` +*) val has: t -> value -> bool +(** + Checks if element exists in set. + + ```res example + let set = Belt.Set.String.fromArray(["apple", "orange", "banana"]) + + set->Belt.Set.String.has("strawberry") /* false */ + set->Belt.Set.String.has("apple") /* true */ + ``` +*) val add: t -> value -> t -(** `add s x` If `x` was already in `s`, `s` is returned unchanged. *) +(** + Adds element to set. If element existed in set, value is unchanged. + + ```res example + let s0 = Belt.Set.String.empty + let s1 = s0->Belt.Set.String.add("apple") + let s2 = s1->Belt.Set.String.add("banana") + let s3 = s2->Belt.Set.String.add("banana") + s0->Belt.Set.String.toArray /* [] */ + s1->Belt.Set.String.toArray /* ["apple"] */ + s2->Belt.Set.String.toArray /* ["apple", "banana"] */ + s3->Belt.Set.String.toArray /* ["apple", "banana"] */ + s2 == s3 /* true */ + ``` +*) val mergeMany: t -> value array -> t +(** + Adds each element of array to set. Unlike [add](#add), the reference of return value might be changed even if all values in array already exist in set + + ```res example + let set = Belt.Set.String.empty + + let newSet = set->Belt.Set.String.mergeMany(["apple", "banana", "orange", "strawberry"]) + + newSet->Belt.Set.String.toArray /* ["apple", "banana", "orange", "strawberry"] */ + ``` +*) val remove: t -> value -> t -(** `remove m x` If `x` was not in `m`, `m` is returned reference unchanged. *) +(** + Removes element from set. If element wasn't existed in set, value is unchanged. + + ```res example + let s0 = Belt.Set.String.fromArray(["orange", "banana", "apple"]) + let s1 = s0->Belt.Set.String.remove("apple") + let s2 = s1->Belt.Set.String.remove("banana") + let s3 = s2->Belt.Set.String.remove("banana") + + s1->Belt.Set.String.toArray /* ["orange", "banana"] */ + s2->Belt.Set.String.toArray /* ["orange"] */ + s2 == s3 /* true */ + ``` +*) val removeMany: t -> value array -> t +(** + Removes each element of array from set. Unlike [remove](#remove), the reference of return value might be changed even if any values in array not existed in set. + + ```res example + let set = Belt.Set.String.fromArray(["apple", "banana", "orange"]) + + let newSet = set->Belt.Set.String.removeMany(["strawberry", "apple", "banana", "orange"]) + newSet->Belt.Set.String.toArray /* [] */ + ``` +*) val union: t -> t -> t +(** + Returns union of two sets. + + ```res example + let s0 = Belt.Set.String.fromArray(["apple", "banana", "orange", "carrot"]) + let s1 = Belt.Set.String.fromArray(["apple", "banana", "orange", "strawberry"]) + let union = Belt.Set.String.union(s0, s1) + union->Belt.Set.String.toArray /* ["apple", "banana", "carrot", "orange", "strawberry"] */ + ``` +*) val intersect: t -> t -> t +(** + Returns intersection of two sets. + + ```res example + let s0 = Belt.Set.String.fromArray(["apple", "banana", "orange", "carrot"]) + let s1 = Belt.Set.String.fromArray(["apple", "banana", "orange", "strawberry"]) + let intersect = Belt.Set.String.intersect(s0, s1) + intersect->Belt.Set.String.toArray /* ["apple", "banana", "orange"] */ + ``` +*) val diff: t -> t -> t +(** + Returns elements from first set, not existing in second set. + + ```res example + let s0 = Belt.Set.String.fromArray(["apple", "banana", "orange", "carrot"]) + let s1 = Belt.Set.String.fromArray(["apple", "banana", "orange", "strawberry"]) + Belt.Set.String.toArray(Belt.Set.String.diff(s0, s1)) /* ["carrot"] */ + Belt.Set.String.toArray(Belt.Set.String.diff(s1, s0)) /* ["strawberry"] */ + ``` +*) val subset: t -> t -> bool -(** `subset s1 s2` tests whether the set `s1` is a subset of - the set `s2`. *) +(** + Checks if second set is subset of first set. + + ```res example + let s0 = Belt.Set.String.fromArray(["5", "2", "3", "5", "6"]) + let s1 = Belt.Set.String.fromArray(["5", "2", "3", "1", "5", "4"]) + let s2 = Belt.Set.String.intersect(s0, s1) + Belt.Set.String.subset(s2, s0) /* true */ + Belt.Set.String.subset(s2, s1) /* true */ + Belt.Set.String.subset(s1, s0) /* false */ + ``` +*) val cmp: t -> t -> int -(** Total ordering between sets. Can be used as the ordering function - for doing sets of sets. *) +(** + 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. +*) val eq: t -> t -> bool -(** `eq s1 s2` tests whether the sets `s1` and `s2` are - equal, that is, contain equal elements. *) +(** + Checks if two sets are equal. + + ```res example + let s0 = Belt.Set.String.fromArray(["apple", "orange"]) + let s1 = Belt.Set.String.fromArray(["orange", "apple"]) + + Belt.Set.String.eq(s0, s1) /* true */ + ``` +*) val forEachU: t -> (value -> unit [@bs]) -> unit +(** + Same as [forEach](##forEach) but takes uncurried functon. +*) + val forEach: t -> (value -> unit) -> unit -(** `forEach s f` applies `f` in turn to all elements of `s`. - In increasing order *) +(** + Applies function `f` in turn to all elements of set in increasing order. + + ```res example + let s0 = Belt.Set.String.fromArray(["banana", "orange", "apple"]) + let acc = ref(list{}) + s0->Belt.Set.String.forEach(x => acc := Belt.List.add(acc.contents, x)) + acc /* ["orange", "banana", "apple"] */ + ``` +*) val reduceU: t -> 'a -> ('a -> value -> 'a [@bs]) -> 'a + val reduce: t -> 'a -> ('a -> value -> 'a) -> 'a -(** Iterate in increasing order. *) +(** + 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. + + ```res example + let s0 = Belt.Set.String.fromArray(["apple", "orange"]) + s0->Belt.Set.String.reduce(0, (acc, element) => acc + String.length(element)) /* 11 */ + ``` +*) val everyU: t -> (value -> bool [@bs]) -> bool + val every: t -> (value -> bool) -> bool -(** `every p s` checks if all elements of the set - satisfy the predicate `p`. Order unspecified. *) +(** + Checks if all elements of the set satisfy the predicate. Order unspecified. + + ```res example + let hasAtLeastFiveChars = x => String.length(x) >= 5 + + let s0 = Belt.Set.String.fromArray(["apple", "carrot"]) + s0->Belt.Set.String.every(hasAtLeastFiveChars) /* true */ + ``` +*) val someU: t -> (value -> bool [@bs]) -> bool + val some: t -> (value -> bool) -> bool -(** `some p s` checks if at least one element of - the set satisfies the predicate `p`. Oder unspecified. *) +(** + Checks if at least one element of the set satisfies the predicate. + + ```res example + let hasFiveChars = x => String.length(x) == 5 + + let s0 = Belt.Set.String.fromArray(["strawberry", "apple"]) + s0->Belt.Set.String.some(hasFiveChars) /* true */ + ``` +*) val keepU: t -> (value -> bool [@bs]) -> t + val keep: t -> (value -> bool) -> t -(** `keep p s` returns the set of all elements in `s` - that satisfy predicate `p`. *) +(** + Returns the set of all elements that satisfy the predicate. + + ```res example + let hasFiveChars = x => String.length(x) == 5 + + let s0 = Belt.Set.String.fromArray(["apple", "orange", "banana"]) + let s1 = s0->Belt.Set.String.keep(hasFiveChars) + + s1->Belt.Set.String.toArray /* ["apple"] */ + ``` +*) val partitionU: t -> (value -> bool [@bs]) -> t * t + val partition: t -> (value -> bool) -> t * t (** - `partition p s` returns a pair of sets `(s1, s2)`, where - `s1` is the set of all the elements of `s` that satisfy the - predicate `p`, and `s2` is the set of all the elements of - `s` that do not satisfy `p`. + 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. + + ```res example + let hasFiveChars = x => String.length(x) == 5 + + let s0 = Belt.Set.String.fromArray(["apple", "carrot"]) + let (s1, s2) = s0->Belt.Set.String.partition(hasFiveChars) + + s1->Belt.Set.String.toArray /* ["apple"] */ + s2->Belt.Set.String.toArray /* ["carrot"] */ + ``` *) val size: t -> int +(** + Returns size of the set. + + ```res example + let s0 = Belt.Set.String.fromArray(["apple"]) + + s0->Belt.Set.String.size /* 1 */ + ``` +*) val toList: t -> value list -(** In increasing order *) +(** + Returns list of ordered set elements. + + ```res example + let s0 = Belt.Set.String.fromArray(["apple", "watermelon"]) + + s0->Belt.Set.String.toList /* ["apple", "watermelon"] */ + ``` +*) val toArray: t -> value array +(** + Returns array of ordered set elements. + + ```res example + let s0 = Belt.Set.String.fromArray(["apple", "watermelon"]) + + s0->Belt.Set.String.toArray /* ["apple", "watermelon"] */ + ``` +*) val minimum: t -> value option +(** + Returns minimum value of the collection. `None` if collection is empty. + + ```res example + let s0 = Belt.Set.String.empty + let s1 = Belt.Set.String.fromArray(["apple", "orange"]) + + s0->Belt.Set.String.minimum /* None */ + s1->Belt.Set.String.minimum /* Some("apple") */ + ``` +*) val minUndefined: t -> value Js.undefined +(** + Returns minimum value of the collection. `undefined` if collection is empty. + + ```res example + let s0 = Belt.Set.String.empty + let s1 = Belt.Set.String.fromArray(["apple", "orange"]) + + s0->Belt.Set.String.minUndefined /* undefined */ + s1->Belt.Set.String.minUndefined /* "apple" */ + ``` +*) val maximum: t -> value option +(** + Returns maximum value of the collection. `None` if collection is empty. + + ```res example + let s0 = Belt.Set.String.empty + let s1 = Belt.Set.String.fromArray(["apple", "orange"]) + + s0->Belt.Set.String.maximum /* None */ + s1->Belt.Set.String.maximum /* Some("orange") */ + ``` +*) val maxUndefined: t -> value Js.undefined +(** + Returns maximum value of the collection. `undefined` if collection is empty. + + ```res example + let s0 = Belt.Set.String.empty + let s1 = Belt.Set.String.fromArray(["apple", "orange"]) + + s0->Belt.Set.String.maxUndefined /* undefined */ + s1->Belt.Set.String.maxUndefined /* orange */ + ``` +*) val get: t -> value -> value option +(** + 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. + + ```res example + let s0 = Belt.Set.String.fromArray(["apple", "carrot"]) + + s0->Belt.Set.String.get("carrot") /* Some("carrot") */ + s0->Belt.Set.String.get("watermelon") /* None */ + ``` +*) val getUndefined: t -> value -> value Js.undefined +(** + See [get](#get) - returns `undefined` when element does not exist. +*) val getExn: t -> value -> value +(** + See [get](#get) - raise when element does not exist. +*) val split: t -> value -> (t * t) * bool (** - `split x s` returns a triple `(l, present, r)`, where - `l` is the set of elements of `s` that are - strictly less than `x`; - `r` is the set of elements of `s` that are - strictly greater than `x`; - `present` is `false` if `s` contains no element equal to `x`, - or `true` if `s` contains an element equal to `x`. + Returns a triple `((l, r), present)`, where `l` is the set of elements of set that are strictly less than value, `r` is the set of elements of set that are strictly greater than value, `present` is `false` if set contains no element equal to value, or `true` if set contains an element equal to value. + + ```res example + let s0 = Belt.Set.String.fromArray(["apple", "banana", "orange"]) + + let ((smaller, larger), present) = s0->Belt.Set.String.split("banana") + + present /* true */ + smaller->Belt.Set.String.toArray /* ["apple"] */ + larger->Belt.Set.String.toArray /* ["orange"] */ + ``` *) val checkInvariantInternal: t -> unit