Skip to content

Commit f5e3785

Browse files
DZakhDZakh
committed
Fix Array module docstrings
1 parent d5904bd commit f5e3785

File tree

5 files changed

+75
-45
lines changed

5 files changed

+75
-45
lines changed

‎CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44

55
- Add `Dict.getUnsafe` https://github.com/rescript-association/rescript-core/pull/167
66

7+
### Documentation
8+
9+
- Fix docstring for `Array.getUnsafe` and `Array.filterMap`
10+
711
## 0.6.0
812

913
### API changes

‎src/Core__Array.resi

Lines changed: 18 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -699,9 +699,9 @@ Console.log(mappedArray) // ["Hello at position 0", "Hi at position 1", "Good by
699699
external mapWithIndex: (array<'a>, ('a, int) => 'b) => array<'b> = "map"
700700

701701
/**
702-
`reduce(xs, f, init)`
702+
`reduce(xs, fn, init)`
703703

704-
Applies `f` to each element of `xs` from beginning to end. Function `f` has two parameters: the item from the list and an “accumulator”; which starts with a value of `init`. `reduce` returns the final value of the accumulator.
704+
Applies `fn` to each element of `xs` from beginning to end. Function `fn` has two parameters: the item from the list and an “accumulator”; which starts with a value of `init`. `reduce` returns the final value of the accumulator.
705705

706706
```res example
707707
Array.reduce([2, 3, 4], (a, b) => a + b, 1) == 10
@@ -712,9 +712,9 @@ external mapWithIndex: (array<'a>, ('a, int) => 'b) => array<'b> = "map"
712712
let reduce: (array<'a>, 'b, ('b, 'a) => 'b) => 'b
713713

714714
/**
715-
`reduceWithIndex(xs, f, init)`
715+
`reduceWithIndex(xs, fn, init)`
716716

717-
Applies `f` to each element of `xs` from beginning to end. Function `f` has three parameters: the item from the array and an “accumulator”, which starts with a value of `init` and the index of each element. `reduceWithIndex` returns the final value of the accumulator.
717+
Applies `fn` to each element of `xs` from beginning to end. Function `fn` has three parameters: the item from the array and an “accumulator”, which starts with a value of `init` and the index of each element. `reduceWithIndex` returns the final value of the accumulator.
718718

719719
```res example
720720
Array.reduceWithIndex([1, 2, 3, 4], (acc, x, i) => acc + x + i, 0) == 16
@@ -723,9 +723,9 @@ let reduce: (array<'a>, 'b, ('b, 'a) => 'b) => 'b
723723
let reduceWithIndex: (array<'a>, 'b, ('b, 'a, int) => 'b) => 'b
724724

725725
/**
726-
`reduceRight(xs, f, init)`
726+
`reduceRight(xs, fn, init)`
727727

728-
Works like `Array.reduce`; except that function `f` is applied to each item of `xs` from the last back to the first.
728+
Works like `Array.reduce`; except that function `fn` is applied to each item of `xs` from the last back to the first.
729729

730730
```res example
731731
Array.reduceRight(["a", "b", "c", "d"], (a, b) => a ++ b, "") == "dcba"
@@ -784,6 +784,7 @@ Returns `None` if the index does not exist in the array. Equivalent to doing `ar
784784
let array = ["Hello", "Hi", "Good bye"]
785785

786786
array->Array.get(0) == Some("Hello") // true
787+
array->Array.get(3) == None // true
787788
```
788789
*/
789790
@get_index
@@ -811,21 +812,18 @@ external set: (array<'a>, int, 'a) => unit = ""
811812
/**
812813
`getUnsafe(array, index)` returns the element at `index` of `array`.
813814

814-
This is _unsafe_, meaning it will fail with an exception if `index` does not exist in `array`.
815+
This is _unsafe_, meaning it will return `undefined` value if `index` does not exist in `array`.
815816

816-
## Exceptions
817-
818-
- `Not_found`: If the provided `index` does not exist in `array`.
817+
Use `Array.getUnsafe` only when you are sure the `index` exists (i.e. when using for-loop).
819818

820819
## Examples
821820
```rescript
822-
let array = ["Hello", "Hi", "Good bye"]
823-
824-
Console.log(array->Array.getUnsafe(0)) // "Hello"
825-
Console.log(array->Array.getUnsafe(3)) // Fails and raises exception
821+
for index in 0 to array->Array.length - 1 {
822+
let value = array->Array.getUnsafe(index)
823+
Console.log(value)
824+
}
826825
```
827826
*/
828-
@raises(Not_found)
829827
external getUnsafe: (array<'a>, int) => 'a = "%array_unsafe_get"
830828

831829
/**
@@ -882,9 +880,9 @@ Console.log(someArray) // ["h1", "hello"]. Original unchanged
882880
external toReversed: array<'a> => array<'a> = "toReversed"
883881

884882
/**
885-
`get(array, index)` returns the element at `index` of `array`.
883+
`filterMap(array, fn)`
886884

887-
Returns `None` if the index does not exist in the array. Equivalent to doing `array[index]` in JavaScript.
885+
Calls `fn` for each element and returns a new array containing results of the `fn` calls which are not `None`.
888886

889887
## Examples
890888
```rescript
@@ -897,8 +895,7 @@ Console.log(
897895
| _ => None
898896
}
899897
),
900-
)
901-
// [5]
898+
) // [5]
902899
```
903900
*/
904901
let filterMap: (array<'a>, 'a => option<'b>) => array<'b>
@@ -968,9 +965,9 @@ Console.log(
968965
external flatMap: (array<'a>, 'a => array<'b>) => array<'b> = "flatMap"
969966

970967
/**
971-
`findMap(arr, f)`
968+
`findMap(arr, fn)`
972969

973-
Calls `f` for each element and returns the first value from `f` that is `Some(_)`.
970+
Calls `fn` for each element and returns the first value from `fn` that is `Some(_)`.
974971
Otherwise returns `None`
975972

976973
```res example

‎src/Core__Dict.resi

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,15 @@ Type representing a dictionary of value `'a`.
99
type t<'a> = Js.Dict.t<'a>
1010

1111
/**
12-
Returns the value at the provided key. Assumes the value always exists.
13-
Use `Dict.getUnsafe` only when you are sure the key exists (i.e. when having used the `Dict.keys` function to check that the key is valid).
12+
`getUnsafe(dict, key)` Returns the `value` at the provided `key`.
13+
14+
This is _unsafe_, meaning it will return `undefined` value if `key` does not exist in `dict`.
15+
16+
Use `Dict.getUnsafe` only when you are sure the key exists (i.e. when iterating `Dict.keys` result).
1417

1518
## Examples
1619
```rescript
1720
let keys = dict->Dict.keys
18-
1921
keys->Array.forEach(key => {
2022
let value = dict->Dict.getUnsafe(key)
2123
Console.log(value)

‎test/ArrayTests.mjs

Lines changed: 45 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,34 @@ Test.run([
2424
7
2525
]);
2626

27+
Test.run([
28+
[
29+
"ArrayTests.res",
30+
7,
31+
20,
32+
42
33+
],
34+
"getUnsafe - existing"
35+
], 1, eq, 1);
36+
2737
Test.run([
2838
[
2939
"ArrayTests.res",
3040
8,
41+
20,
42+
41
43+
],
44+
"getUnsafe - missing"
45+
], [
46+
0,
47+
1,
48+
2
49+
][10], eq, undefined);
50+
51+
Test.run([
52+
[
53+
"ArrayTests.res",
54+
11,
3155
13,
3256
30
3357
],
@@ -47,7 +71,7 @@ Test.run([
4771
Test.run([
4872
[
4973
"ArrayTests.res",
50-
14,
74+
17,
5175
20,
5276
28
5377
],
@@ -70,7 +94,7 @@ Test.run([
7094
Test.run([
7195
[
7296
"ArrayTests.res",
73-
15,
97+
18,
7498
20,
7599
36
76100
],
@@ -80,7 +104,7 @@ Test.run([
80104
Test.run([
81105
[
82106
"ArrayTests.res",
83-
18,
107+
21,
84108
13,
85109
30
86110
],
@@ -108,7 +132,7 @@ Test.run([
108132
Test.run([
109133
[
110134
"ArrayTests.res",
111-
24,
135+
27,
112136
13,
113137
38
114138
],
@@ -123,7 +147,7 @@ Test.run([
123147
Test.run([
124148
[
125149
"ArrayTests.res",
126-
31,
150+
34,
127151
13,
128152
26
129153
],
@@ -146,7 +170,7 @@ Test.run([
146170
Test.run([
147171
[
148172
"ArrayTests.res",
149-
36,
173+
39,
150174
20,
151175
41
152176
],
@@ -156,7 +180,7 @@ Test.run([
156180
Test.run([
157181
[
158182
"ArrayTests.res",
159-
39,
183+
42,
160184
13,
161185
35
162186
],
@@ -184,7 +208,7 @@ Test.run([
184208
Test.run([
185209
[
186210
"ArrayTests.res",
187-
45,
211+
48,
188212
13,
189213
38
190214
],
@@ -199,7 +223,7 @@ Test.run([
199223
Test.run([
200224
[
201225
"ArrayTests.res",
202-
51,
226+
54,
203227
20,
204228
41
205229
],
@@ -219,7 +243,7 @@ var arr = [
219243
Test.run([
220244
[
221245
"ArrayTests.res",
222-
54,
246+
57,
223247
13,
224248
31
225249
],
@@ -229,7 +253,7 @@ Test.run([
229253
Test.run([
230254
[
231255
"ArrayTests.res",
232-
65,
256+
68,
233257
13,
234258
24
235259
],
@@ -255,7 +279,7 @@ Test.run([
255279
Test.run([
256280
[
257281
"ArrayTests.res",
258-
70,
282+
73,
259283
20,
260284
42
261285
],
@@ -274,7 +298,7 @@ Test.run([
274298
Test.run([
275299
[
276300
"ArrayTests.res",
277-
72,
301+
75,
278302
13,
279303
32
280304
],
@@ -289,7 +313,7 @@ Test.run([
289313
Test.run([
290314
[
291315
"ArrayTests.res",
292-
78,
316+
81,
293317
20,
294318
30
295319
],
@@ -306,7 +330,7 @@ Test.run([
306330
Test.run([
307331
[
308332
"ArrayTests.res",
309-
80,
333+
83,
310334
13,
311335
34
312336
],
@@ -324,7 +348,7 @@ Test.run([
324348
Test.run([
325349
[
326350
"ArrayTests.res",
327-
85,
351+
88,
328352
20,
329353
41
330354
],
@@ -338,7 +362,7 @@ Test.run([
338362
Test.run([
339363
[
340364
"ArrayTests.res",
341-
86,
365+
89,
342366
20,
343367
38
344368
],
@@ -348,7 +372,7 @@ Test.run([
348372
Test.run([
349373
[
350374
"ArrayTests.res",
351-
89,
375+
92,
352376
13,
353377
22
354378
],
@@ -370,7 +394,7 @@ Test.run([
370394
Test.run([
371395
[
372396
"ArrayTests.res",
373-
94,
397+
97,
374398
20,
375399
40
376400
],
@@ -389,7 +413,7 @@ Test.run([
389413
Test.run([
390414
[
391415
"ArrayTests.res",
392-
96,
416+
99,
393417
13,
394418
30
395419
],
@@ -404,7 +428,7 @@ Test.run([
404428
Test.run([
405429
[
406430
"ArrayTests.res",
407-
103,
431+
106,
408432
13,
409433
27
410434
],

‎test/ArrayTests.res

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ let eq = (a, b) => a == b
44

55
Test.run(__POS_OF__("make"), Array.make(~length=6, 7), eq, [7, 7, 7, 7, 7, 7])
66

7+
Test.run(__POS_OF__("getUnsafe - existing"), [0, 1, 2]->Array.getUnsafe(1), eq, 1)
8+
Test.run(__POS_OF__("getUnsafe - missing"), [0, 1, 2]->Array.getUnsafe(10), eq, %raw(`undefined`))
9+
710
Test.run(
811
__POS_OF__("fromInitializer"),
912
Array.fromInitializer(~length=7, i => i + 3),

0 commit comments

Comments
 (0)