Skip to content

Commit d6391de

Browse files
bobzhangbobzhang
committed
good docs for set
1 parent 2b9a97b commit d6391de

File tree

6 files changed

+263
-24
lines changed

6 files changed

+263
-24
lines changed

‎jscomp/others/belt.ml

+3-1
Original file line numberDiff line numberDiff line change
@@ -172,8 +172,9 @@ module Range = Belt_Range
172172
173173
It also has three specialized inner modules
174174
{!Belt.Set.Int} and {!Belt.Set.String}
175+
175176
{!Belt.Set.Dict}: This module separate date from function
176-
which is more verbbose but slightly more efficient
177+
which is more verbbose but slightly more efficient
177178
178179
*)
179180
module Set = Belt_Set
@@ -185,6 +186,7 @@ module Set = Belt_Set
185186
186187
It also has three specialized inner modules
187188
{!Belt.Map.Int} and {!Belt.Map.String}
189+
188190
{!Belt.Map.Dict}: This module separate date from function
189191
which is more verbbose but slightly more efficient
190192
*)

‎jscomp/others/belt_Set.mli

+256-19
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ type ('key,'identity) t
101101

102102

103103
type ('key, 'id) id = ('key, 'id) Belt_Id.comparable
104-
(** The identity needed for making an empty set
104+
(** The identity needed for making a set from scratch
105105
*)
106106

107107
val make: id:('elt, 'id) id -> ('elt, 'id) t
@@ -116,57 +116,216 @@ val make: id:('elt, 'id) id -> ('elt, 'id) t
116116

117117

118118
val ofArray: 'k array -> id:('k, 'id) id -> ('k, 'id) t
119+
(** [ofArray xs ~id]
120+
121+
@example{[
122+
module IntCmp = (val IntCmp.comparableU
123+
~cmp:(fun[\@bs]
124+
(x:int) y -> Pervasives.comapre x y));;
125+
toArray (ofArray [1;3;2;4] (module IntCmp)) = [1;2;3;4]
126+
127+
]}
128+
*)
129+
119130

120131
val ofSortedArrayUnsafe: 'elt array -> id:('elt, 'id) id -> ('elt,'id) t
121132
(** [ofSortedArrayUnsafe xs ~id]
122133
123-
The same as {!ofArray} except it is after assuming the array is already sorted
134+
The same as {!ofArray} except it is after assuming the input array [x] is already sorted
124135
125-
{b unsafe} assuming the input is sorted
136+
{b Unsafe}
126137
*)
127138

128139

129140
val isEmpty: _ t -> bool
141+
(**
142+
@example {[
143+
module IntCmp =
144+
(val IntCmp.comparableU
145+
~cmp:(fun[\@bs]
146+
(x:int) y -> Pervasives.comapre x y));;
147+
isEmpty (ofArray [||] ~id:(module IntCmp)) = true;;
148+
isEmpty (ofArray [|1|] ~id:(module IntCmp)) = true;;
149+
]}
150+
*)
130151
val has: ('elt, 'id) t -> 'elt -> bool
131-
152+
(**
153+
@example {[
154+
module IntCmp =
155+
(val IntCmp.comparableU
156+
~cmp:(fun[\@bs]
157+
(x:int) y -> Pervasives.comapre x y));;
158+
let v = ofArray [|1;4;2;5|] ~id:(module IntCmp);;
159+
has v 3 = false;;
160+
has v 1 = true;;
161+
]}
162+
*)
132163

133164
val add:
134165
('elt, 'id) t -> 'elt -> ('elt, 'id) t
135-
(** [add s x] If [x] was already in [s], [s] is returned unchanged. *)
166+
(** [add s x] If [x] was already in [s], [s] is returned unchanged.
167+
168+
@example {[
169+
module IntCmp =
170+
(val IntCmp.comparableU
171+
~cmp:(fun[\@bs]
172+
(x:int) y -> Pervasives.comapre x y));;
173+
let s0 = make ~id:(module IntCmp);;
174+
let s1 = add s0 1 ;;
175+
let s2 = add s1 2;;
176+
let s3 = add s2 2;;
177+
toArray s0 = [||];;
178+
toArray s1 = [|1|];;
179+
toArray s2 = [|1;2|];;
180+
toArray s3 = [|1;2|];;
181+
s2 == s3;;
182+
]}
183+
*)
136184

137185
val mergeMany: ('elt, 'id) t -> 'elt array -> ('elt, 'id) t
186+
(** [mergeMany s xs]
138187
188+
Adding each of [xs] to [s], note unlike {!add},
189+
the reference of return value might be changed even if all values in [xs]
190+
exist [s]
191+
192+
*)
139193
val remove: ('elt, 'id) t -> 'elt -> ('elt, 'id) t
140-
(** [remove m x] If [x] was not in [m], [m] is returned reference unchanged. *)
194+
(** [remove m x] If [x] was not in [m], [m] is returned reference unchanged.
195+
196+
@example {[
197+
module IntCmp =
198+
(val IntCmp.comparableU
199+
~cmp:(fun[\@bs]
200+
(x:int) y -> Pervasives.comapre x y));;
201+
let s0 = ofArray ~id:(module IntCmp) [|2;3;1;4;5|];;
202+
let s1 = remove s0 1 ;;
203+
let s2 = remove s1 3 ;;
204+
let s3 = remove s2 3 ;;
205+
206+
toArray s1 = [|2;3;4;5|];;
207+
toArray s2 = [|2;4;5|];;
208+
s2 == s3;;
209+
]}
210+
*)
141211

142212
val removeMany:
143-
('elt, 'id) t -> 'elt array -> ('elt, 'id) t
213+
('elt, 'id) t -> 'elt array -> ('elt, 'id) t
214+
(** [removeMany s xs]
144215
216+
Removing each of [xs] to [s], note unlike {!remove},
217+
the reference of return value might be changed even if none in [xs]
218+
exists [s]
219+
*)
145220

146221
val union: ('elt, 'id) t -> ('elt, 'id) t -> ('elt, 'id) t
147-
val intersect: ('elt, 'id) t -> ('elt, 'id) t -> ('elt, 'id) t
222+
(**
223+
[union s0 s1]
224+
225+
@example {[
226+
module IntCmp =
227+
(val IntCmp.comparableU
228+
~cmp:(fun[\@bs]
229+
(x:int) y -> Pervasives.comapre x y));;
230+
let s0 = ofArray ~id:(module IntCmp) [|5;2;3;5;6|]];;
231+
let s1 = ofArray ~id:(module IntCmp) [|5;2;3;1;5;4;|];;
232+
toArray (union s0 s1) = [|1;2;3;4;5;6|]
233+
]}
234+
*)
235+
236+
val intersect: ('elt, 'id) t -> ('elt, 'id) t -> ('elt, 'id) t
237+
(** [intersect s0 s1]
238+
@example {[
239+
module IntCmp =
240+
(val IntCmp.comparableU
241+
~cmp:(fun[\@bs]
242+
(x:int) y -> Pervasives.comapre x y));;
243+
let s0 = ofArray ~id:(module IntCmp) [|5;2;3;5;6|]];;
244+
let s1 = ofArray ~id:(module IntCmp) [|5;2;3;1;5;4;|];;
245+
toArray (intersect s0 s1) = [|2;3;5|]
246+
]}
247+
248+
*)
148249
val diff: ('elt, 'id) t -> ('elt, 'id) t -> ('elt, 'id) t
149-
val subset: ('elt, 'id) t -> ('elt, 'id) t -> bool
250+
(** [diff s0 s1]
251+
@example {[
252+
module IntCmp =
253+
(val IntCmp.comparableU
254+
~cmp:(fun[\@bs]
255+
(x:int) y -> Pervasives.comapre x y));;
256+
let s0 = ofArray ~id:(module IntCmp) [|5;2;3;5;6|]];;
257+
let s1 = ofArray ~id:(module IntCmp) [|5;2;3;1;5;4;|];;
258+
toArray (diff s0 s1) = [|6|];;
259+
toArray (diff s1 s0) = [|1;4|];;
260+
]}
261+
*)
150262

