@grain/stdlib 0.5.12 → 0.6.0

package/list.gr

@@ -1,16 +1,13 @@
 /**
- * @module List: Utilities for working with lists.
+ * Utilities for working with lists.
  *
- * @example import List from "list"
+ * @example from "list" include List
  *
  * @since v0.2.0
  * @history v0.1.0: Originally named `lists`
  * @history v0.2.0: Renamed to `list`
  */
-
-/**
- * @section Values: Functions for working with the List data type.
- */
+module List
 
 /**
  * Creates a new list of the specified length where each element is
@@ -25,7 +22,7 @@
  *
  * @since v0.3.0
  */
-export let init = (length, fn) => {
+provide let init = (length, fn) => {
   // This method can be further improved by checking the length against a specific size
   // and determining if it can be made tail-recursive, then use List.reverse on it.
   // Which would be the same as OCaml does it in https://github.com/ocaml/ocaml/blob/03839754f46319aa36d9dad56940a6f3c3bcb48a/stdlib/list.ml#L79
@@ -48,7 +45,7 @@ export let init = (length, fn) => {
  * @since v0.1.0
  * @history v0.2.0: Made the function tail-recursive
  */
-export let length = list => {
+provide let length = list => {
   let rec iter = (len, list) => {
     match (list) {
       [] => len,
@@ -58,6 +55,21 @@ export let length = list => {
   iter(0, list)
 }
 
+/**
+ * Determines if the list contains no elements.
+ *
+ * @param list: The list to inspect
+ * @returns `true` if the list is empty and `false` otherwise
+ *
+ * @since v0.6.0
+ */
+provide let isEmpty = list => {
+  match (list) {
+    [] => true,
+    _ => false,
+  }
+}
+
 /**
  * Creates a new list with all elements in reverse order.
  *
@@ -66,7 +78,7 @@ export let length = list => {
  *
  * @since v0.1.0
  */
-export let reverse = list => {
+provide let reverse = list => {
   let rec iter = (list, acc) => {
     match (list) {
       [] => acc,
@@ -86,7 +98,7 @@ export let reverse = list => {
  *
  * @since v0.1.0
  */
-export let rec append = (list1, list2) => {
+provide let rec append = (list1, list2) => {
   match (list1) {
     [] => list2,
     [first, ...rest] => [first, ...append(rest, list2)],
@@ -103,7 +115,7 @@ export let rec append = (list1, list2) => {
  *
  * @since v0.1.0
  */
-export let rec contains = (search, list) => {
+provide let rec contains = (search, list) => {
   match (list) {
     [] => false,
     [first, ...rest] => first == search || contains(search, rest),
@@ -130,7 +142,7 @@ export let rec contains = (search, list) => {
  * @history v0.1.0: Originally named `foldLeft`
  * @history v0.2.0: Renamed to `reduce`
  */
-export let rec reduce = (fn, initial, list) => {
+provide let rec reduce = (fn, initial, list) => {
   match (list) {
     [] => initial,
     [first, ...rest] => reduce(fn, fn(initial, first), rest),
@@ -157,7 +169,7 @@ export let rec reduce = (fn, initial, list) => {
  * @history v0.1.0: Originally named `foldRight`
  * @history v0.2.0: Renamed to `reduceRight`
  */
-export let rec reduceRight = (fn, initial, list) => {
+provide let rec reduceRight = (fn, initial, list) => {
   match (list) {
     [] => initial,
     [first, ...rest] => fn(first, reduceRight(fn, initial, rest)),
@@ -174,7 +186,7 @@ export let rec reduceRight = (fn, initial, list) => {
  *
  * @since v0.1.0
  */
-export let rec map = (fn, list) => {
+provide let rec map = (fn, list) => {
   match (list) {
     [] => [],
     [first, ...rest] => [fn(first), ...map(fn, rest)],
@@ -191,7 +203,7 @@ export let rec map = (fn, list) => {
  *
  * @since v0.1.0
  */
-export let mapi = (fn, list) => {
+provide let mapi = (fn, list) => {
   let rec iter = (fn, list, index) => {
     match (list) {
       [] => [],
@@ -213,7 +225,7 @@ export let mapi = (fn, list) => {
  *
  * @since v0.2.0
  */
-export let rec flatMap = (fn, list) => {
+provide let rec flatMap = (fn, list) => {
   match (list) {
     [] => [],
     [first, ...rest] => append(fn(first), flatMap(fn, rest)),
@@ -230,7 +242,7 @@ export let rec flatMap = (fn, list) => {
  *
  * @since v0.1.0
  */
-export let rec every = (fn, list) => {
+provide let rec every = (fn, list) => {
   match (list) {
     [] => true,
     // The short-circuiting of `&&` makes this tail-recursive
@@ -248,7 +260,7 @@ export let rec every = (fn, list) => {
  *
  * @since v0.1.0
  */
-export let rec some = (fn, list) => {
+provide let rec some = (fn, list) => {
   match (list) {
     [] => false,
     // The short-circuiting of `||` makes this tail-recursive
@@ -264,7 +276,7 @@ export let rec some = (fn, list) => {
  *
  * @since v0.1.0
  */
-export let rec forEach = (fn, list) => {
+provide let rec forEach = (fn, list) => {
   match (list) {
     [] => void,
     [first, ...rest] => {
@@ -283,7 +295,7 @@ export let rec forEach = (fn, list) => {
  *
  * @since v0.1.0
  */
-export let forEachi = (fn, list) => {
+provide let forEachi = (fn, list) => {
   let rec iter = (fn, list, index) => {
     match (list) {
       [] => void,
@@ -307,7 +319,7 @@ export let forEachi = (fn, list) => {
  *
  * @since v0.1.0
  */
-export let rec filter = (fn, list) => {
+provide let rec filter = (fn, list) => {
   match (list) {
     [] => [],
     [first, ...rest] =>
@@ -326,13 +338,15 @@ export let rec filter = (fn, list) => {
  *
  * @since v0.3.0
  */
-export let filteri = (fn, list) => {
+provide let filteri = (fn, list) => {
   let rec iter = (fn, list, index) => {
     match (list) {
       [] => [],
       [first, ...rest] =>
-        if (fn(first, index)) [first, ...iter(fn, rest, index + 1)]
-        else iter(fn, rest, index + 1),
+        if (fn(first, index))
+          [first, ...iter(fn, rest, index + 1)]
+        else
+          iter(fn, rest, index + 1),
     }
   }
   iter(fn, list, 0)
@@ -349,7 +363,7 @@ export let filteri = (fn, list) => {
  *
  * @since v0.1.0
  */
-export let rec reject = (fn, list) => {
+provide let rec reject = (fn, list) => {
   match (list) {
     [] => [],
     [first, ...rest] =>
@@ -369,7 +383,7 @@ export let rec reject = (fn, list) => {
  * @history v0.2.0: Renamed to `head`
  * @history v0.3.0: Return type converted to `Option` type
  */
-export let head = list => {
+provide let head = list => {
   match (list) {
     [] => None,
     [first, ..._] => Some(first),
@@ -388,7 +402,7 @@ export let head = list => {
  * @history v0.2.0: Renamed to `tail`
  * @history v0.3.0: Return type converted to `Option` type
  */
-export let tail = list => {
+provide let tail = list => {
   match (list) {
     [] => None,
     [_, ...rest] => Some(rest),
@@ -407,7 +421,7 @@ export let tail = list => {
  * @history v0.1.0: Originally failed for index out-of-bounds or list empty
  * @history v0.3.0: Return type converted to `Option` type
  */
-export let rec nth = (index, list) => {
+provide let rec nth = (index, list) => {
   if (index < 0) {
     None
   } else {
@@ -428,7 +442,7 @@ export let rec nth = (index, list) => {
  *
  * @since v0.1.0
  */
-export let rec flatten = list => {
+provide let rec flatten = list => {
   match (list) {
     [] => [],
     [first, ...rest] => append(first, flatten(rest)),
@@ -438,8 +452,8 @@ export 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
  *
@@ -447,16 +461,19 @@ export let rec flatten = list => {
  * @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
  */
-export 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)],
+        if (index == 0)
+          [value, ...list]
+        else
+          [first, ...insert(index - 1, value, rest)],
     }
   }
 }
@@ -471,7 +488,7 @@ export let rec insert = (value, index, list) => {
  * @since v0.1.0
  * @history v0.2.0: Made the function tail-recursive
  */
-export let count = (fn, list) => {
+provide let count = (fn, list) => {
   let rec iter = (n, list) => {
     match (list) {
       [] => n,
@@ -493,7 +510,7 @@ export let count = (fn, list) => {
  *
  * @since v0.1.0
  */
-export let part = (count, list) => {
+provide let part = (count, list) => {
   if (count < 0) {
     fail "part count cannot be a negative number"
   } else {
@@ -502,8 +519,10 @@ export let part = (count, list) => {
         [] =>
           if (count > 0) fail "part count is out-of-bounds" else (list1, list2),
         [first, ...rest] =>
-          if (count > 0) iter([first, ...list1], rest, count - 1)
-          else (list1, list2),
+          if (count > 0)
+            iter([first, ...list1], rest, count - 1)
+          else
+            (list1, list2),
       }
     }
     let (pt1, pt2) = iter([], list, count)
@@ -512,24 +531,50 @@ export let part = (count, list) => {
 }
 
 /**
- * Rotates list elements by the specified amount to the left.
+ * Rotates list elements by the specified amount to the left, such that `n`th
+ * element is the first in the new list.
  *
  * If value is negative, list elements will be rotated by the
  * specified amount to the right. See examples.
  *
- * @param count: The number of elements to rotate by
+ * @param n: The number of elements to rotate by
  * @param list: The list to be rotated
  *
  * @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
+ *
+ * @history v0.6.0: No longer throws if `count` outside list length bounds
  */
-export let rotate = (count, list) => {
-  let (beginning, end) =
-    if (count >= 0) part(count, list) else part(length(list) + count, list)
+provide let rotate = (n, list) => {
+  // Optimization: only compute the list length (O(n)) if n is negative
+  // or if the entire list is exhausted when partitioning. This should improve
+  // performance if the list is very long but n is small
+  let getSplitI = () => {
+    let len = length(list)
+    if (len == 0) 0 else n % len
+  }
+  let (beginning, end) = if (n >= 0) {
+    let rec iter = (list1, list2, n) => {
+      match (list2) {
+        [] => if (n > 0) None else Some((list1, list2)),
+        [first, ...rest] =>
+          if (n > 0)
+            iter([first, ...list1], rest, n - 1)
+          else
+            Some((list1, list2)),
+      }
+    }
+    let res = iter([], list, n)
+    match (res) {
+      None => part(getSplitI(), list),
+      Some((pt1, pt2)) => (reverse(pt1), pt2),
+    }
+  } else {
+    part(getSplitI(), list)
+  }
   append(end, beginning)
 }
 
@@ -544,13 +589,15 @@ export let rotate = (count, list) => {
  * @history v0.1.0: Originally named `uniq`
  * @history v0.2.0: Renamed to `unique`
  */
-export let unique = list => {
+provide let unique = list => {
   let rec iter = (list, acc) => {
     match (list) {
       [] => reverse(acc),
       [first, ...rest] =>
-        if (contains(first, acc)) iter(rest, acc)
-        else iter(rest, [first, ...acc]),
+        if (contains(first, acc))
+          iter(rest, acc)
+        else
+          iter(rest, [first, ...acc]),
     }
   }
   iter(list, [])
@@ -573,7 +620,7 @@ export let unique = list => {
  *
  * @since v0.5.3
  */
-export let zip = (list1, list2) => {
+provide let zip = (list1, list2) => {
   let rec zipInner = (list1, list2, acc) => {
     match ((list1, list2)) {
       ([first1, ...rest1], [first2, ...rest2]) =>
@@ -604,7 +651,7 @@ export let zip = (list1, list2) => {
  *
  * @since v0.5.3
  */
-export let zipWith = (fn, list1, list2) => {
+provide let zipWith = (fn, list1, list2) => {
   let rec zipWithInner = (list1, list2, acc) => {
     match ((list1, list2)) {
       ([first1, ...rest1], [first2, ...rest2]) =>
@@ -623,10 +670,14 @@ export let zipWith = (fn, list1, list2) => {
  *
  * @since v0.5.3
  */
-export let unzip = list => {
-  reduceRight(((first, second), (firstUnzipped, secondUnzipped)) => {
-    ([first, ...firstUnzipped], [second, ...secondUnzipped])
-  }, ([], []), list)
+provide let unzip = list => {
+  reduceRight(
+    ((first, second), (firstUnzipped, secondUnzipped)) => {
+      ([first, ...firstUnzipped], [second, ...secondUnzipped])
+    },
+    ([], []),
+    list
+  )
 }
 
 /**
@@ -641,13 +692,13 @@ export let unzip = list => {
  *
  * @since v0.2.0
  */
-export let rec drop = (count, list) => {
+provide let rec drop = (count, list) => {
   if (count < 0) {
     fail "number of items to drop cannot be a negative number"
   } else {
     match ((count, list)) {
       (_, []) => [],
-      (n, _) when n == 0 => list,
+      (0, _) => list,
       (n, [first, ...rest]) => drop(n - 1, rest),
     }
   }
@@ -664,7 +715,7 @@ export let rec drop = (count, list) => {
  *
  * @since v0.2.0
  */
-export let rec dropWhile = (fn, list) => {
+provide let rec dropWhile = (fn, list) => {
   match (list) {
     [] => list,
     [first, ...rest] => if (fn(first)) dropWhile(fn, rest) else list,
@@ -683,13 +734,13 @@ export let rec dropWhile = (fn, list) => {
  *
  * @since v0.2.0
  */
-export let rec take = (count, list) => {
+provide let rec take = (count, list) => {
   if (count < 0) {
     fail "number of items to take cannot be a negative number"
   } else {
     match ((count, list)) {
       (_, []) => list,
-      (n, _) when n == 0 => [],
+      (0, _) => [],
       (n, [first, ...rest]) => [first, ...take(n - 1, rest)],
     }
   }
@@ -706,7 +757,7 @@ export let rec take = (count, list) => {
  *
  * @since v0.2.0
  */
-export let rec takeWhile = (fn, list) => {
+provide let rec takeWhile = (fn, list) => {
   match (list) {
     [] => [],
     [first, ...rest] => if (fn(first)) [first, ...takeWhile(fn, rest)] else [],
@@ -724,7 +775,7 @@ export let rec takeWhile = (fn, list) => {
  * @history v0.2.0: Originally failed if the list was empty
  * @history v0.3.0: Return type converted to `Option` type
  */
-export let rec find = (fn, list) => {
+provide let rec find = (fn, list) => {
   match (list) {
     [] => None,
     [first, ...rest] => if (fn(first)) Some(first) else find(fn, rest),
@@ -742,7 +793,7 @@ export let rec find = (fn, list) => {
  * @history v0.2.0: Originally failed if the list was empty
  * @history v0.3.0: Return type converted to `Option` type
  */
-export let findIndex = (fn, list) => {
+provide let findIndex = (fn, list) => {
   let rec findItemIndex = (l, index) => {
     match (l) {
       [] => None,
@@ -763,7 +814,7 @@ export let findIndex = (fn, list) => {
  *
  * @since v0.2.0
  */
-export let product = (list1, list2) => {
+provide let product = (list1, list2) => {
   let mut list = []
   forEach(aItem => {
     forEach(bItem => {
@@ -787,7 +838,7 @@ export let product = (list1, list2) => {
  *
  * @since v0.2.0
  */
-export let sub = (start, length, list) => {
+provide let sub = (start, length, list) => {
   take(length, drop(start, list))
 }
 
@@ -801,7 +852,7 @@ export let sub = (start, length, list) => {
  *
  * @since v0.4.0
  */
-export let join = (separator: String, list: List<String>) => {
+provide let join = (separator: String, list: List<String>) => {
   let rec iter = (sep, acc, rem) => {
     match (rem) {
       [] => acc,
@@ -831,7 +882,7 @@ export let join = (separator: String, list: List<String>) => {
  *
  * @since v0.4.5
  */
-export let rec revAppend = (list1, list2) => {
+provide let rec revAppend = (list1, list2) => {
   match (list1) {
     [hd, ...tl] => revAppend(tl, [hd, ...list2]),
     [] => list2,
@@ -842,13 +893,14 @@ export let rec revAppend = (list1, list2) => {
  * Sorts the given list based on a given comparator function. The resulting list is sorted in increasing order.
  *
  * Ordering is calculated using a comparator function which takes two list elements and must return 0 if both are equal, a positive number if the first is greater, and a negative number if the first is smaller.
- * @param comp: The comparator function used to indicate sort order
+ * @param compare: The comparator function used to indicate sort order
  * @param list: The list to be sorted
  * @returns The sorted list
  *
  * @since v0.4.5
+ * @history v0.6.0: Made `compare` a default argument
  */
-export let sort = (comp, list) => {
+provide let sort = (compare=compare, list) => {
   let rec merge = (left, right, list) => {
     match ((left, right)) {
       (_, []) => {
@@ -858,7 +910,7 @@ export let sort = (comp, list) => {
         revAppend(list, right)
       },
       ([lhd, ...ltl], [rhd, ...rtl]) => {
-        if (comp(lhd, rhd) < 0) {
+        if (compare(lhd, rhd) < 0) {
           merge(ltl, right, append([lhd], list))
         } else {
           merge(left, rtl, append([rhd], list))