feat(stdlib)!: Reorder parameters to List.insert (#1857)

compiler/test/stdlib/list.test.gr

@@ -120,10 +120,10 @@ assert flatten([list, []]) == list
 
 // List.insert
 
-assert insert(1, 0, []) == [1]
+assert insert(0, 1, []) == [1]
 assert insert(0, 0, list) == [0, 1, 2, 3]
-assert insert(0, 2, list) == [1, 2, 0, 3]
-assert insert(0, 3, list) == [1, 2, 3, 0]
+assert insert(2, 0, list) == [1, 2, 0, 3]
+assert insert(3, 0, list) == [1, 2, 3, 0]
 
 // List.count
 

stdlib/list.gr

@@ -451,25 +451,26 @@ provide let rec flatten = list => {
 /**
  * Inserts a new value into a list at the specified index.
  *
- * @param value: The value to insert
  * @param index: The index to update
+ * @param value: The value to insert
  * @param list: The list to update
  * @returns The new list
  *
  * @throws Failure(String): When `index` is negative
  * @throws Failure(String): When `index` is more than 0 and greater than the list size
  *
  * @since v0.1.0
+ * @history v0.6.0: Swapped order of `index` and `value` parameters
  */
-provide let rec insert = (value, index, list) => {
+provide let rec insert = (index, value, list) => {
   if (index < 0) {
     fail "insert index cannot be a negative number"
   } else {
     match (list) {
       [] => if (index == 0) [value] else fail "insert index is out-of-bounds",
       [first, ...rest] =>
         if (index == 0) [value, ...list]
-        else [first, ...insert(value, index - 1, rest)],
+        else [first, ...insert(index - 1, value, rest)],
     }
   }
 }

stdlib/list.md

@@ -689,13 +689,20 @@ List.flatten([[1, 2], [3, 4]]) // [1, 2, 3, 4]
 
 ### List.**insert**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.1.0</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.1.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>next</code></td><td>Swapped order of `index` and `value` parameters</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-insert : (value: a, index: Number, list: List<a>) => List<a>
+insert : (index: Number, value: a, list: List<a>) => List<a>
 ```
 
 Inserts a new value into a list at the specified index.
@@ -704,8 +711,8 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`value`|`a`|The value to insert|
 |`index`|`Number`|The index to update|
+|`value`|`a`|The value to insert|
 |`list`|`List<a>`|The list to update|
 
 Returns: