From 3a2464177b17543e85224f96d264004d9f7bf360 Mon Sep 17 00:00:00 2001 From: Cheng Lou Date: Tue, 23 May 2023 03:30:48 -0700 Subject: [PATCH] Change idiom from e.g. `shuffle` to `toShuffled` and `shuffleInPlace` to `shuffle` See https://github.com/rescript-association/rescript-core/pull/139#issuecomment-1557231008 --- CHANGELOG.md | 22 ++++++++++++++++++++- README.md | 2 +- migration/migration.toml | 8 ++++++-- src/Core__Array.mjs | 8 ++++---- src/Core__Array.res | 14 +++++++------- src/Core__Array.resi | 28 +++++++++++++-------------- src/Core__List.mjs | 6 +++--- src/Core__List.res | 4 ++-- src/Core__List.resi | 8 ++++---- src/typed-arrays/Core__TypedArray.res | 6 +++--- test/ArrayTests.mjs | 12 ++++++------ test/ArrayTests.res | 6 +++--- 12 files changed, 74 insertions(+), 50 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e811884f..1d8fae13 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,26 @@ # @rescript/core Changelog -## main +## Next version + +### API changes + +- `Array` mutable & immutable helper name changed to conform to JS' upcoming APIs [such as `toSorted`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toSorted) + - `sort` -> `toSorted`, `sortInPlace` -> `sort` + - `reverse` -> `toReversed`, `reverseInPlace` -> `reverse` + - `splice` -> `toSpliced`, `spliceInPlace` -> `splice` + - `shuffle` -> `toShuffled`, `shuffleInPlace` -> `shuffle` + - `fillAllInPlace` -> `fillAll`, `fillInPlaceToEnd` -> `fillToEnd`, `fillInPlace` -> `fill` + - added `with` +- Same for `TypedArray`: + - `sort` -> `toSorted`, `sortInPlace` -> `sort` + - `reverse` -> `toReversed`, `reverseInPlace` -> `reverse` + - `fillAllInPlace` -> `fillAll`, `fillInPlaceToEnd` -> `fillToEnd`, `fillInPlace` -> `fill` +- And `List`: + - `shuffle` -> `toShuffled` + +**Note 1**: These changes should all produce the correct type errors. Though `TypedArray`'s `reverse` and `sort` previously mutated _and_ returned the mutated array itself, whereas now they'd be copies. Please be careful refactoring these 2. + +**Note 2**: the newly added helpers, `Array.toSorted`, `Array.toSpliced`, `Array.toReversed`, `Array.with`, `TypedArray.toSorted` and `TypedArray.toReversed` require their respective polyfill, as [they're not currently supported by Firefox](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toSorted). ## 0.3.1 diff --git a/README.md b/README.md index f0ecc67f..fbc825a1 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,7 @@ This standard library is based on `rescript-js`, but with the tweaks and modific - `setUnsafe` added (copied from `Belt`). - `sort`, `toSorted`, `reverse`, `toReversed`, `splice`, `toSpliced` are the same as their JS counterpart (mutable and immutable, respectively). - `keepMap` is added from `Belt`, but **renamed to `filterMap`**. Rationale: `filterMap` is closer to the JS convention of naming. It's also available in other languages like Rust. `keep` et al can confuse beginners, who're bound to be looking for `filter` style names since that's what JS has. -- `shuffle` and `shuffleInPlace` are added (copied from `Belt`). +- `shuffle` and `toShuffled` are added (copied from `Belt`'s `shuffleInPlace` and `shuffle`). - `flatMap` added (copied from `Belt`, but using native `map` and `concat` functions). ### Float diff --git a/migration/migration.toml b/migration/migration.toml index 079810c3..31cd5e5d 100644 --- a/migration/migration.toml +++ b/migration/migration.toml @@ -150,7 +150,7 @@ match="Math.min_float" rewrite="Math.min" ## BELT -## Below are migrations that cover moving from Belt to equivalents +## Below are migrations that cover moving from Belt to equivalents ## available in the new stdlib. [belt-option] match="Belt.Option" @@ -182,6 +182,10 @@ rewrite="Array.filterMap" [belt-array-a-shuffle] match="Belt.Array.shuffle" +rewrite="Array.toShuffled" + +[belt-array-a-shuffle-in-place] +match="Belt.Array.shuffleInPlace" rewrite="Array.shuffle" [belt-array-a-flat-map] @@ -270,4 +274,4 @@ rewrite="Date" [js-global-a] match="Js.Global." -rewrite="" \ No newline at end of file +rewrite="" diff --git a/src/Core__Array.mjs b/src/Core__Array.mjs index 3a0598ef..74183c35 100644 --- a/src/Core__Array.mjs +++ b/src/Core__Array.mjs @@ -70,16 +70,16 @@ function swapUnsafe(xs, i, j) { xs[j] = tmp; } -function shuffleInPlace(xs) { +function shuffle(xs) { var len = xs.length; for(var i = 0; i < len; ++i){ swapUnsafe(xs, i, Js_math.random_int(i, len)); } } -function shuffle(xs) { +function toShuffled(xs) { var result = xs.slice(); - shuffleInPlace(result); + shuffle(result); return result; } @@ -135,8 +135,8 @@ export { findIndexOpt , filterMap , keepSome , + toShuffled , shuffle , - shuffleInPlace , findMap , } /* No side effect */ diff --git a/src/Core__Array.res b/src/Core__Array.res index 6c447571..e0d6cd5a 100644 --- a/src/Core__Array.res +++ b/src/Core__Array.res @@ -7,18 +7,18 @@ external setUnsafe: (array<'a>, int, 'a) => unit = "%array_unsafe_set" @val external fromArrayLikeWithMap: (Js.Array2.array_like<'a>, 'a => 'b) => array<'b> = "Array.from" -@send external fillAllInPlace: (array<'a>, 'a) => unit = "fill" +@send external fillAll: (array<'a>, 'a) => unit = "fill" -@send external fillInPlaceToEnd: (array<'a>, 'a, ~start: int) => unit = "fill" +@send external fillToEnd: (array<'a>, 'a, ~start: int) => unit = "fill" -@send external fillInPlace: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill" +@send external fill: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill" let make = (~length, x) => if length <= 0 { [] } else { let arr = makeUninitializedUnsafe(length) - arr->fillAllInPlace(x) + arr->fillAll(x) arr } @@ -154,16 +154,16 @@ let swapUnsafe = (xs, i, j) => { setUnsafe(xs, j, tmp) } -let shuffleInPlace = xs => { +let shuffle = xs => { let len = length(xs) for i in 0 to len - 1 { swapUnsafe(xs, i, Js.Math.random_int(i, len)) /* [i,len) */ } } -let shuffle = xs => { +let toShuffled = xs => { let result = copy(xs) - shuffleInPlace(result) + shuffle(result) result } diff --git a/src/Core__Array.resi b/src/Core__Array.resi index ada0d4f9..ccbb4e1d 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 `array` with `value`. +`fillAll(array, value)` fills the entire `array` with `value`. Beware this will *mutate* the array. @@ -65,16 +65,16 @@ See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer ## Examples ```rescript let myArray = [1, 2, 3, 4] -myArray->Array.fillAllInPlace(9) +myArray->Array.fillAll(9) Console.log(myArray) // [9, 9, 9, 9] ``` */ @send -external fillAllInPlace: (array<'a>, 'a) => unit = "fill" +external fillAll: (array<'a>, 'a) => unit = "fill" /** -`fillInPlaceToEnd(array, value, ~start)` fills `array` with `value` from the `start` index. +`fillToEnd(array, value, ~start)` fills `array` with `value` from the `start` index. Beware this will *mutate* the array. @@ -83,16 +83,16 @@ See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer ## Examples ```rescript let myArray = [1, 2, 3, 4] -myArray->Array.fillInPlaceToEnd(9, ~start=1) +myArray->Array.fillToEnd(9, ~start=1) Console.log(myArray) // [1, 9, 9, 9] ``` */ @send -external fillInPlaceToEnd: (array<'a>, 'a, ~start: int) => unit = "fill" +external fillToEnd: (array<'a>, 'a, ~start: int) => unit = "fill" /** -`fillInPlace(array, value, ~start, ~end)` fills `array` with `value` from `start` to `end`. +`fill(array, value, ~start, ~end)` fills `array` with `value` from `start` to `end`. Beware this will *mutate* the array. @@ -101,13 +101,13 @@ See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer ## Examples ```rescript let myArray = [1, 2, 3, 4] -myArray->Array.fillInPlace(9, ~start=1, ~end=2) +myArray->Array.fill(9, ~start=1, ~end=2) Console.log(myArray) // [1, 9, 9, 4] ``` */ @send -external fillInPlace: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill" +external fill: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill" /** `pop(array)` removes the last item from `array` and returns it. @@ -885,20 +885,20 @@ 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` in a random order. +`toShuffled(array)` returns a new array with all items in `array` in a random order. ## Examples ```rescript let array = ["Hello", "Hi", "Good bye"] -let shuffledArray = array->Array.shuffle +let shuffledArray = array->Array.toShuffled Console.log(shuffledArray) ``` */ -let shuffle: array<'a> => array<'a> +let toShuffled: array<'a> => array<'a> /** -`shuffleInPlace(array)` randomizes the position of all items in `array`. +`shuffle(array)` randomizes the position of all items in `array`. Beware this will *mutate* the array. @@ -910,7 +910,7 @@ array->Array.shuffle Console.log(array) ``` */ -let shuffleInPlace: array<'a> => unit +let shuffle: array<'a> => unit /** `flatMap(array, mapper)` returns a new array concatenating the arrays returned from running `mapper` on all items in `array`. diff --git a/src/Core__List.mjs b/src/Core__List.mjs index 8da20a23..88b2cc9d 100644 --- a/src/Core__List.mjs +++ b/src/Core__List.mjs @@ -651,9 +651,9 @@ function toArray(x) { return arr; } -function shuffle(xs) { +function toShuffled(xs) { var v = toArray(xs); - Core__Array.shuffleInPlace(v); + Core__Array.shuffle(v); return fromArray(v); } @@ -1357,7 +1357,7 @@ export { getExn , make , makeBy , - shuffle , + toShuffled , drop , take , splitAt , diff --git a/src/Core__List.res b/src/Core__List.res index 317d3c2e..5506f64b 100644 --- a/src/Core__List.res +++ b/src/Core__List.res @@ -481,9 +481,9 @@ let toArray = (x: t<_>) => { arr } -let shuffle = xs => { +let toShuffled = xs => { let v = toArray(xs) - Core__Array.shuffleInPlace(v) + Core__Array.shuffle(v) fromArray(v) } diff --git a/src/Core__List.resi b/src/Core__List.resi index 189083af..5c3a1718 100644 --- a/src/Core__List.resi +++ b/src/Core__List.resi @@ -193,15 +193,15 @@ List.makeBy(5, i => i * i) // list{0, 1, 4, 9, 16} let makeBy: (int, int => 'a) => t<'a> /** -`shuffle(list)` returns a new list in random order. +`toShuffled(list)` returns a new list in random order. ## Examples ```rescript -List.shuffle(list{1, 2, 3}) // list{2, 1, 3} +List.toShuffled(list{1, 2, 3}) // list{2, 1, 3} ``` */ -let shuffle: t<'a> => t<'a> +let toShuffled: t<'a> => t<'a> /** `drop(list, value)` return a new list, dropping the first `value` element. @@ -391,7 +391,7 @@ let f = x => x * x let l = list{3, 4, 5} let withMap = List.map(l, f)->List.reverse -let withMapReverse = l->List.mapReverse(f) +let withMapReverse = l->List.mapReverse(f) Console.log(withMap == withMapReverse) // true ``` diff --git a/src/typed-arrays/Core__TypedArray.res b/src/typed-arrays/Core__TypedArray.res index 16714279..e93191e5 100644 --- a/src/typed-arrays/Core__TypedArray.res +++ b/src/typed-arrays/Core__TypedArray.res @@ -17,9 +17,9 @@ type t<'a> @send external copyWithin: (t<'a>, ~target: int, ~start: int, ~end: int) => array<'a> = "copyWithin" -@send external fillAllInPlace: (t<'a>, 'a) => t<'a> = "fill" -@send external fillInPlaceToEnd: (t<'a>, 'a, ~start: int) => t<'a> = "fill" -@send external fillInPlace: (t<'a>, 'a, ~start: int, ~end: int) => t<'a> = "fill" +@send external fillAll: (t<'a>, 'a) => t<'a> = "fill" +@send external fillToEnd: (t<'a>, 'a, ~start: int) => t<'a> = "fill" +@send external fill: (t<'a>, 'a, ~start: int, ~end: int) => t<'a> = "fill" @send external reverse: t<'a> => unit = "reverse" @send external toReversed: t<'a> => t<'a> = "toReversed" diff --git a/test/ArrayTests.mjs b/test/ArrayTests.mjs index 7cc4a4c6..891b9262 100644 --- a/test/ArrayTests.mjs +++ b/test/ArrayTests.mjs @@ -201,10 +201,10 @@ Test.run([ "ArrayTests.res", 51, 20, - 38 + 41 ], - "shuffle - length" - ], Core__Array.shuffle([ + "toShuffled - length" + ], Core__Array.toShuffled([ 1, 2, 3 @@ -221,10 +221,10 @@ Test.run([ "ArrayTests.res", 54, 13, - 38 + 31 ], - "shuffleInPlace - length" - ], (Core__Array.shuffleInPlace(arr), arr.length), eq, 3); + "shuffle - length" + ], (Core__Array.shuffle(arr), arr.length), eq, 3); Test.run([ [ diff --git a/test/ArrayTests.res b/test/ArrayTests.res index 40c352f7..d22ff4a3 100644 --- a/test/ArrayTests.res +++ b/test/ArrayTests.res @@ -48,13 +48,13 @@ Test.run( list{}, ) -Test.run(__POS_OF__("shuffle - length"), Array.shuffle([1, 2, 3])->Array.length, eq, 3) +Test.run(__POS_OF__("toShuffled - length"), Array.toShuffled([1, 2, 3])->Array.length, eq, 3) Test.run( - __POS_OF__("shuffleInPlace - length"), + __POS_OF__("shuffle - length"), { let arr = [1, 2, 3] - Array.shuffleInPlace(arr) + Array.shuffle(arr) arr->Array.length }, eq,