From d767be9a24e5939717677a7c9c43a46493c68664 Mon Sep 17 00:00:00 2001 From: Dmitry Zakharov Date: Mon, 11 Dec 2023 19:14:39 +0400 Subject: [PATCH] Fix Array module docstrings --- CHANGELOG.md | 4 +++ src/Core__Array.resi | 39 ++++++++++++-------------- src/Core__Dict.resi | 8 ++++-- test/ArrayTests.mjs | 66 ++++++++++++++++++++++++++++++-------------- test/ArrayTests.res | 3 ++ 5 files changed, 75 insertions(+), 45 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 28b4893b..6c1e4802 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ - Add `Dict.getUnsafe` https://github.com/rescript-association/rescript-core/pull/167 +### Documentation + +- Fix docstring for `Array.getUnsafe` and `Array.filterMap` https://github.com/rescript-association/rescript-core/pull/168 + ## 0.6.0 ### API changes diff --git a/src/Core__Array.resi b/src/Core__Array.resi index d1a1c149..15b23f4c 100644 --- a/src/Core__Array.resi +++ b/src/Core__Array.resi @@ -699,9 +699,9 @@ Console.log(mappedArray) // ["Hello at position 0", "Hi at position 1", "Good by external mapWithIndex: (array<'a>, ('a, int) => 'b) => array<'b> = "map" /** - `reduce(xs, f, init)` + `reduce(xs, fn, init)` - 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. + 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. ```res example 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" let reduce: (array<'a>, 'b, ('b, 'a) => 'b) => 'b /** - `reduceWithIndex(xs, f, init)` + `reduceWithIndex(xs, fn, init)` - 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. + 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. ```res example 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 let reduceWithIndex: (array<'a>, 'b, ('b, 'a, int) => 'b) => 'b /** - `reduceRight(xs, f, init)` + `reduceRight(xs, fn, init)` - Works like `Array.reduce`; except that function `f` is applied to each item of `xs` from the last back to the first. + Works like `Array.reduce`; except that function `fn` is applied to each item of `xs` from the last back to the first. ```res example 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 let array = ["Hello", "Hi", "Good bye"] array->Array.get(0) == Some("Hello") // true +array->Array.get(3) == None // true ``` */ @get_index @@ -811,21 +812,18 @@ external set: (array<'a>, int, 'a) => unit = "" /** `getUnsafe(array, index)` returns the element at `index` of `array`. -This is _unsafe_, meaning it will fail with an exception if `index` does not exist in `array`. +This is _unsafe_, meaning it will return `undefined` value if `index` does not exist in `array`. -## Exceptions - -- `Not_found`: If the provided `index` does not exist in `array`. +Use `Array.getUnsafe` only when you are sure the `index` exists (i.e. when using for-loop). ## Examples ```rescript -let array = ["Hello", "Hi", "Good bye"] - -Console.log(array->Array.getUnsafe(0)) // "Hello" -Console.log(array->Array.getUnsafe(3)) // Fails and raises exception +for index in 0 to array->Array.length - 1 { + let value = array->Array.getUnsafe(index) + Console.log(value) +} ``` */ -@raises(Not_found) external getUnsafe: (array<'a>, int) => 'a = "%array_unsafe_get" /** @@ -882,9 +880,9 @@ Console.log(someArray) // ["h1", "hello"]. Original unchanged external toReversed: array<'a> => array<'a> = "toReversed" /** -`get(array, index)` returns the element at `index` of `array`. +`filterMap(array, fn)` -Returns `None` if the index does not exist in the array. Equivalent to doing `array[index]` in JavaScript. +Calls `fn` for each element and returns a new array containing results of the `fn` calls which are not `None`. ## Examples ```rescript @@ -897,8 +895,7 @@ Console.log( | _ => None } ), -) -// [5] +) // [5] ``` */ let filterMap: (array<'a>, 'a => option<'b>) => array<'b> @@ -968,9 +965,9 @@ Console.log( external flatMap: (array<'a>, 'a => array<'b>) => array<'b> = "flatMap" /** - `findMap(arr, f)` + `findMap(arr, fn)` - Calls `f` for each element and returns the first value from `f` that is `Some(_)`. + Calls `fn` for each element and returns the first value from `fn` that is `Some(_)`. Otherwise returns `None` ```res example diff --git a/src/Core__Dict.resi b/src/Core__Dict.resi index ec5f1132..e3ac21f4 100644 --- a/src/Core__Dict.resi +++ b/src/Core__Dict.resi @@ -9,13 +9,15 @@ Type representing a dictionary of value `'a`. type t<'a> = Js.Dict.t<'a> /** -Returns the value at the provided key. Assumes the value always exists. -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). +`getUnsafe(dict, key)` Returns the `value` at the provided `key`. + +This is _unsafe_, meaning it will return `undefined` value if `key` does not exist in `dict`. + +Use `Dict.getUnsafe` only when you are sure the key exists (i.e. when iterating `Dict.keys` result). ## Examples ```rescript let keys = dict->Dict.keys - keys->Array.forEach(key => { let value = dict->Dict.getUnsafe(key) Console.log(value) diff --git a/test/ArrayTests.mjs b/test/ArrayTests.mjs index 1b13a37e..1d1d40e2 100644 --- a/test/ArrayTests.mjs +++ b/test/ArrayTests.mjs @@ -24,10 +24,34 @@ Test.run([ 7 ]); +Test.run([ + [ + "ArrayTests.res", + 7, + 20, + 42 + ], + "getUnsafe - existing" + ], 1, eq, 1); + Test.run([ [ "ArrayTests.res", 8, + 20, + 41 + ], + "getUnsafe - missing" + ], [ + 0, + 1, + 2 + ][10], eq, undefined); + +Test.run([ + [ + "ArrayTests.res", + 11, 13, 30 ], @@ -47,7 +71,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 14, + 17, 20, 28 ], @@ -70,7 +94,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 15, + 18, 20, 36 ], @@ -80,7 +104,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 18, + 21, 13, 30 ], @@ -108,7 +132,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 24, + 27, 13, 38 ], @@ -123,7 +147,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 31, + 34, 13, 26 ], @@ -146,7 +170,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 36, + 39, 20, 41 ], @@ -156,7 +180,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 39, + 42, 13, 35 ], @@ -184,7 +208,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 45, + 48, 13, 38 ], @@ -199,7 +223,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 51, + 54, 20, 41 ], @@ -219,7 +243,7 @@ var arr = [ Test.run([ [ "ArrayTests.res", - 54, + 57, 13, 31 ], @@ -229,7 +253,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 65, + 68, 13, 24 ], @@ -255,7 +279,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 70, + 73, 20, 42 ], @@ -274,7 +298,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 72, + 75, 13, 32 ], @@ -289,7 +313,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 78, + 81, 20, 30 ], @@ -306,7 +330,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 80, + 83, 13, 34 ], @@ -324,7 +348,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 85, + 88, 20, 41 ], @@ -338,7 +362,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 86, + 89, 20, 38 ], @@ -348,7 +372,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 89, + 92, 13, 22 ], @@ -370,7 +394,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 94, + 97, 20, 40 ], @@ -389,7 +413,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 96, + 99, 13, 30 ], @@ -404,7 +428,7 @@ Test.run([ Test.run([ [ "ArrayTests.res", - 103, + 106, 13, 27 ], diff --git a/test/ArrayTests.res b/test/ArrayTests.res index afaa44fd..c18899dd 100644 --- a/test/ArrayTests.res +++ b/test/ArrayTests.res @@ -4,6 +4,9 @@ let eq = (a, b) => a == b Test.run(__POS_OF__("make"), Array.make(~length=6, 7), eq, [7, 7, 7, 7, 7, 7]) +Test.run(__POS_OF__("getUnsafe - existing"), [0, 1, 2]->Array.getUnsafe(1), eq, 1) +Test.run(__POS_OF__("getUnsafe - missing"), [0, 1, 2]->Array.getUnsafe(10), eq, %raw(`undefined`)) + Test.run( __POS_OF__("fromInitializer"), Array.fromInitializer(~length=7, i => i + 3),