263+
val subset: ('elt, 'id) t -> ('elt, 'id) t -> bool
264+
(** [subset s0 s1]
265+
266+
@example {[
267+
module IntCmp =
268+
(val IntCmp.comparableU
269+
~cmp:(fun[\@bs]
270+
(x:int) y -> Pervasives.comapre x y));;
271+
let s0 = ofArray ~id:(module IntCmp) [|5;2;3;5;6|]];;
272+
let s1 = ofArray ~id:(module IntCmp) [|5;2;3;1;5;4;|];;
273+
let s2 = intersect s0 s1;;
274+
subset s2 s0 = true;;
275+
subset s1 s0 = true;;
276+
subset s1 s2 = false;;
277+
]}
278+
*)
279+
151280
val cmp: ('elt, 'id) t -> ('elt, 'id) t -> int
152281
(** Total ordering between sets. Can be used as the ordering function
153-
for doing sets of sets. *)
282+
for doing sets of sets.
283+
It compare [size] first and then iterate over
284+
each element following the order of elements
285+
*)
154286

155287
val eq: ('elt, 'id) t -> ('elt, 'id) t -> bool
288+
(** [eq s0 s1]
156289
290+
@return true if [toArray s0 = toArray s1]
291+
*)
292+
157293
val forEachU: ('elt, 'id) t -> ('elt -> unit [@bs]) -> unit
158294
val forEach: ('elt, 'id) t -> ('elt -> unit ) -> unit
159295
(** [forEach s f] applies [f] in turn to all elements of [s].
160-
In increasing order *)
296+
In increasing order
297+
298+
@example {[
299+
module IntCmp =
300+
(val IntCmp.comparableU
301+
~cmp:(fun[\@bs]
302+
(x:int) y -> Pervasives.comapre x y));;
303+
let s0 = ofArray ~id:(module IntCmp) [|5;2;3;5;6|]];;
304+
let acc = ref [] ;;
305+
forEach s0 (fun x -> acc := x !acc);;
306+
!acc = [6;5;3;2];;
307+
]}
308+
*)
161309

162310
val reduceU: ('elt, 'id) t -> 'a -> ('a -> 'elt -> 'a [@bs]) -> 'a
163311
val reduce: ('elt, 'id) t -> 'a -> ('a -> 'elt -> 'a ) -> 'a
164-
(** In increasing order. *)
312+
(** In increasing order.
313+
314+
@example {[
315+
module IntCmp =
316+
(val IntCmp.comparableU
317+
~cmp:(fun[\@bs]
318+
(x:int) y -> Pervasives.comapre x y));;
319+
let s0 = ofArray ~id:(module IntCmp) [|5;2;3;5;6|]];;
320+
reduce s0 [] Bs.List.add = [6;5;3;2];;
321+
]}
322+
*)
165323

166324
val everyU: ('elt, 'id) t -> ('elt -> bool [@bs]) -> bool
167325
val every: ('elt, 'id) t -> ('elt -> bool ) -> bool
168326
(** [every p s] checks if all elements of the set
169-
satisfy the predicate [p]. Order unspecified *)
327+
satisfy the predicate [p]. Order unspecified.
328+
*)
170329

171330
val someU: ('elt, 'id) t -> ('elt -> bool [@bs]) -> bool
172331
val some: ('elt, 'id) t -> ('elt -> bool ) -> bool
@@ -186,32 +345,89 @@ val partition: ('elt, 'id) t -> ('elt -> bool) -> ('elt, 'id) t * ('elt, 'id) t
186345
[s] that do not satisfy [p]. *)
187346

188347
val size: ('elt, 'id) t -> int
189-
val toList: ('elt, 'id) t -> 'elt list
190-
(** In increasing order*)
348+
(** [size s]
349+
350+
@example {[
351+
module IntCmp =
352+
(val IntCmp.comparableU
353+
~cmp:(fun[\@bs]
354+
(x:int) y -> Pervasives.comapre x y));;
355+
let s0 = ofArray ~id:(module IntCmp) [|5;2;3;5;6|]];;
356+
size s0 = 4;;
357+
]}
358+
*)
359+
191360
val toArray: ('elt, 'id) t -> 'elt array
361+
(** [toArray s0]
362+
@example {[
363+
module IntCmp =
364+
(val IntCmp.comparableU
365+
~cmp:(fun[\@bs]
366+
(x:int) y -> Pervasives.comapre x y));;
367+
let s0 = ofArray ~id:(module IntCmp) [|5;2;3;5;6|]];;
368+
toArray s0 = [|2;3;5;6|];;
369+
]}*)
370+
371+
val toList: ('elt, 'id) t -> 'elt list
372+
(** In increasing order
373+
374+
{b See} {!toArray}
375+
*)
192376

193377
val minimum: ('elt, 'id) t -> 'elt option
378+
(** [minimum s0]
379+
380+
@return the minimum element of the collection, [None] if it is empty
381+
*)
382+
194383
val minUndefined: ('elt, 'id) t -> 'elt Js.undefined
384+
(** [minUndefined s0]
385+
386+
@return the minimum element of the collection, [undefined] if it is empty
387+
*)
388+
195389
val maximum: ('elt, 'id) t -> 'elt option
390+
(** [maximum s0]
391+
392+
@return the maximum element of the collection, [None] if it is empty
393+
*)
196394
val maxUndefined: ('elt, 'id) t -> 'elt Js.undefined
395+
(** [maxUndefined s0]
197396
397+
@return the maximum element of the collection, [undefined] if it is empty
398+
*)
198399

400+
val get: ('elt, 'id) t -> 'elt -> 'elt option
401+
(** [get s0 k]
402+
403+
@return the reference of the value [k'] which is equivalent to [k]
404+
using the comparator specifiecd by this collection, [None]
405+
if it does not exist
406+
*)
199407

200-
val get: ('elt, 'id) t -> 'elt -> 'elt option
201408
val getUndefined: ('elt, 'id) t -> 'elt -> 'elt Js.undefined
202-
val getExn: ('elt, 'id) t -> 'elt -> 'elt
409+
(** {b See} {!get}
410+
*)
411+
412+
val getExn: ('elt, 'id) t -> 'elt -> 'elt
413+
(** {b See} {!get}
414+
415+
{b raise} if not exist
416+
*)
203417

204418
val split: ('elt, 'id) t -> 'elt -> (('elt, 'id) t * ('elt, 'id) t) * bool
205419
(** [split set ele]
206420
207421
@return a tuple [((smaller, larger), present)],
208422
[present] is true when [ele] exist in [set]
209-
*)
423+
*)
424+
425+
(**/**)
210426
val checkInvariantInternal: _ t -> unit
211427
(**
212428
{b raise} when invariant is not helld
213429
*)
214-
430+
(**/**)
215431

216432
(****************************************************************************)
217433
(** Below are operations only when better performance needed,
@@ -220,6 +436,27 @@ val checkInvariantInternal: _ t -> unit
220436
*)
221437

222438
val getData: ('k,'id) t -> ('k,'id) Belt_SetDict.t
439+
(** [getData s0]
440+
441+
{b Advanced usage only}
442+
443+
@return the raw data (detached from comparator),
444+
but its type is still manifested, so that user can pass identity directly
445+
without boxing
446+
*)
223447
val getId: ('k,'id) t -> ('k,'id) id
448+
(** [getId s0]
449+
450+
{b Advanced usage only}
451+
452+
@return the identity of [s0]
453+
*)
454+
224455
val packIdData: id:('k, 'id) id -> data:('k, 'id) Belt_SetDict.t -> ('k, 'id) t
456+
(** [packIdData ~id ~data]
457+
458+
{b Advanced usage only}
459+
460+
@return the packed collection
461+
*)
225462

‎jscomp/others/belt_SetInt.mli

+1-1
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
It is more efficient in general, the API is the same with {!Belt_Set} except its key type is fixed,
2828
and identity is not needed(using the built-in one)
2929
30-
{b See} {!Belt.MutableSet}
30+
{b See} {!Belt.Set}
3131
*)
3232

3333
# 35

‎jscomp/others/belt_SetString.mli

+1-1
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
It is more efficient in general, the API is the same with {!Belt_Set} except its key type is fixed,
2828
and identity is not needed(using the built-in one)
2929
30-
{b See} {!Belt.MutableSet}
30+
{b See} {!Belt.Set}
3131
*)
3232

3333
# 33

0 commit comments

Comments
 (0)