forked from rescript-lang/rescript
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathBelt.html
395 lines (326 loc) · 17.5 KB
/
Belt.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
<!doctype html>
<html>
<head>
<link rel="stylesheet" href="../api_static/tomorrow-night.css">
<link rel="stylesheet" href="../api_static/style.css" type="text/css">
<script src="../api_static//highlight.pack.js"></script>
<script src="../api_static//script.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
<meta charset="utf8">
<link rel="next" href="Belt_Array.html">
<title> Belt </title></head>
<body>
<nav class="module-index"><ul><li><a href="Belt.html">Belt</a></li>
<li><a href="Belt_Array.html">Belt_Array</a></li>
<li><a href="Belt_Debug.html">Belt_Debug</a></li>
<li><a href="Belt_HashMap.html">Belt_HashMap</a></li>
<li><a href="Belt_HashMapInt.html">Belt_HashMapInt</a></li>
<li><a href="Belt_HashMapString.html">Belt_HashMapString</a></li>
<li><a href="Belt_HashSet.html">Belt_HashSet</a></li>
<li><a href="Belt_HashSetInt.html">Belt_HashSetInt</a></li>
<li><a href="Belt_HashSetString.html">Belt_HashSetString</a></li>
<li><a href="Belt_Id.html">Belt_Id</a></li>
<li><a href="Belt_List.html">Belt_List</a></li>
<li><a href="Belt_Map.html">Belt_Map</a></li>
<li><a href="Belt_MapDict.html">Belt_MapDict</a></li>
<li><a href="Belt_MapInt.html">Belt_MapInt</a></li>
<li><a href="Belt_MapString.html">Belt_MapString</a></li>
<li><a href="Belt_MutableMap.html">Belt_MutableMap</a></li>
<li><a href="Belt_MutableMapInt.html">Belt_MutableMapInt</a></li>
<li><a href="Belt_MutableMapString.html">Belt_MutableMapString</a></li>
<li><a href="Belt_MutableQueue.html">Belt_MutableQueue</a></li>
<li><a href="Belt_MutableSet.html">Belt_MutableSet</a></li>
<li><a href="Belt_MutableSetInt.html">Belt_MutableSetInt</a></li>
<li><a href="Belt_MutableSetString.html">Belt_MutableSetString</a></li>
<li><a href="Belt_MutableStack.html">Belt_MutableStack</a></li>
<li><a href="Belt_Option.html">Belt_Option</a></li>
<li><a href="Belt_Range.html">Belt_Range</a></li>
<li><a href="Belt_Result.html">Belt_Result</a></li>
<li><a href="Belt_Set.html">Belt_Set</a></li>
<li><a href="Belt_SetDict.html">Belt_SetDict</a></li>
<li><a href="Belt_SetInt.html">Belt_SetInt</a></li>
<li><a href="Belt_SetString.html">Belt_SetString</a></li>
<li><a href="Belt_SortArray.html">Belt_SortArray</a></li>
<li><a href="Belt_SortArrayInt.html">Belt_SortArrayInt</a></li>
<li><a href="Belt_SortArrayString.html">Belt_SortArrayString</a></li>
<li><a href="Belt_internalAVLset.html">Belt_internalAVLset</a></li>
<li><a href="Belt_internalAVLtree.html">Belt_internalAVLtree</a></li>
<li><a href="Belt_internalBuckets.html">Belt_internalBuckets</a></li>
<li><a href="Belt_internalBucketsType.html">Belt_internalBucketsType</a></li>
<li><a href="Belt_internalMapInt.html">Belt_internalMapInt</a></li>
<li><a href="Belt_internalMapString.html">Belt_internalMapString</a></li>
<li><a href="Belt_internalMutableAVLMap.html">Belt_internalMutableAVLMap</a></li>
<li><a href="Belt_internalSetBuckets.html">Belt_internalSetBuckets</a></li>
<li><a href="Belt_internalSetInt.html">Belt_internalSetInt</a></li>
<li><a href="Belt_internalSetString.html">Belt_internalSetString</a></li>
<li><a href="Dom.html">Dom</a></li>
<li><a href="Dom_storage.html">Dom_storage</a></li>
<li><a href="Js.html">Js</a></li>
<li><a href="Js_array.html">Js_array</a></li>
<li><a href="Js_cast.html">Js_cast</a></li>
<li><a href="Js_console.html">Js_console</a></li>
<li><a href="Js_date.html">Js_date</a></li>
<li><a href="Js_dict.html">Js_dict</a></li>
<li><a href="Js_exn.html">Js_exn</a></li>
<li><a href="Js_float.html">Js_float</a></li>
<li><a href="Js_global.html">Js_global</a></li>
<li><a href="Js_int.html">Js_int</a></li>
<li><a href="Js_json.html">Js_json</a></li>
<li><a href="Js_list.html">Js_list</a></li>
<li><a href="Js_mapperRt.html">Js_mapperRt</a></li>
<li><a href="Js_math.html">Js_math</a></li>
<li><a href="Js_null.html">Js_null</a></li>
<li><a href="Js_null_undefined.html">Js_null_undefined</a></li>
<li><a href="Js_obj.html">Js_obj</a></li>
<li><a href="Js_option.html">Js_option</a></li>
<li><a href="Js_promise.html">Js_promise</a></li>
<li><a href="Js_re.html">Js_re</a></li>
<li><a href="Js_result.html">Js_result</a></li>
<li><a href="Js_string.html">Js_string</a></li>
<li><a href="Js_typed_array.html">Js_typed_array</a></li>
<li><a href="Js_types.html">Js_types</a></li>
<li><a href="Js_undefined.html">Js_undefined</a></li>
<li><a href="Js_vector.html">Js_vector</a></li>
<li><a href="Node.html">Node</a></li>
<li><a href="Node_buffer.html">Node_buffer</a></li>
<li><a href="Node_child_process.html">Node_child_process</a></li>
<li><a href="Node_fs.html">Node_fs</a></li>
<li><a href="Node_module.html">Node_module</a></li>
<li><a href="Node_path.html">Node_path</a></li>
<li><a href="Node_process.html">Node_process</a></li></ul></nav>
<div class="navbar"> <a class="up" href="index.html" title="Index">Up</a>
<a class="post" href="Belt_Array.html" title="Belt_Array">Next</a>
</div>
<h1>Module <a href="type_Belt.html">Belt</a></h1>
<pre><span class="keyword">module</span> Belt: <code class="code">sig</code> <a href="Belt.html">..</a> <code class="code">end</code></pre><div class="info module top">
<div class="not-examples">
A stdlib shipped with BuckleScript
<p>
This stdlib is still in <i>beta</i> but we encourage you to try it out and
give us feedback.
<p>
<b>Motivation </b>
<p>
The motivation for creating such library is to provide BuckleScript users a
better end-to-end user experience, since the original OCaml stdlib was not
written with JS in mind. Below is a list of areas this lib aims to
improve:
<OL>
<li>Consistency in name convention: camlCase, and arguments order</li>
<li>Exception thrown functions are all suffixed with <i>Exn</i>, e.g, <i>getExn</i></li>
<li>Better performance and smaller code size running on JS platform</li>
</OL>
<p>
<b>Name Convention</b>
<p>
For higher order functions, it will be suffixed <b>U</b> if it takes uncurried
callback.
<p>
<pre class="codepre"><code class="code"> val forEach : 'a t -> ('a -> unit) -> unit
val forEachU : 'a t -> ('a -> unit [@bs]) -> unit
</code></pre>
<p>
In general, uncurried version will be faster, but it may be less familiar to
people who have a background in functional programming.
<p>
<b>A special encoding for collection safety</b>
<p>
When we create a collection library for a custom data type we need a way to provide a comparator
function. Take <i>Set</i> for example, suppose its element type is a pair of ints,
it needs a custom <i>compare</i> function that takes two tuples and returns their order.
The <i>Set</i> could not just be typed as <code class="code"> Set.t (int * int) </code>, its customized <i>compare</i> function
needs to manifest itself in the signature, otherwise, if the user creates another
customized <i>compare</i> function, the two collection could mix which would result in runtime error.
<p>
The original OCaml stdlib solved the problem using <i>functor</i> which creates a big
closure at runtime and makes dead code elimination much harder.
We use a phantom type to solve the problem:
<p>
<pre class="codepre"><code class="code"> module Comparable1 = 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 mySet1 = Belt.Set.make ~id:(module Comparable1)
module Comparable2 = 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 mySet2 = Belt.Set.make ~id:(module Comparable2)
</code></pre>
<p>
Here, the compiler would infer <code class="code">mySet1</code> and <code class="code">mySet2</code> having different type, so
e.g. a `merge` operation that tries to merge these two sets will correctly fail.
<p>
<pre class="codepre"><code class="code"> val mySet1 : ((int * int), Comparable1.identity) t
val mySet2 : ((int * int), Comparable2.identity) t
</code></pre>
<p>
<code class="code">Comparable1.identity</code> and <code class="code">Comparable2.identity</code> are not the same using our encoding scheme.
<p>
<b>Collection Hierarchy</b>
<p>
In general, we provide a generic collection module, but also create specialized
modules for commonly used data type. Take <i>Belt.Set</i> for example, we provide:
<p>
<pre class="codepre"><code class="code"> Belt.Set
Belt.Set.Int
Belt.Set.String
</code></pre>
<p>
The specialized modules <i>Belt.Set.Int</i>, <i>Belt.Set.String</i> are in general more
efficient.
<p>
Currently, both <i>Belt_Set</i> and <i>Belt.Set</i> are accessible to users for some
technical reasons,
we <b>strongly recommend</b> users stick to qualified import, <i>Belt.Set</i>, we may hide
the internal, <i>i.e</i>, <i>Belt_Set</i> in the future<br>
</div>
</div>
<hr width="100%">
<pre><span class="keyword">module</span> <a href="Belt.Id.html">Id</a>: <code class="type"><a href="Belt_Id.html">Belt_Id</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.Id.html"><code class="code">Belt.Id</code></a>
<p>
Provide utilities to create identified comparators or hashes for
data structures used below.
<p>
It create a unique identifier per module of
functions so that different data structures with slightly different
comparison functions won't mix<br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.Array.html">Array</a>: <code class="type"><a href="Belt_Array.html">Belt_Array</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.Array.html"><code class="code">Belt.Array</code></a>
<p>
<b>mutable array</b>: Utilities functions<br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.SortArray.html">SortArray</a>: <code class="type"><a href="Belt_SortArray.html">Belt_SortArray</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.SortArray.html"><code class="code">Belt.SortArray</code></a>
<p>
The top level provides some generic sort related utilities.
<p>
It also has two specialized inner modules
<code class="code">Belt.SortArray.Int</code> and <code class="code">Belt.SortArray.String</code><br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.MutableQueue.html">MutableQueue</a>: <code class="type"><a href="Belt_MutableQueue.html">Belt_MutableQueue</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.MutableQueue.html"><code class="code">Belt.MutableQueue</code></a>
<p>
An FIFO(first in first out) queue data structure<br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.MutableStack.html">MutableStack</a>: <code class="type"><a href="Belt_MutableStack.html">Belt_MutableStack</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.MutableStack.html"><code class="code">Belt.MutableStack</code></a>
<p>
An FILO(first in last out) stack data structure<br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.List.html">List</a>: <code class="type"><a href="Belt_List.html">Belt_List</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.List.html"><code class="code">Belt.List</code></a>
<p>
Utilities for List data type<br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.Range.html">Range</a>: <code class="type"><a href="Belt_Range.html">Belt_Range</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.Range.html"><code class="code">Belt.Range</code></a>
<p>
Utilities for a closed range <code class="code">(from, start)</code><br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.Set.html">Set</a>: <code class="type"><a href="Belt_Set.html">Belt_Set</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.Set.html"><code class="code">Belt.Set</code></a>
<p>
The top level provides generic <b>immutable</b> set operations.
<p>
It also has three specialized inner modules
<code class="code">Belt.Set.Int</code>, <code class="code">Belt.Set.String</code> and
<p>
<code class="code">Belt.Set.Dict</code>: This module separates data from function
which is more verbose but slightly more efficient<br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.Map.html">Map</a>: <code class="type"><a href="Belt_Map.html">Belt_Map</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.Map.html"><code class="code">Belt.Map</code></a>,
<p>
The top level provides generic <b>immutable</b> map operations.
<p>
It also has three specialized inner modules
<code class="code">Belt.Map.Int</code>, <code class="code">Belt.Map.String</code> and
<p>
<code class="code">Belt.Map.Dict</code>: This module separates data from function
which is more verbose but slightly more efficient<br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.MutableSet.html">MutableSet</a>: <code class="type"><a href="Belt_MutableSet.html">Belt_MutableSet</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.MutableSet.html"><code class="code">Belt.MutableSet</code></a>
<p>
The top level provides generic <b>mutable</b> set operations.
<p>
It also has two specialized inner modules
<code class="code">Belt.MutableSet.Int</code> and <code class="code">Belt.MutableSet.String</code><br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.MutableMap.html">MutableMap</a>: <code class="type"><a href="Belt_MutableMap.html">Belt_MutableMap</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.MutableMap.html"><code class="code">Belt.MutableMap</code></a>
<p>
The top level provides generic <b>mutable</b> map operations.
<p>
It also has two specialized inner modules
<code class="code">Belt.MutableMap.Int</code> and <code class="code">Belt.MutableMap.String</code><br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.HashSet.html">HashSet</a>: <code class="type"><a href="Belt_HashSet.html">Belt_HashSet</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.HashSet.html"><code class="code">Belt.HashSet</code></a>
<p>
The top level provides generic <b>mutable</b> hash set operations.
<p>
It also has two specialized inner modules
<code class="code">Belt.HashSet.Int</code> and <code class="code">Belt.HashSet.String</code><br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.HashMap.html">HashMap</a>: <code class="type"><a href="Belt_HashMap.html">Belt_HashMap</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.HashMap.html"><code class="code">Belt.HashMap</code></a>
<p>
The top level provides generic <b>mutable</b> hash map operations.
<p>
It also has two specialized inner modules
<code class="code">Belt.HashMap.Int</code> and <code class="code">Belt.HashMap.String</code><br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.Option.html">Option</a>: <code class="type"><a href="Belt_Option.html">Belt_Option</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.Option.html"><code class="code">Belt.Option</code></a>
<p>
Utilities for option data type.<br>
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.Result.html">Result</a>: <code class="type"><a href="Belt_Result.html">Belt_Result</a></code></pre> <div class="info">
<div class="not-examples">
</div>
</div>
<pre><span class="keyword">module</span> <a href="Belt.Debug.html">Debug</a>: <code class="type"><a href="Belt_Debug.html">Belt_Debug</a></code></pre> <div class="info">
<div class="not-examples">
<a href="Belt.Debug.html"><code class="code">Belt.Debug</code></a>
<p>
Utilities for set up debugging<br>
</div>
</div> </body></html>