From 23d76e68dcb96087ea7dfbb55b7a4558676078c8 Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Tue, 28 Feb 2023 16:15:28 +0100 Subject: [PATCH 01/11] start working on Array docstrings --- src/Core__Array.resi | 221 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 209 insertions(+), 12 deletions(-) diff --git a/src/Core__Array.resi b/src/Core__Array.resi index 0bbb3984..745f4f79 100644 --- a/src/Core__Array.resi +++ b/src/Core__Array.resi @@ -29,7 +29,21 @@ let make: (~length: int, 'a) => array<'a> let fromInitializer: (~length: int, int => 'a) => array<'a> @val external isArray: 'a => bool = "Array.isArray" -@get external length: array<'a> => int = "length" + +/** +`length(array)` returns the `int` length (number of items) of the array. + +See [`Array.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length) on MDN. + +## Examples +```rescript +let someArray = ["hi", "hello"] + +Console.log(someArray->Array.length) // 2 +``` +*/ +@get +external length: array<'a> => int = "length" @send external copyAllWithin: (array<'a>, ~target: int) => array<'a> = "copyWithin" @send external copyWithinToEnd: (array<'a>, ~target: int, ~start: int) => array<'a> = "copyWithin" @@ -38,22 +52,205 @@ external copyWithin: (array<'a>, ~target: int, ~start: int, ~end: int) => array< @send external fillAllInPlace: (array<'a>, 'a) => unit = "fill" @send external fillInPlaceToEnd: (array<'a>, 'a, ~start: int) => unit = "fill" @send external fillInPlace: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill" -@send external pop: array<'a> => option<'a> = "pop" -@send external push: (array<'a>, 'a) => unit = "push" -@variadic @send external pushMany: (array<'a>, array<'a>) => unit = "push" -@send external reverseInPlace: array<'a> => unit = "reverse" -@send external shift: array<'a> => option<'a> = "shift" + +/** +`pop(array)` pops off the last item in the array, and returns it. + +Beware this will *mutate* the array. + +See [`Array.pop`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/pop) on MDN. + +## Examples +```rescript +let someArray = ["hi", "hello"] +let lastItem = someArray->Array.pop // "hello" + +Console.log(someArray) // ["hi"]. Notice last item is gone. +``` +*/ +@send +external pop: array<'a> => option<'a> = "pop" + +/** +`push(array, item)` pushes a new item to the end of the array. + +Beware this will *mutate* the array. + +See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) on MDN. + +## Examples +```rescript +let someArray = ["hi", "hello"] +someArray->Array.push("yay") + +Console.log(someArray) // ["hi", "hello", "yay"] +``` +*/ +@send +external push: (array<'a>, 'a) => unit = "push" + +/** +`pushMany(array, itemsArray)` pushes many new items to the end of the array. + +Beware this will *mutate* the array. + +See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) on MDN. + +## Examples +```rescript +let someArray = ["hi", "hello"] +someArray->Array.pushMany(["yay", "wehoo"]) + +Console.log(someArray) // ["hi", "hello", "yay", "wehoo"] +``` +*/ +@variadic +@send +external pushMany: (array<'a>, array<'a>) => unit = "push" + +/** +`reverse(array)` reverses the order of the items in the array. + +Beware this will *mutate* the array. + +See [`Array.reverse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) on MDN. + +## Examples +```rescript +let someArray = ["hi", "hello"] +someArray->Array.reverse + +Console.log(someArray) // ["hello", "h1"] +``` +*/ +@send +external reverseInPlace: array<'a> => unit = "reverse" + +/** +`shift(array)` removes the first item in the array, and returns it. + +Beware this will *mutate* the array. + +See [`Array.shift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/shift) on MDN. + +## Examples +```rescript +let someArray = ["hi", "hello"] +let lastItem = someArray->Array.shift // "hi" + +Console.log(someArray) // ["hello"]. Notice first item is gone. +``` +*/ +@send +external shift: array<'a> => option<'a> = "shift" let sort: (array<'a>, ('a, 'a) => int) => array<'a> @send external sortInPlace: (array<'a>, ('a, 'a) => int) => unit = "sort" @variadic @send external spliceInPlace: (array<'a>, ~start: int, ~remove: int, ~insert: array<'a>) => unit = "splice" -@send external unshift: (array<'a>, 'a) => unit = "unshift" -@variadic @send external unshiftMany: (array<'a>, array<'a>) => unit = "unshift" -@send external concat: (array<'a>, array<'a>) => array<'a> = "concat" -@variadic @send external concatMany: (array<'a>, array>) => array<'a> = "concat" -@send external flat: array> => array<'a> = "flat" -@send external includes: (array<'a>, 'a) => bool = "includes" + +/** +`unshift(array, item)` inserts a new item at the start of the array. + +Beware this will *mutate* the array. + +See [`Array.unshift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift) on MDN. + +## Examples +```rescript +let someArray = ["hi", "hello"] +someArray->Array.unshift("yay") + +Console.log(someArray) // ["yay", "hi", "hello"] +``` +*/ +@send +external unshift: (array<'a>, 'a) => unit = "unshift" + +/** +`unshiftMany(array, itemsArray)` inserts many new items to the start of the array. + +Beware this will *mutate* the array. + +See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift) on MDN. + +## Examples +```rescript +let someArray = ["hi", "hello"] +someArray->Array.unshiftMany(["yay", "wehoo"]) + +Console.log(someArray) // ["yay", "wehoo", "hi", "hello"] +``` +*/ +@variadic +@send +external unshiftMany: (array<'a>, array<'a>) => unit = "unshift" + +/** +`concat(array1, array2)` concatenates two arrays, creating a new array. + +See [`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) on MDN. + +## Examples +```rescript +let array1 = ["hi", "hello"] +let array2 = ["yay", "wehoo"] + +let someArray = array1->Array.concat(array2) + +Console.log(someArray) // ["hi", "hello", "yay", "wehoo"] +``` +*/ +@send +external concat: (array<'a>, array<'a>) => array<'a> = "concat" + +/** +`concatMany(array1, arrays)` concatenates array1 with several other arrays, creating a new array. + +See [`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) on MDN. + +## Examples +```rescript +let array1 = ["hi", "hello"] +let array2 = ["yay"] +let array3 = ["wehoo"] + +let someArray = array1->Array.concatMany([array2, array3]) + +Console.log(someArray) // ["hi", "hello", "yay", "wehoo"] +``` +*/ +@variadic +@send +external concatMany: (array<'a>, array>) => array<'a> = "concat" + +/** +`flat(arrays)` flattens the provided arrays into a single array. + +See [`Array.flat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat) on MDN. + +## Examples +```rescript +Console.log([[1], [2], [3, 4]]->Array.flat) // [1, 2, 3, 4] +``` +*/ +@send +external flat: array> => array<'a> = "flat" + +/** +`includes(array, item)` checks whether `array` includes `item`, by doing a [strict check for equality](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality). + +See [`Array.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes) on MDN. + +## Examples +```rescript +Console.log([1, 2]->Array.includes(1)) // true +Console.log([1, 2]->Array.includes(3)) // false +Console.log([{"language": "ReScript"}]->Array.includes({"language": "ReScript"})) // false, because of strict equality +``` +*/ +@send +external includes: (array<'a>, 'a) => bool = "includes" @send external indexOf: (array<'a>, 'a) => int = "indexOf" let indexOfOpt: (array<'a>, 'a) => option @send external indexOfFrom: (array<'a>, 'a, int) => int = "indexOf" From c35ec2037412b0d475984188a8fa0f0db9b1cce5 Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Tue, 28 Feb 2023 16:28:21 +0100 Subject: [PATCH 02/11] docs for indexOf and includes --- src/Core__Array.resi | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/src/Core__Array.resi b/src/Core__Array.resi index 745f4f79..d17d83e3 100644 --- a/src/Core__Array.resi +++ b/src/Core__Array.resi @@ -251,7 +251,36 @@ Console.log([{"language": "ReScript"}]->Array.includes({"language": "ReScript"}) */ @send external includes: (array<'a>, 'a) => bool = "includes" -@send external indexOf: (array<'a>, 'a) => int = "indexOf" + +/** +`indexOf(array, item)` returns the index of the provided `item` in `array`. Uses [strict check for equality](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) when comparing items. + +Returns `-1` if the item doesn not exist. Check out `Array.indexOfOpt` for a version that returns `None` instead of `-1` if the item does not exist. + +See [`Array.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf) on MDN. + +## Examples +```rescript +Console.log([1, 2]->Array.indexOf(2)) // 1 +Console.log([1, 2]->Array.indexOf(3)) // -1 +Console.log([{"language": "ReScript"}]->Array.indexOf({"language": "ReScript"})) // -1, because of strict equality +``` +*/ +@send +external indexOf: (array<'a>, 'a) => int = "indexOf" + +/** +`indexOfOpt(array, item)` returns an option of the index of the provided `item` in `array`. Uses [strict check for equality](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) when comparing items. + +See [`Array.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf) on MDN. + +## Examples +```rescript +Console.log([1, 2]->Array.indexOfOpt(2)) // Some(1) +Console.log([1, 2]->Array.indexOfOpt(3)) // None +Console.log([{"language": "ReScript"}]->Array.indexOfOpt({"language": "ReScript"})) // None, because of strict equality +``` +*/ let indexOfOpt: (array<'a>, 'a) => option @send external indexOfFrom: (array<'a>, 'a, int) => int = "indexOf" @send external joinWith: (array<'a>, string) => string = "join" From a849ac1499a8935f2ee671d256e260d3f6678363 Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Mon, 6 Mar 2023 18:50:13 +0100 Subject: [PATCH 03/11] remove Array.fromIterator + friends in favor of specialized functions in Iterator --- src/Core__Array.res | 3 --- src/Core__Array.resi | 2 -- src/Core__Iterator.res | 3 ++- src/Core__Iterator.resi | 25 +++++++++++++++++++++++-- test/TempTests.res | 2 +- 5 files changed, 26 insertions(+), 9 deletions(-) diff --git a/src/Core__Array.res b/src/Core__Array.res index a1c2e853..2a63e63b 100644 --- a/src/Core__Array.res +++ b/src/Core__Array.res @@ -10,9 +10,6 @@ external setUnsafe: (array<'a>, int, 'a) => unit = "%array_unsafe_set" @val external fromArrayLikeWithMap: (Js.Array2.array_like<'a>, 'a => 'b) => array<'b> = "Array.from" -@val external fromIterator: Core__Iterator.t<'a> => array<'a> = "Array.from" -@val external fromIteratorWithMap: (Core__Iterator.t<'a>, 'a => 'b) => array<'b> = "Array.from" - @send external fillAllInPlace: (array<'a>, 'a) => unit = "fill" @send external fillInPlaceToEnd: (array<'a>, 'a, ~start: int) => unit = "fill" diff --git a/src/Core__Array.resi b/src/Core__Array.resi index d17d83e3..6f93397f 100644 --- a/src/Core__Array.resi +++ b/src/Core__Array.resi @@ -3,8 +3,6 @@ @val external fromArrayLike: Js.Array2.array_like<'a> => array<'a> = "Array.from" @val external fromArrayLikeWithMap: (Js.Array2.array_like<'a>, 'a => 'b) => array<'b> = "Array.from" -@val external fromIterator: Core__Iterator.t<'a> => array<'a> = "Array.from" -@val external fromIteratorWithMap: (Core__Iterator.t<'a>, 'a => 'b) => array<'b> = "Array.from" /** `make(~length, init)` diff --git a/src/Core__Iterator.res b/src/Core__Iterator.res index 161973ad..ef3aae07 100644 --- a/src/Core__Iterator.res +++ b/src/Core__Iterator.res @@ -6,4 +6,5 @@ type value<'a> = { } @send external next: t<'a> => value<'a> = "next" -@scope("Array") external toArray: t<'a> => array<'a> = "from" +external toArray: t<'a> => array<'a> = "Array.from" +external toArrayWithMapper: (t<'a>, 'a => 'b) => array<'b> = "Array.from" diff --git a/src/Core__Iterator.resi b/src/Core__Iterator.resi index c22c336b..36a9fed3 100644 --- a/src/Core__Iterator.resi +++ b/src/Core__Iterator.resi @@ -55,5 +55,26 @@ let mapKeysAsArray = map->Map.keys->Iterator.toArray Console.log(mapKeysAsArray) // Logs ["someKey", "someKey2"] to the console. ``` */ -@scope("Array") -external toArray: t<'a> => array<'a> = "from" +external toArray: t<'a> => array<'a> = "Array.from" + +/** +Turns an iterator into an array of the remaining values, applying the provided mapper function on each item. +Remember that each invocation of `next` of an iterator consumes a value. `Iterator.toArrayWithMapper` will consume all remaining values of the iterator and return them in an array to you. + +See [iterator protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on MDN. + +## Examples +```rescript +let map = Map.make() +map->Map.set("someKey", "someValue") +map->Map.set("someKey2", "someValue2") + +// `Map.keys` returns all keys of the map as an iterator. +let mapKeysAsArray = map + ->Map.keys + ->Iterator.toArrayWithMapper(key => key->String.length) + +Console.log(mapKeysAsArray) // Logs [7, 8] to the console. +``` +*/ +external toArrayWithMapper: (t<'a>, 'a => 'b) => array<'b> = "Array.from" diff --git a/test/TempTests.res b/test/TempTests.res index 82784cea..f7bf9d3b 100644 --- a/test/TempTests.res +++ b/test/TempTests.res @@ -171,7 +171,7 @@ Console.info("Symbol") Console.info("---") let x = Symbol.getFor("Foo") Console.log(x) -let array: array = Array.fromIterator(String.getSymbolUnsafe("foo", Symbol.iterator)(.)) +let array: array = String.getSymbolUnsafe("foo", Symbol.iterator)(.)->Iterator.toArray Console.log(array) Console.info("") From ef4719b867a2aae34396382005c0f1e7cf785096 Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Mon, 6 Mar 2023 20:58:57 +0100 Subject: [PATCH 04/11] more array docstrings --- src/Core__Array.resi | 155 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 146 insertions(+), 9 deletions(-) diff --git a/src/Core__Array.resi b/src/Core__Array.resi index 6f93397f..4257f8ab 100644 --- a/src/Core__Array.resi +++ b/src/Core__Array.resi @@ -47,9 +47,60 @@ external length: array<'a> => int = "length" external copyWithinToEnd: (array<'a>, ~target: int, ~start: int) => array<'a> = "copyWithin" @send external copyWithin: (array<'a>, ~target: int, ~start: int, ~end: int) => array<'a> = "copyWithin" -@send external fillAllInPlace: (array<'a>, 'a) => unit = "fill" -@send external fillInPlaceToEnd: (array<'a>, 'a, ~start: int) => unit = "fill" -@send external fillInPlace: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill" + +/** +`fillAllInPlace(array, value)` fills the entire provided `array` with the provided `value`. + +Beware this will *mutate* the array. + +See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN. + +## Examples +```rescript +let myArray = [1, 2, 3, 4] +myArray->Array.fillAllInPlace(9) + +Console.log(myArray) // [9, 9, 9, 9] +``` +*/ +@send +external fillAllInPlace: (array<'a>, 'a) => unit = "fill" + +/** +`fillInPlaceToEnd` fills the entire provided `array` with the provided `value`, starting from the index provided to `start`. + +Beware this will *mutate* the array. + +See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN. + +## Examples +```rescript +let myArray = [1, 2, 3, 4] +myArray->Array.fillInPlaceToEnd(9, ~start=1) + +Console.log(myArray) // [1, 9, 9, 9] +``` +*/ +@send +external fillInPlaceToEnd: (array<'a>, 'a, ~start: int) => unit = "fill" + +/** +`fillInPlace` fills the entire provided `array` with the provided `value`, starting from the index provided to `start`, going to the index provided to `end`. + +Beware this will *mutate* the array. + +See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN. + +## Examples +```rescript +let myArray = [1, 2, 3, 4] +myArray->Array.fillInPlace(9, ~start=1, ~end=2) + +Console.log(myArray) // [1, 9, 9, 4] +``` +*/ +@send +external fillInPlace: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill" /** `pop(array)` pops off the last item in the array, and returns it. @@ -107,7 +158,7 @@ Console.log(someArray) // ["hi", "hello", "yay", "wehoo"] external pushMany: (array<'a>, array<'a>) => unit = "push" /** -`reverse(array)` reverses the order of the items in the array. +`reverseInPlace(array)` reverses the order of the items in the array. Beware this will *mutate* the array. @@ -116,7 +167,7 @@ See [`Array.reverse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Re ## Examples ```rescript let someArray = ["hi", "hello"] -someArray->Array.reverse +someArray->Array.reverseInPlace Console.log(someArray) // ["hello", "h1"] ``` @@ -141,8 +192,39 @@ Console.log(someArray) // ["hello"]. Notice first item is gone. */ @send external shift: array<'a> => option<'a> = "shift" + +/** +`sort(array, comparator)` returns a new, sorted array from `array`, using the provided `comparator` function. + +See [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) on MDN. + +## Examples +```rescript +let someArray = [3, 2, 1] +let sortedArray = someArray->Array.sort((a, b) => a > b ? 1 : -1) + +Console.log(sortedArray) // [1, 2, 3] +``` +*/ let sort: (array<'a>, ('a, 'a) => int) => array<'a> -@send external sortInPlace: (array<'a>, ('a, 'a) => int) => unit = "sort" + +/** +`sortInPlace(array, comparator)` sorts the provided `array` using the provided `comparator` function. + +Beware this will *mutate* the array. + +See [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) on MDN. + +## Examples +```rescript +let someArray = [3, 2, 1] +someArray->Array.sortInPlace((a, b) => a > b ? 1 : -1) + +Console.log(someArray) // [1, 2, 3] +``` +*/ +@send +external sortInPlace: (array<'a>, ('a, 'a) => int) => unit = "sort" @variadic @send external spliceInPlace: (array<'a>, ~start: int, ~remove: int, ~insert: array<'a>) => unit = "splice" @@ -285,9 +367,50 @@ let indexOfOpt: (array<'a>, 'a) => option @send external lastIndexOf: (array<'a>, 'a) => int = "lastIndexOf" let lastIndexOfOpt: (array<'a>, 'a) => option @send external lastIndexOfFrom: (array<'a>, 'a, int) => int = "lastIndexOf" -@send external slice: (array<'a>, ~start: int, ~end: int) => array<'a> = "slice" -@send external sliceToEnd: (array<'a>, ~start: int) => array<'a> = "slice" -@send external copy: array<'a> => array<'a> = "slice" + +/** +`slice(array, start, end)` creates a new array from the provided `array`, with all items from `array` starting from `start`, stopping _before_ `end` (`end` is not included). + +See [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) on MDN. + +## Examples +```rescript +let myArray = [1, 2, 3, 4] + +Console.log(myArray->Array.slice(~start=1, ~end=3)) // [2, 3] +``` +*/ +@send +external slice: (array<'a>, ~start: int, ~end: int) => array<'a> = "slice" + +/** +`sliceToEnd(array, start)` creates a new array from the provided `array`, with all items from `array` starting from `start`. + +See [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) on MDN. + +## Examples +```rescript +let myArray = [1, 2, 3, 4] + +Console.log(myArray->Array.sliceToEnd(~start=1)) // [2, 3, 4] +``` +*/ +@send +external sliceToEnd: (array<'a>, ~start: int) => array<'a> = "slice" +/** +`copy(array)` makes a shallow copy of the provided `array`. + +## Examples +```rescript +let myArray = [1, 2, 3] +let copyOfMyArray = myArray->Array.copy + +Console.log(copyOfMyArray) // [1, 2, 3] +Console.log(myArray === copyOfMyArray) // false +``` +*/ +@send +external copy: array<'a> => array<'a> = "slice" @send external toString: array<'a> => string = "toString" @send external toLocaleString: array<'a> => string = "toLocaleString" @send external every: (array<'a>, 'a => bool) => bool = "every" @@ -359,6 +482,20 @@ let reduceRightWithIndex: (array<'a>, 'b, ('b, 'a, int) => 'b) => 'b external getUnsafe: (array<'a>, int) => 'a = "%array_unsafe_get" external setUnsafe: (array<'a>, int, 'a) => unit = "%array_unsafe_set" let findIndexOpt: (array<'a>, 'a => bool) => option + +/** +`reverse(array)` creates a new array with all items from `array` in reversed order. + +See [`Array.reverse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) on MDN. + +## Examples +```rescript +let someArray = ["hi", "hello"] +let reversed = someArray->Array.reverse + +Console.log(reversed) // ["hello", "h1"] +``` +*/ let reverse: array<'a> => array<'a> let filterMap: (array<'a>, 'a => option<'b>) => array<'b> From 1283825d7788e7639ef790e89f8cff0ecf4b3d0c Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Wed, 8 Mar 2023 08:43:11 +0100 Subject: [PATCH 05/11] changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e8490e2..ace9b15f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,7 @@ - Add `panic`/`Error.panic`. https://github.com/rescript-association/rescript-core/pull/72 - The globally available `null` value now originates from `Nullable` and not `Null`, just like the globally available `undefined` value does. https://github.com/rescript-association/rescript-core/pull/88 - Add `Int.range` and `Int.rangeWithOptions`, https://github.com/rescript-association/rescript-core/pull/52 +- Remove `Array.fromIterator` and `Array.fromIteratorWithMap`. The same functions exist in `Iterator` as `Iterator.fromArray` and `Iterator.fromArrayWithMapper`. https://github.com/rescript-association/rescript-core/pull/78 ### Documentation From 0dbf4b38513c9aec5875a9e84906ed960eb9a259 Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Wed, 8 Mar 2023 08:44:39 +0100 Subject: [PATCH 06/11] remove unsafe Array.from functions --- CHANGELOG.md | 1 + src/Core__Array.res | 3 --- src/Core__Array.resi | 2 -- 3 files changed, 1 insertion(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ace9b15f..2d43731f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,7 @@ - The globally available `null` value now originates from `Nullable` and not `Null`, just like the globally available `undefined` value does. https://github.com/rescript-association/rescript-core/pull/88 - Add `Int.range` and `Int.rangeWithOptions`, https://github.com/rescript-association/rescript-core/pull/52 - Remove `Array.fromIterator` and `Array.fromIteratorWithMap`. The same functions exist in `Iterator` as `Iterator.fromArray` and `Iterator.fromArrayWithMapper`. https://github.com/rescript-association/rescript-core/pull/78 +- Remove unsafe `Array.from` and `Array.fromWithMap`. https://github.com/rescript-association/rescript-core/pull/78 ### Documentation diff --git a/src/Core__Array.res b/src/Core__Array.res index 2a63e63b..cd1bda48 100644 --- a/src/Core__Array.res +++ b/src/Core__Array.res @@ -3,9 +3,6 @@ external getUnsafe: (array<'a>, int) => 'a = "%array_unsafe_get" external setUnsafe: (array<'a>, int, 'a) => unit = "%array_unsafe_set" -@val external from: 'a => array<'b> = "Array.from" -@val external fromWithMap: ('a, 'b => 'c) => array<'c> = "Array.from" - @val external fromArrayLike: Js.Array2.array_like<'a> => array<'a> = "Array.from" @val external fromArrayLikeWithMap: (Js.Array2.array_like<'a>, 'a => 'b) => array<'b> = "Array.from" diff --git a/src/Core__Array.resi b/src/Core__Array.resi index 4257f8ab..5f6e5344 100644 --- a/src/Core__Array.resi +++ b/src/Core__Array.resi @@ -1,5 +1,3 @@ -@val external from: 'a => array<'b> = "Array.from" -@val external fromWithMap: ('a, 'b => 'c) => array<'c> = "Array.from" @val external fromArrayLike: Js.Array2.array_like<'a> => array<'a> = "Array.from" @val external fromArrayLikeWithMap: (Js.Array2.array_like<'a>, 'a => 'b) => array<'b> = "Array.from" From ebd09d6a9c7305d3bfa53b5d5727ef78267534a9 Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Wed, 8 Mar 2023 11:17:01 +0100 Subject: [PATCH 07/11] more array docstrings --- src/Core__Array.res | 1 - src/Core__Array.resi | 426 +++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 407 insertions(+), 20 deletions(-) diff --git a/src/Core__Array.res b/src/Core__Array.res index cd1bda48..f329780c 100644 --- a/src/Core__Array.res +++ b/src/Core__Array.res @@ -101,7 +101,6 @@ let sort = (arr, cmp) => { } @send external toString: array<'a> => string = "toString" -@send external toLocaleString: array<'a> => string = "toLocaleString" @send external every: (array<'a>, 'a => bool) => bool = "every" @send external everyWithIndex: (array<'a>, ('a, int) => bool) => bool = "every" diff --git a/src/Core__Array.resi b/src/Core__Array.resi index 5f6e5344..59d813d5 100644 --- a/src/Core__Array.resi +++ b/src/Core__Array.resi @@ -1,4 +1,7 @@ +// TODO: Docs @val external fromArrayLike: Js.Array2.array_like<'a> => array<'a> = "Array.from" + +// TODO: Docs @val external fromArrayLikeWithMap: (Js.Array2.array_like<'a>, 'a => 'b) => array<'b> = "Array.from" @@ -40,9 +43,15 @@ Console.log(someArray->Array.length) // 2 */ @get external length: array<'a> => int = "length" + +// TODO: Docs @send external copyAllWithin: (array<'a>, ~target: int) => array<'a> = "copyWithin" + +// TODO: Docs @send external copyWithinToEnd: (array<'a>, ~target: int, ~start: int) => array<'a> = "copyWithin" + +// TODO: Docs @send external copyWithin: (array<'a>, ~target: int, ~start: int, ~end: int) => array<'a> = "copyWithin" @@ -409,20 +418,232 @@ Console.log(myArray === copyOfMyArray) // false */ @send external copy: array<'a> => array<'a> = "slice" -@send external toString: array<'a> => string = "toString" -@send external toLocaleString: array<'a> => string = "toLocaleString" -@send external every: (array<'a>, 'a => bool) => bool = "every" -@send external everyWithIndex: (array<'a>, ('a, int) => bool) => bool = "every" -@send external filter: (array<'a>, 'a => bool) => array<'a> = "filter" -@send external filterWithIndex: (array<'a>, ('a, int) => bool) => array<'a> = "filter" -@send external find: (array<'a>, 'a => bool) => option<'a> = "find" -@send external findWithIndex: (array<'a>, ('a, int) => bool) => option<'a> = "find" -@send external findIndex: (array<'a>, 'a => bool) => int = "findIndex" -@send external findIndexWithIndex: (array<'a>, ('a, int) => bool) => int = "findIndex" -@send external forEach: (array<'a>, 'a => unit) => unit = "forEach" -@send external forEachWithIndex: (array<'a>, ('a, int) => unit) => unit = "forEach" -@send external map: (array<'a>, 'a => 'b) => array<'b> = "map" -@send external mapWithIndex: (array<'a>, ('a, int) => 'b) => array<'b> = "map" + +/** +`toString(array)` stringifies the provided `array`, by running `toString` on all of the array elements and joining them with ",". + +See [`Array.toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString) on MDN. + +## Examples +```rescript +let array = [1, 2, 3, 4] + +Console.log(array->Array.toString) // "1,2,3,4" +``` +*/ +@send +external toString: array<'a> => string = "toString" + +/** +`every(array, checker)` returns true if all items in `array` returns true when running the provided `checker` function. + +See [`Array.every`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) on MDN. + +## Examples +```rescript +let array = [1, 2, 3, 4] + +Console.log(array->Array.every(num => num > 4)) // true +Console.log(array->Array.every(num => num === 1)) // false +``` +*/ +@send +external every: (array<'a>, 'a => bool) => bool = "every" + +/** +`everyWithIndex(array, checker)` returns true if all items in `array` returns true when running the provided `checker` function. + +See [`Array.every`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) on MDN. + +## Examples +```rescript +let array = [1, 2, 3, 4] + +Console.log(array->Array.everyWithIndex((num, index) => index < 2 && num <= 2)) // true +Console.log(array->Array.everyWithIndex((num, index) => index < 2 && num >= 2)) // false +``` +*/ +@send +external everyWithIndex: (array<'a>, ('a, int) => bool) => bool = "every" + +/** +`filter(array, checker)` returns a new array containing all elements from `array` for which the provided `checker` function returns true. + +See [`Array.filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) on MDN. + +## Examples +```rescript +let array = [1, 2, 3, 4] + +Console.log(array->Array.filter(num => num > 2)) // [3, 4] +``` +*/ +@send +external filter: (array<'a>, 'a => bool) => array<'a> = "filter" + +/** +`filterWithIndex(array, checker)` returns a new array containing all elements from `array` for which the provided `checker` function returns true. + +See [`Array.filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) on MDN. + +## Examples +```rescript +let array = [1, 2, 3, 4] + +Console.log(array->Array.filterWithIndex((num, index) => index === 0 || num === 2)) // [1, 2] +``` +*/ +@send +external filterWithIndex: (array<'a>, ('a, int) => bool) => array<'a> = "filter" + +/** +`find(array, checker)` returns the first element of `array` where the provided `checker` function returns true. + +See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN. + +## Examples +```rescript +type languages = ReScript | TypeScript | JavaScript + +let array = [ReScript, TypeScript, JavaScript] + +switch array->Array.find(item => item == ReScript) { +| None => Console.log("No item...") +| Some(_) => Console.log("Yay, ReScript!") +} +``` +*/ +@send +external find: (array<'a>, 'a => bool) => option<'a> = "find" + +/** +`findWithIndex(array, checker)` returns the first element of `array` where the provided `checker` function returns true. + +See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN. + +## Examples +```rescript +type languages = ReScript | TypeScript | JavaScript + +let array = [TypeScript, JavaScript, ReScript] + +switch array->Array.findWithIndex((item, index) => index > 1 && item == ReScript) { +| None => Console.log("No item...") +| Some(_) => Console.log("Yay, ReScript exists in a later position!") +} +``` +*/ +@send +external findWithIndex: (array<'a>, ('a, int) => bool) => option<'a> = "find" + +/** +`findIndex(array, checker)` returns the index of the first element of `array` where the provided `checker` function returns true. + +Returns `-1` if the item does not exist. Consider using `Array.findIndexOpt` if you want an option instead (where `-1` would be `None`). + +See [`Array.findIndex`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex) on MDN. + +## Examples +```rescript +type languages = ReScript | TypeScript | JavaScript + +let array = [ReScript, JavaScript] + +Console.log(array->Array.findIndex(item => item == ReScript)) // 0 +Console.log(array->Array.findIndex(item => item == TypeScript)) // -1 +``` +*/ +@send +external findIndex: (array<'a>, 'a => bool) => int = "findIndex" + +/** +`findIndexWithIndex(array, checker)` returns the index of the first element of `array` where the provided `checker` function returns true. + +Returns `-1` if the item does not exist. Consider using `Array.findIndexOpt` if you want an option instead (where `-1` would be `None`). + +See [`Array.findIndex`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex) on MDN. + +## Examples +```rescript +type languages = ReScript | TypeScript | JavaScript + +let array = [ReScript, JavaScript] + +Console.log(array->Array.findIndexWithIndex((item, index) => index === 0 && item == ReScript)) // 0 +Console.log(array->Array.findIndex((item, index) => index === 0 && item == TypeScript)) // -1 +``` +*/ +@send +external findIndexWithIndex: (array<'a>, ('a, int) => bool) => int = "findIndex" + +/** +`forEach(array, fn)` runs the provided `fn` on every element of `array`. + +See [`Array.forEach`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) on MDN. + +## Examples +```rescript +let array = ["Hello", "Hi", "Good bye"] + +array->Array.forEach(item => { + Console.log(item) +}) +``` +*/ +@send +external forEach: (array<'a>, 'a => unit) => unit = "forEach" + +/** +`forEachWithIndex(array, fn)` runs the provided `fn` on every element of `array`. + +See [`Array.forEach`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) on MDN. + +## Examples +```rescript +let array = ["Hello", "Hi", "Good bye"] + +array->Array.forEachWithIndex((item, index) => { + Console.log("At item " ++ Int.toString(index) ++ ": " ++ item) +}) +``` +*/ +@send +external forEachWithIndex: (array<'a>, ('a, int) => unit) => unit = "forEach" + +/** +`map(array, fn)` returns a new array with all elements from `array`, each element transformed using the provided `fn`. + +See [`Array.map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) on MDN. + +## Examples +```rescript +let array = ["Hello", "Hi", "Good bye"] +let mappedArray = array->Array.map(greeting => greeting ++ " to you") + +Console.log(mappedArray) // ["Hello to you", "Hi to you", "Good bye to you"] +``` +*/ +@send +external map: (array<'a>, 'a => 'b) => array<'b> = "map" + +/** +`mapWithIndex(array, fn)` returns a new array with all elements from `array`, each element transformed using the provided `fn`. + +See [`Array.map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) on MDN. + +## Examples +```rescript +let array = ["Hello", "Hi", "Good bye"] +let mappedArray = + array->Array.mapWithIndex((greeting, index) => + greeting ++ " at position " ++ Int.toString(index) + ) + +Console.log(mappedArray) // ["Hello at position 0", "Hi at position 1", "Good bye at position 2"] +``` +*/ +@send +external mapWithIndex: (array<'a>, ('a, int) => 'b) => array<'b> = "map" /** `reduce(xs, f, init)` @@ -470,15 +691,112 @@ let reduceRight: (array<'a>, 'b, ('b, 'a) => 'b) => 'b */ let reduceRightWithIndex: (array<'a>, 'b, ('b, 'a, int) => 'b) => 'b -@send external some: (array<'a>, 'a => bool) => bool = "some" -@send external someWithIndex: (array<'a>, ('a, int) => bool) => bool = "some" -@get_index external get: (array<'a>, int) => option<'a> = "" -@set_index external set: (array<'a>, int, 'a) => unit = "" +/** +`some(array, checker)` returns true if running the provided `checker` function on any element in `array` returns true. + +See [`Array.some`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some) on MDN. + +## Examples +```rescript +let array = ["Hello", "Hi", "Good bye"] + +Console.log(array->Array.some(greeting => greeting === "Hello")) // true +``` +*/ +@send +external some: (array<'a>, 'a => bool) => bool = "some" + +/** +`someWithIndex(array, checker)` returns true if running the provided `checker` function on any element in `array` returns true. + +See [`Array.some`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some) on MDN. + +## Examples +```rescript +let array = ["Hello", "Hi", "Good bye"] + +Console.log(array->Array.someWithIndex((greeting, index) => greeting === "Hello" && index === 0)) // true +``` +*/ +@send +external someWithIndex: (array<'a>, ('a, int) => bool) => bool = "some" + +/** +`get(array, index)` returns the element at `index` of `array`. + +Returns `None` if the index does not exist in the array. Equivalent to doing `array[index]` in JavaScript. + +## Examples +```rescript +let array = ["Hello", "Hi", "Good bye"] + +array->Array.get(0) == Some("Hello") // true +``` +*/ +@get_index +external get: (array<'a>, int) => option<'a> = "" + +/** +`set(array, index, item)` sets the provided `item` at `index` of `array`. + +Beware this will *mutate* the array. + +## Examples +```rescript +let array = ["Hello", "Hi", "Good bye"] +array->Array.set(1, "Hello") + +Console.log(array[1]) // "Hello" +``` +*/ +@set_index +external set: (array<'a>, int, 'a) => unit = "" @get_index external getSymbol: (array<'a>, Core__Symbol.t) => option<'b> = "" @get_index external getSymbolUnsafe: (array<'a>, Core__Symbol.t) => 'b = "" @set_index external setSymbol: (array<'a>, Core__Symbol.t, 'b) => 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`. + +## Exceptions + +- `Not_found`: If the provided `index` does not exist in `array`. + +## 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 +``` +*/ +@raises(Not_found) external getUnsafe: (array<'a>, int) => 'a = "%array_unsafe_get" + +// TODO: Docs. Is there any practical difference from `set`? external setUnsafe: (array<'a>, int, 'a) => unit = "%array_unsafe_set" + +/** +`findIndexOpt(array, checker)` returns the index of the first element of `array` where the provided `checker` function returns true. + +Returns `None` if no item matches. + +See [`Array.findIndex`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex) on MDN. + +## Examples +```rescript +type languages = ReScript | TypeScript | JavaScript + +let array = [ReScript, TypeScript, JavaScript] + +switch array->Array.findIndexOpt(item => item == ReScript) { +| None => Console.log("Ahh, no ReScript...") +| Some(index) => Console.log("Yay, ReScript at index " ++ Int.toString(index)) +} +``` +*/ let findIndexOpt: (array<'a>, 'a => bool) => option /** @@ -495,6 +813,27 @@ Console.log(reversed) // ["hello", "h1"] ``` */ let reverse: array<'a> => array<'a> + +/** +`get(array, index)` returns the element at `index` of `array`. + +Returns `None` if the index does not exist in the array. Equivalent to doing `array[index]` in JavaScript. + +## Examples +```rescript +let array = ["Hello", "Hi", "Good bye"] + +Console.log( + array->Array.filterMap(item => + switch item { + | "Hello" => Some(item->String.length) + | _ => None + } + ), +) +// [5] +``` +*/ let filterMap: (array<'a>, 'a => option<'b>) => array<'b> /** @@ -508,9 +847,58 @@ let filterMap: (array<'a>, 'a => option<'b>) => array<'b> ``` */ let keepSome: array> => array<'a> + +/** +`shuffle(array)` returns a new array with all items in `array` shuffled. + +## Examples +```rescript +let array = ["Hello", "Hi", "Good bye"] +let shuffledArray = array->Array.shuffle + +Console.log(shuffledArray) +``` +*/ let shuffle: array<'a> => array<'a> + +/** +`shuffleInPlace(array)` shuffles all items in `array` in place. + +Beware this will *mutate* the array. + +## Examples +```rescript +let array = ["Hello", "Hi", "Good bye"] +array->Array.shuffle + +Console.log(array) +``` +*/ let shuffleInPlace: array<'a> => unit -@send external flatMap: (array<'a>, 'a => array<'b>) => array<'b> = "flatMap" + +/** +`flatMap(array, mapper)` returns a new array with all items from `array` run through the provided `mapper` function, and arrays flattened one level. + +## Examples +```rescript +type language = ReScript | TypeScript | JavaScript + +let array = [ReScript, TypeScript, JavaScript] + +Console.log( + array->Array.flatMap(item => + switch item { + | ReScript => [1, 2, 3] + | TypeScript => [4, 5, 6] + | JavaScript => [7, 8, 9] + } + ), +) +// [1, 2, 3, 4, 5, 6, 7, 8, 9] +``` +*/ +@send +external flatMap: (array<'a>, 'a => array<'b>) => array<'b> = "flatMap" /** `findMap(arr, f)` From b044643e3951636bc3fe12e616503283a715242f Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Thu, 9 Mar 2023 18:37:23 +0100 Subject: [PATCH 08/11] Apply suggestions from code review Co-authored-by: Glenn Slotte --- src/Core__Array.resi | 22 +++++++++++----------- src/Core__Iterator.resi | 2 +- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/src/Core__Array.resi b/src/Core__Array.resi index 59d813d5..bb53a69b 100644 --- a/src/Core__Array.resi +++ b/src/Core__Array.resi @@ -30,7 +30,7 @@ let fromInitializer: (~length: int, int => 'a) => array<'a> @val external isArray: 'a => bool = "Array.isArray" /** -`length(array)` returns the `int` length (number of items) of the array. +`length(array)` returns the length of (i.e. number of items in) the array. See [`Array.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length) on MDN. @@ -74,7 +74,7 @@ Console.log(myArray) // [9, 9, 9, 9] external fillAllInPlace: (array<'a>, 'a) => unit = "fill" /** -`fillInPlaceToEnd` fills the entire provided `array` with the provided `value`, starting from the index provided to `start`. +`fillInPlaceToEnd(array, value, ~start)` fills `array` with `value` from the `start` index. Beware this will *mutate* the array. @@ -92,7 +92,7 @@ Console.log(myArray) // [1, 9, 9, 9] external fillInPlaceToEnd: (array<'a>, 'a, ~start: int) => unit = "fill" /** -`fillInPlace` fills the entire provided `array` with the provided `value`, starting from the index provided to `start`, going to the index provided to `end`. +`fillInPlace(array, value, ~start, ~end)` fills `array` with `value` from `start` to `end`. Beware this will *mutate* the array. @@ -110,7 +110,7 @@ Console.log(myArray) // [1, 9, 9, 4] external fillInPlace: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill" /** -`pop(array)` pops off the last item in the array, and returns it. +`pop(array)` removes the last item from `array` and returns it. Beware this will *mutate* the array. @@ -128,7 +128,7 @@ Console.log(someArray) // ["hi"]. Notice last item is gone. external pop: array<'a> => option<'a> = "pop" /** -`push(array, item)` pushes a new item to the end of the array. +`push(array, item)` appends `item` to the end of `array`. Beware this will *mutate* the array. @@ -312,7 +312,7 @@ Console.log(someArray) // ["hi", "hello", "yay", "wehoo"] external concatMany: (array<'a>, array>) => array<'a> = "concat" /** -`flat(arrays)` flattens the provided arrays into a single array. +`flat(arrays)` concatenates an array of arrays into a single array. See [`Array.flat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat) on MDN. @@ -376,7 +376,7 @@ let lastIndexOfOpt: (array<'a>, 'a) => option @send external lastIndexOfFrom: (array<'a>, 'a, int) => int = "lastIndexOf" /** -`slice(array, start, end)` creates a new array from the provided `array`, with all items from `array` starting from `start`, stopping _before_ `end` (`end` is not included). +`slice(array, ~start, ~end)` creates a new array of items copied from `array` from `start` until (but not including) `end`. See [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) on MDN. @@ -405,7 +405,7 @@ Console.log(myArray->Array.sliceToEnd(~start=1)) // [2, 3, 4] @send external sliceToEnd: (array<'a>, ~start: int) => array<'a> = "slice" /** -`copy(array)` makes a shallow copy of the provided `array`. +`copy(array)` makes a copy of the array with the items in it, but does not make copies of the items themselves. ## Examples ```rescript @@ -435,7 +435,7 @@ Console.log(array->Array.toString) // "1,2,3,4" external toString: array<'a> => string = "toString" /** -`every(array, checker)` returns true if all items in `array` returns true when running the provided `checker` function. +`every(array, predicate)` returns true if `predicate` returns true for all items in `array`. See [`Array.every`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) on MDN. @@ -692,7 +692,7 @@ let reduceRight: (array<'a>, 'b, ('b, 'a) => 'b) => 'b let reduceRightWithIndex: (array<'a>, 'b, ('b, 'a, int) => 'b) => 'b /** -`some(array, checker)` returns true if running the provided `checker` function on any element in `array` returns true. +`some(array, predicate)` returns true if `predicate` returns true for any element in `array`. See [`Array.some`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some) on MDN. @@ -877,7 +877,7 @@ Console.log(array) let shuffleInPlace: array<'a> => unit /** -`flatMap(array, mapper)` returns a new array with all items from `array` run through the provided `mapper` function, and arrays flattened one level. +`flatMap(array, mapper)` returns a new array concatenating the arrays returned from running `mapper` on all items in `array`. ## Examples ```rescript diff --git a/src/Core__Iterator.resi b/src/Core__Iterator.resi index 36a9fed3..4953614d 100644 --- a/src/Core__Iterator.resi +++ b/src/Core__Iterator.resi @@ -58,7 +58,7 @@ Console.log(mapKeysAsArray) // Logs ["someKey", "someKey2"] to the console. external toArray: t<'a> => array<'a> = "Array.from" /** -Turns an iterator into an array of the remaining values, applying the provided mapper function on each item. +`toArray(iterator)` turns `iterator` into an array of its remaining values, applying the provided mapper function on each item. Remember that each invocation of `next` of an iterator consumes a value. `Iterator.toArrayWithMapper` will consume all remaining values of the iterator and return them in an array to you. See [iterator protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on MDN. From 41d73625d59fc2d99bfbc4b317d13163202e084d Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Thu, 9 Mar 2023 18:50:41 +0100 Subject: [PATCH 09/11] add back accidentally removed fns --- src/Core__Array.res | 1 + src/Core__Array.resi | 2 ++ 2 files changed, 3 insertions(+) diff --git a/src/Core__Array.res b/src/Core__Array.res index f329780c..cd1bda48 100644 --- a/src/Core__Array.res +++ b/src/Core__Array.res @@ -101,6 +101,7 @@ let sort = (arr, cmp) => { } @send external toString: array<'a> => string = "toString" +@send external toLocaleString: array<'a> => string = "toLocaleString" @send external every: (array<'a>, 'a => bool) => bool = "every" @send external everyWithIndex: (array<'a>, ('a, int) => bool) => bool = "every" diff --git a/src/Core__Array.resi b/src/Core__Array.resi index bb53a69b..c8a0dc0f 100644 --- a/src/Core__Array.resi +++ b/src/Core__Array.resi @@ -434,6 +434,8 @@ Console.log(array->Array.toString) // "1,2,3,4" @send external toString: array<'a> => string = "toString" +@send external toLocaleString: array<'a> => string = "toLocaleString" + /** `every(array, predicate)` returns true if `predicate` returns true for all items in `array`. From 37405fea8c82780493728fd949792abdd9738652 Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Thu, 9 Mar 2023 18:55:07 +0100 Subject: [PATCH 10/11] fixes after PR review --- src/Core__Array.resi | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/src/Core__Array.resi b/src/Core__Array.resi index c8a0dc0f..0469b3ff 100644 --- a/src/Core__Array.resi +++ b/src/Core__Array.resi @@ -777,7 +777,19 @@ Console.log(array->Array.getUnsafe(3)) // Fails and raises exception @raises(Not_found) external getUnsafe: (array<'a>, int) => 'a = "%array_unsafe_get" -// TODO: Docs. Is there any practical difference from `set`? +/** +`setUnsafe(array, index, item)` sets the provided `item` at `index` of `array`. + +Beware this will *mutate* the array, and is *unsafe*. + +## Examples +```rescript +let array = ["Hello", "Hi", "Good bye"] +array->Array.setUnsafe(1, "Hello") + +Console.log(array[1]) // "Hello" +``` +*/ external setUnsafe: (array<'a>, int, 'a) => unit = "%array_unsafe_set" /** @@ -851,7 +863,7 @@ let filterMap: (array<'a>, 'a => option<'b>) => array<'b> let keepSome: array> => array<'a> /** -`shuffle(array)` returns a new array with all items in `array` shuffled. +`shuffle(array)` returns a new array with all items in `array` in a random order. ## Examples ```rescript @@ -864,7 +876,7 @@ Console.log(shuffledArray) let shuffle: array<'a> => array<'a> /** -`shuffleInPlace(array)` shuffles all items in `array` in place. +`shuffleInPlace(array)` randomizes the position of all items in `array`. Beware this will *mutate* the array. From 4d4ffd87f69c28d13c4cadab8c86cf91f26293a6 Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Thu, 9 Mar 2023 20:49:40 +0100 Subject: [PATCH 11/11] more tweaks after PR comments --- src/Core__Array.resi | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/src/Core__Array.resi b/src/Core__Array.resi index 0469b3ff..253f0cf2 100644 --- a/src/Core__Array.resi +++ b/src/Core__Array.resi @@ -56,7 +56,7 @@ external copyWithinToEnd: (array<'a>, ~target: int, ~start: int) => array<'a> = external copyWithin: (array<'a>, ~target: int, ~start: int, ~end: int) => array<'a> = "copyWithin" /** -`fillAllInPlace(array, value)` fills the entire provided `array` with the provided `value`. +`fillAllInPlace(array, value)` fills the entire `array` with `value`. Beware this will *mutate* the array. @@ -146,7 +146,7 @@ Console.log(someArray) // ["hi", "hello", "yay"] external push: (array<'a>, 'a) => unit = "push" /** -`pushMany(array, itemsArray)` pushes many new items to the end of the array. +`pushMany(array, itemsArray)` appends many new items to the end of the array. Beware this will *mutate* the array. @@ -216,7 +216,7 @@ Console.log(sortedArray) // [1, 2, 3] let sort: (array<'a>, ('a, 'a) => int) => array<'a> /** -`sortInPlace(array, comparator)` sorts the provided `array` using the provided `comparator` function. +`sortInPlace(array, comparator)` sorts `array` using the `comparator` function. Beware this will *mutate* the array. @@ -274,7 +274,7 @@ Console.log(someArray) // ["yay", "wehoo", "hi", "hello"] external unshiftMany: (array<'a>, array<'a>) => unit = "unshift" /** -`concat(array1, array2)` concatenates two arrays, creating a new array. +`concat(array1, array2)` concatenates the two arrays, creating a new array. See [`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) on MDN. @@ -370,7 +370,19 @@ Console.log([{"language": "ReScript"}]->Array.indexOfOpt({"language": "ReScript" */ let indexOfOpt: (array<'a>, 'a) => option @send external indexOfFrom: (array<'a>, 'a, int) => int = "indexOf" -@send external joinWith: (array<'a>, string) => string = "join" + +/** +`joinWith(array, separator)` produces a string where all items of `array` are printed, separated by `separator`. Under the hood this will run JavaScript's `toString` on all the array items. + +## Examples +```rescript +let array = [1, 2, 3] + +Console.log(array->Array.joinWith(" -- ")) // 1 -- 2 -- 3 +``` +*/ +@send +external joinWith: (array<'a>, string) => string = "join" @send external lastIndexOf: (array<'a>, 'a) => int = "lastIndexOf" let lastIndexOfOpt: (array<'a>, 'a) => option @send external lastIndexOfFrom: (array<'a>, 'a, int) => int = "lastIndexOf" @@ -391,7 +403,7 @@ Console.log(myArray->Array.slice(~start=1, ~end=3)) // [2, 3] external slice: (array<'a>, ~start: int, ~end: int) => array<'a> = "slice" /** -`sliceToEnd(array, start)` creates a new array from the provided `array`, with all items from `array` starting from `start`. +`sliceToEnd(array, start)` creates a new array from `array`, with all items from `array` starting from `start`. See [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) on MDN. @@ -420,7 +432,7 @@ Console.log(myArray === copyOfMyArray) // false external copy: array<'a> => array<'a> = "slice" /** -`toString(array)` stringifies the provided `array`, by running `toString` on all of the array elements and joining them with ",". +`toString(array)` stringifies `array` by running `toString` on all of the array elements and joining them with ",". See [`Array.toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString) on MDN.