feat(stdlib)!: List.rotate wraparound for count > length (#1558)

Closes #1522

Author: alex-snezhko

compiler/test/stdlib/list.test.gr

@@ -135,6 +135,12 @@ assert rotate(0, list) == list
 assert rotate(1, list) == [2, 3, 1]
 assert rotate(2, list) == [3, 1, 2]
 assert rotate(-2, list) == [2, 3, 1]
+let l = [1, 2, 3, 4, 5]
+assert rotate(5, l) == l
+assert rotate(7, l) == [3, 4, 5, 1, 2]
+assert rotate(-18, l) == [3, 4, 5, 1, 2]
+assert rotate(1, []) == []
+assert rotate(0, []) == []
 
 // List.unique
 

stdlib/list.gr

@@ -523,14 +523,37 @@ export let part = (count, list) => {
  *
  * @example List.rotate(2, [1, 2, 3, 4, 5]) // [3, 4, 5, 1, 2]
  * @example List.rotate(-1, [1, 2, 3, 4, 5]) // [5, 1, 2, 3, 4]
- *
- * @throws Failure(String): When the list doesn't contain at least the required amount of elements
+ * @example List.rotate(-7, [1, 2, 3, 4, 5]) // [4, 5, 1, 2, 3]
  *
  * @since v0.1.0
- */
-export let rotate = (n, list) => {
-  let (beginning, end) =
-    if (n >= 0) part(n, list) else part(length(list) + n, list)
+ * 
+ * @history v0.6.0: No longer throws if `count` outside list length bounds
+ */
+export let rotate = (count, list) => {
+  // Optimization: only compute the list length (O(n)) if the count is negative
+  // or if the entire list is exhausted when partitioning. This should improve
+  // performance if the list is very long but the count is small
+  let getSplitI = () => {
+    let len = length(list)
+    if (len == 0) 0 else count % len
+  }
+  let (beginning, end) = if (count >= 0) {
+    let rec iter = (list1, list2, count) => {
+      match (list2) {
+        [] => if (count > 0) None else Some((list1, list2)),
+        [first, ...rest] =>
+          if (count > 0) iter([first, ...list1], rest, count - 1)
+          else Some((list1, list2)),
+      }
+    }
+    let res = iter([], list, count)
+    match (res) {
+      None => part(getSplitI(), list),
+      Some((pt1, pt2)) => (reverse(pt1), pt2),
+    }
+  } else {
+    part(getSplitI(), list)
+  }
   append(end, beginning)
 }
 

stdlib/list.md

@@ -764,9 +764,16 @@ Throws:
 
 ### List.**rotate**
 
-<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>No longer throws if `count` outside list length bounds</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
@@ -786,12 +793,6 @@ Parameters:
 |`n`|`Number`|The number of elements to rotate by|
 |`list`|`List<a>`|The list to be rotated|
 
-Throws:
-
-`Failure(String)`
-
-* When the list doesn't contain at least the required amount of elements
-
 Examples:
 
 ```grain
@@ -802,6 +803,10 @@ List.rotate(2, [1, 2, 3, 4, 5]) // [3, 4, 5, 1, 2]
 List.rotate(-1, [1, 2, 3, 4, 5]) // [5, 1, 2, 3, 4]
 ```
 
+```grain
+List.rotate(-7, [1, 2, 3, 4, 5]) // [4, 5, 1, 2, 3]
+```
+
 ### List.**unique**
 
 <details>