Change idiom from e.g. shuffle to toShuffled and shuffleInPlace to shuffle

See #139 (comment)

Author: chenglou

CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## 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
 
 ### Bug fixes

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

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=""
+rewrite=""

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 */

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
 }
 

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<option<'a>> => 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`.

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 ,

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)
 }
 

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
 ```

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"

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([
       [

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,