@grain/stdlib 0.4.4 → 0.5.0

package/list.gr

@@ -1,8 +1,31 @@
-// Standard library for list functionality
+/**
+ * @module List: Utilities for working with lists.
+ *
+ * @example import List from "list"
+ *
+ * @since v0.2.0
+ * @history v0.1.0: Originally named `lists`
+ * @history v0.2.0: Renamed to `list`
+ */
 
-export *
+/**
+ * @section Values: Functions for working with the List data type.
+ */
 
-let init = (length, fn) => {
+/**
+ * Creates a new list of the specified length where each element is
+ * initialized with the result of an initializer function. The initializer
+ * is called with the index of each list element.
+ *
+ * @param length: The length of the new list
+ * @param fn: The initializer function to call with each index, where the value returned will be used to initialize the element
+ * @returns The new list
+ *
+ * @example List.init(5, n => n + 3) // [3, 4, 5, 6, 7]
+ *
+ * @since v0.3.0
+ */
+export 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
@@ -16,204 +39,463 @@ let init = (length, fn) => {
   iter(0, length)
 }
 
-let length = (list) => {
+/**
+ * Computes the length of the input list.
+ *
+ * @param list: The list to inspect
+ * @returns The number of elements in the list
+ *
+ * @since v0.1.0
+ * @history v0.2.0: Made the function tail-recursive
+ */
+export let length = list => {
   let rec iter = (len, list) => {
     match (list) {
       [] => len,
-      [_, ...rest] => iter(len + 1, rest)
-    }
-  }
-  iter(0, list)
-}
-
-let sum = list => {
-  let rec iter = (n, list) => {
-    match (list) {
-      [] => n,
-      [first, ...rest] => iter(n + first, rest)
+      [_, ...rest] => iter(len + 1, rest),
     }
   }
   iter(0, list)
 }
 
-let reverse = (list) => {
+/**
+ * Creates a new list with all elements in reverse order.
+ *
+ * @param list: The list to reverse
+ * @returns The new list
+ *
+ * @since v0.1.0
+ */
+export let reverse = list => {
   let rec iter = (list, acc) => {
     match (list) {
       [] => acc,
-      [first, ...rest] => iter(rest, [first, ...acc])
+      [first, ...rest] => iter(rest, [first, ...acc]),
     }
   }
   iter(list, [])
 }
 
-let rec append = (list1, list2) => {
+/**
+ * Creates a new list with the elements of the first list followed by
+ * the elements of the second list.
+ *
+ * @param list1: The list containing elements to appear first
+ * @param list2: The list containing elements to appear second
+ * @returns The new list containing elements from `list1` followed by elements from `list2`
+ *
+ * @since v0.1.0
+ */
+export let rec append = (list1, list2) => {
   match (list1) {
     [] => list2,
-    [first, ...rest] => [first, ...append(rest, list2)]
+    [first, ...rest] => [first, ...append(rest, list2)],
   }
 }
 
-let rec contains = (value, list) => {
+/**
+ * Checks if the value is an element of the input list.
+ * Uses the generic `==` structural equality operator.
+ *
+ * @param search: The value to compare
+ * @param list: The list to inspect
+ * @returns `true` if the value exists in the list or `false` otherwise
+ *
+ * @since v0.1.0
+ */
+export let rec contains = (search, list) => {
   match (list) {
     [] => false,
-    [first, ...rest] => (first == value) || contains(value, rest)
+    [first, ...rest] => first == search || contains(search, rest),
   }
 }
 
-let rec reduce = (fn, acc, list) => {
+/**
+ * Combines all elements of a list using a reducer function,
+ * starting from the "head", or left side, of the list.
+ *
+ * In `List.reduce(fn, initial, list)`, `fn` is called with
+ * an accumulator and each element of the list, and returns
+ * a new accumulator. The final value is the last accumulator
+ * returned. The accumulator starts with value `initial`.
+ *
+ * @param fn: The reducer function to call on each element, where the value returned will be the next accumulator value
+ * @param initial: The initial value to use for the accumulator on the first iteration
+ * @param list: The list to iterate
+ * @returns The final accumulator returned from `fn`
+ *
+ * @example List.reduce((a, b) => a + b, 0, [1, 2, 3]) // 6
+ *
+ * @since v0.2.0
+ * @history v0.1.0: Originally named `foldLeft`
+ * @history v0.2.0: Renamed to `reduce`
+ */
+export let rec reduce = (fn, initial, list) => {
   match (list) {
-    [] => acc,
-    [first, ...rest] => reduce(fn, fn(acc, first), rest)
+    [] => initial,
+    [first, ...rest] => reduce(fn, fn(initial, first), rest),
   }
 }
 
-let rec reduceRight = (fn, acc, list) => {
+/**
+ * Combines all elements of a list using a reducer function,
+ * starting from the "end", or right side, of the list.
+ *
+ * In `List.reduceRight(fn, initial, list)`, `fn` is called with
+ * each element of the list and an accumulator, and returns
+ * a new accumulator. The final value is the last accumulator
+ * returned. The accumulator starts with value `initial`.
+ *
+ * @param fn: The reducer function to call on each element, where the value returned will be the next accumulator value
+ * @param initial: The initial value to use for the accumulator on the first iteration
+ * @param list: The list to iterate
+ * @returns The final accumulator returned from `fn`
+ *
+ * @example List.reduceRight((a, b) => b ++ a, "", ["baz", "bar", "foo"]) // "foobarbaz"
+ *
+ * @since v0.2.0
+ * @history v0.1.0: Originally named `foldRight`
+ * @history v0.2.0: Renamed to `reduceRight`
+ */
+export let rec reduceRight = (fn, initial, list) => {
   match (list) {
-    [] => acc,
-    [first, ...rest] => fn(first, reduceRight(fn, acc, rest))
+    [] => initial,
+    [first, ...rest] => fn(first, reduceRight(fn, initial, rest)),
   }
 }
 
-let rec map = (fn, list) => {
+/**
+ * Produces a new list initialized with the results of a mapper function
+ * called on each element of the input list.
+ *
+ * @param fn: The mapper function to call on each element, where the value returned will be used to initialize the element in the new list
+ * @param list: The list to iterate
+ * @returns The new list with mapped values
+ *
+ * @since v0.1.0
+ */
+export let rec map = (fn, list) => {
   match (list) {
     [] => [],
-    [first, ...rest] => [fn(first), ...map(fn, rest)]
+    [first, ...rest] => [fn(first), ...map(fn, rest)],
   }
 }
 
-let mapi = (fn, list) => {
+/**
+ * Produces a new list initialized with the results of a mapper function
+ * called on each element of the input list and its index.
+ *
+ * @param fn: The mapper function to call on each element, where the value returned will be used to initialize the element in the new list
+ * @param list: The list to iterate
+ * @returns The new list with mapped values
+ *
+ * @since v0.1.0
+ */
+export let mapi = (fn, list) => {
   let rec iter = (fn, list, index) => {
     match (list) {
       [] => [],
-      [first, ...rest] => [fn(first, index), ...iter(fn, rest, index + 1)]
+      [first, ...rest] => [fn(first, index), ...iter(fn, rest, index + 1)],
     }
   }
   iter(fn, list, 0)
 }
 
-let rec flatMap = (fn, list) => {
+/**
+ * Produces a new list by calling a function on each element
+ * of the input list. Each iteration produces an intermediate
+ * list, which are all appended to produce a "flattened" list
+ * of all results.
+ *
+ * @param fn: The function to be called on each element, where the value returned will be a list that gets appended to the new list
+ * @param list: The list to iterate
+ * @returns The new list
+ *
+ * @since v0.2.0
+ */
+export let rec flatMap = (fn, list) => {
   match (list) {
     [] => [],
-    [first, ...rest] => append(fn(first), flatMap(fn, rest))
+    [first, ...rest] => append(fn(first), flatMap(fn, rest)),
   }
 }
 
-let every = (fn, list) => {
-  reduce((acc, value) => { acc && fn(value) }, true, list)
+/**
+ * Checks that the given condition is satisfied for all
+ * elements in the input list.
+ *
+ * @param fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
+ * @param list: The list to check
+ * @returns `true` if all elements satify the condition or `false` otherwise
+ *
+ * @since v0.1.0
+ */
+export let every = (fn, list) => {
+  reduce((acc, value) => {
+    acc && fn(value)
+  }, true, list)
 }
 
-let some = (fn, list) => {
-  reduce((acc, value) => { acc || fn(value) }, false, list)
+/**
+ * Checks that the given condition is satisfied **at least
+ * once** by an element in the input list.
+ *
+ * @param fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
+ * @param list: The list to iterate
+ * @returns `true` if one or more elements satify the condition or `false` otherwise
+ *
+ * @since v0.1.0
+ */
+export let some = (fn, list) => {
+  reduce((acc, value) => {
+    acc || fn(value)
+  }, false, list)
 }
 
-let rec forEach = (fn, list) => {
+/**
+ * Iterates a list, calling an iterator function on each element.
+ *
+ * @param fn: The iterator function to call with each element
+ * @param list: The list to iterate
+ *
+ * @since v0.1.0
+ */
+export let rec forEach = (fn, list) => {
   match (list) {
     [] => void,
     [first, ...rest] => {
-      fn(first)
+      fn(first): Void
       forEach(fn, rest)
-    }
+    },
   }
 }
 
-let forEachi = (fn, list) => {
+/**
+ * Iterates a list, calling an iterator function on each element.
+ * Also passes the index as the second argument to the function.
+ *
+ * @param fn: The iterator function to call with each element
+ * @param list: The list to iterate
+ *
+ * @since v0.1.0
+ */
+export let forEachi = (fn, list) => {
   let rec iter = (fn, list, index) => {
     match (list) {
       [] => void,
       [first, ...rest] => {
-        fn(first, index)
+        fn(first, index): Void
         iter(fn, rest, index + 1)
-      }
+      },
     }
   }
   iter(fn, list, 0)
 }
 
-let rec filter = (fn, list) => {
+/**
+ * Produces a new list by calling a function on each element of
+ * the input list and only including it in the result list if the element satisfies
+ * the condition.
+ *
+ * @param fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
+ * @param list: The list to iterate
+ * @returns The new list containing elements where `fn` returned `true`
+ *
+ * @since v0.1.0
+ */
+export let rec filter = (fn, list) => {
   match (list) {
     [] => [],
-    [first, ...rest] => if (fn(first)) [first, ...filter(fn, rest)] else filter(fn, rest)
+    [first, ...rest] =>
+      if (fn(first)) [first, ...filter(fn, rest)] else filter(fn, rest),
   }
 }
 
-let filteri = (fn, list) => {
+/**
+ * Produces a new list by calling a function on each element of
+ * the input list and only including it in the result list if the element satisfies
+ * the condition. Also passes the index to the function.
+ *
+ * @param fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
+ * @param list: The list to iterate
+ * @returns The new list containing elements where `fn` returned `true`
+ *
+ * @since v0.3.0
+ */
+export 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)
+      [first, ...rest] =>
+        if (fn(first, index)) [first, ...iter(fn, rest, index + 1)]
+        else iter(fn, rest, index + 1),
     }
   }
   iter(fn, list, 0)
 }
 
-let rec reject = (fn, list) => {
+/**
+ * Produces a new list by calling a function on each element of
+ * the input list and excluding it from the result list if the element satisfies
+ * the condition.
+ *
+ * @param fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
+ * @param list: The list to iterate
+ * @returns The new list containing elements where `fn` returned `false`
+ *
+ * @since v0.1.0
+ */
+export let rec reject = (fn, list) => {
   match (list) {
     [] => [],
-    [first, ...rest] => if (!fn(first)) [first, ...reject(fn, rest)] else reject(fn, rest)
+    [first, ...rest] =>
+      if (!fn(first)) [first, ...reject(fn, rest)] else reject(fn, rest),
   }
 }
 
-let head = (list) => {
+/**
+ * Provides `Some(element)` containing the first element, or "head", of
+ * the input list or `None` if the list is empty.
+ *
+ * @param list: The list to access
+ * @returns `Some(firstElement)` if the list has elements or `None` otherwise
+ *
+ * @since v0.2.0
+ * @history v0.1.0: Originally named `hd`
+ * @history v0.2.0: Renamed to `head`
+ * @history v0.3.0: Return type converted to `Option` type
+ */
+export let head = list => {
   match (list) {
     [] => None,
-    [first, ..._] => Some(first)
+    [first, ..._] => Some(first),
   }
 }
 
-let tail = (list) => {
+/**
+ * Provides `Some(tail)` containing all list items except the first element, or "tail", of
+ * the input list or `None` if the list is empty.
+ *
+ * @param list: The list to access
+ * @returns `Some(tail)` if the list has elements or `None` otherwise
+ *
+ * @since v0.2.0
+ * @history v0.1.0: Originally named `tl`
+ * @history v0.2.0: Renamed to `tail`
+ * @history v0.3.0: Return type converted to `Option` type
+ */
+export let tail = list => {
   match (list) {
     [] => None,
-    [_, ...rest] => Some(rest)
+    [_, ...rest] => Some(rest),
   }
 }
 
-let rec nth = (index, list) => {
+/**
+ * Provides `Some(element)` containing the element in the list at the specified index
+ * or `None` if the index is out-of-bounds or the list is empty.
+ *
+ * @param index: The index to access
+ * @param list: The list to access
+ * @returns `Some(element)` if the list contains an element at the index or `None` otherwise
+ *
+ * @since v0.1.0
+ * @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) => {
   if (index < 0) {
     None
   } else {
     match (list) {
       [] => None,
-      [first, ...rest] => if (index == 0) Some(first) else nth(index - 1, rest)
+      [first, ...rest] => if (index == 0) Some(first) else nth(index - 1, rest),
     }
   }
 }
 
-let rec flatten = (list) => {
+/**
+ * Flattens nested lists.
+ *
+ * @param list: The list to flatten
+ * @returns A new list containing all nested list elements combined
+ *
+ * @example List.flatten([[1, 2], [3, 4]]) // [1, 2, 3, 4]
+ *
+ * @since v0.1.0
+ */
+export let rec flatten = list => {
   match (list) {
     [] => [],
-    [first, ...rest] => append(first, flatten(rest))
+    [first, ...rest] => append(first, flatten(rest)),
   }
 }
 
-let rec insert = (value, index, list) => {
+/**
+ * Inserts a new value into a list at the specified index.
+ * Fails if the index is out-of-bounds.
+ *
+ * @param value: The value to insert
+ * @param index: The index to update
+ * @param list: The list to update
+ * @returns The new list
+ *
+ * @since v0.1.0
+ */
+export let rec insert = (value, index, list) => {
   if (index < 0) {
     fail "insert index cannot be a negative number"
   } else {
-    match(list) {
+    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)]
+      [first, ...rest] =>
+        if (index == 0) [value, ...list]
+        else [first, ...insert(value, index - 1, rest)],
     }
   }
 }
 
-let count = (fn, list) => {
+/**
+ * Counts the number of elements in a list that satisfy the given condition.
+ *
+ * @param fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
+ * @param list: The list to iterate
+ * @returns The total number of elements that satisfy the condition
+ *
+ * @since v0.1.0
+ * @history v0.2.0: Made the function tail-recursive
+ */
+export let count = (fn, list) => {
   let rec iter = (n, list) => {
     match (list) {
       [] => n,
-      [first, ...rest] => if (fn(first)) iter(n + 1, rest) else iter(n, rest)
+      [first, ...rest] => if (fn(first)) iter(n + 1, rest) else iter(n, rest),
     }
   }
   iter(0, list)
 }
 
-let part = (count, list) => {
+/**
+ * Split a list into two, with the first list containing the required number of elements.
+ * Fails if the input list doesn't contain at least the required amount of elements.
+ *
+ * @param count: The number of elements required
+ * @param list: The list to split
+ * @returns Two lists where the first contains exactly the required amount of elements and the second contains any remaining elements
+ *
+ * @since v0.1.0
+ */
+export let part = (count, list) => {
   if (count < 0) {
     fail "part count cannot be a negative number"
   } else {
     let rec iter = (list1, list2, count) => {
       match (list2) {
-        [] => 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) fail "part count is out-of-bounds" else (list1, list2),
+        [first, ...rest] =>
+          if (count > 0) iter([first, ...list1], rest, count - 1)
+          else (list1, list2),
       }
     }
     let (pt1, pt2) = iter([], list, count)
@@ -221,110 +503,238 @@ let part = (count, list) => {
   }
 }
 
-let rotate = (count, list) => {
-  let (beginning, end) = if (count >= 0) part(count, list) else part(length(list) + count, list)
+/**
+ * Rotates list elements by the specified amount to the left.
+ *
+ * If value is negative, list elements will be rotated by the
+ * specified amount to the right. See examples.
+ *
+ * Fails if the input list doesn't contain at least the required amount of elements.
+ *
+ * @param count: 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]
+ *
+ * @since v0.1.0
+ */
+export let rotate = (count, list) => {
+  let (beginning, end) = if (count >= 0) part(count, list)
+    else part(length(list) + count, list)
   append(end, beginning)
 }
 
-let unique = (list) => {
+/**
+ * Produces a new list with any duplicates removed.
+ * Uses the generic `==` structural equality operator.
+ *
+ * @param list: The list to filter
+ * @returns The new list with only unique values
+ *
+ * @since v0.2.0
+ * @history v0.1.0: Originally named `uniq`
+ * @history v0.2.0: Renamed to `unique`
+ */
+export 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])
+      [first, ...rest] =>
+        if (contains(first, acc)) iter(rest, acc)
+        else iter(rest, [first, ...acc]),
     }
   }
   iter(list, [])
 }
 
-let rec drop = (n, list) => {
-  if (n < 0) {
+/**
+ * Produces a new list with the specified number of elements removed from
+ * the beginning of the input list.
+ *
+ * Fails if the specified amount is a negative number.
+ *
+ * @param count: The amount of elements to remove
+ * @param list: The input list
+ * @returns The new list without the dropped elements
+ *
+ * @since v0.2.0
+ */
+export let rec drop = (count, list) => {
+  if (count < 0) {
     fail "number of items to drop cannot be a negative number"
   } else {
-    match ((n, list)) {
-      (_,[]) => [],
+    match ((count, list)) {
+      (_, []) => [],
       (n, _) when n == 0 => list,
-      (n, [first, ...rest]) => drop(n - 1, rest)
+      (n, [first, ...rest]) => drop(n - 1, rest),
     }
   }
 }
 
-let rec dropWhile = (fn, list) => {
+/**
+ * Produces a new list with the elements removed from the beginning
+ * of the input list until they no longer satisfy the given condition.
+ * Stops when the predicate function returns `false`.
+ *
+ * @param fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
+ * @param list: The input list
+ * @returns The new list without the dropped elements
+ *
+ * @since v0.2.0
+ */
+export let rec dropWhile = (fn, list) => {
   match (list) {
     [] => list,
-    [first, ...rest] => if (fn(first)) dropWhile(fn, rest) else list
+    [first, ...rest] => if (fn(first)) dropWhile(fn, rest) else list,
   }
 }
 
-let rec take = (n, list) => {
-  if (n < 0) {
+/**
+ * Produces a new list with–at most—the specified amount elements from
+ * the beginning of the input list.
+ *
+ * Fails if the specified amount is a negative number.
+ *
+ * @param count: The amount of elements to keep
+ * @param list: The input list
+ * @returns The new list containing the taken elements
+ *
+ * @since v0.2.0
+ */
+export let rec take = (count, list) => {
+  if (count < 0) {
     fail "number of items to take cannot be a negative number"
   } else {
-    match ((n, list)) {
+    match ((count, list)) {
       (_, []) => list,
       (n, _) when n == 0 => [],
-      (n, [first, ...rest]) => [first, ...take(n-1, rest)]
+      (n, [first, ...rest]) => [first, ...take(n - 1, rest)],
     }
   }
 }
 
-let rec takeWhile = (p, list) => {
+/**
+ * Produces a new list with elements from the beginning of the input list
+ * as long as they satisfy the given condition.
+ * Stops when the predicate function returns `false`.
+ *
+ * @param fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
+ * @param list: The input list
+ * @returns The new list containing the taken elements
+ *
+ * @since v0.2.0
+ */
+export let rec takeWhile = (fn, list) => {
   match (list) {
     [] => [],
-    [first, ...rest] => if (p(first)) [first, ...takeWhile(p, rest)] else []
+    [first, ...rest] => if (fn(first)) [first, ...takeWhile(fn, rest)] else [],
   }
 }
 
-let rec find = (fn, list) => {
+/**
+ * Finds the first element in a list that satifies the given condition.
+ *
+ * @param fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
+ * @param list: The list to search
+ * @returns `Some(element)` containing the first value found or `None` otherwise
+ *
+ * @since v0.2.0
+ * @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) => {
   match (list) {
     [] => None,
-    [first, ...rest] => if (fn(first)) Some(first) else find(fn, rest)
+    [first, ...rest] => if (fn(first)) Some(first) else find(fn, rest),
   }
 }
 
-let findIndex = (fn, list) => {
+/**
+ * Finds the first index in a list where the element satifies the given condition.
+ *
+ * @param fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
+ * @param list: The list to search
+ * @returns `Some(index)` containing the index of the first element found or `None` otherwise
+ *
+ * @since v0.2.0
+ * @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) => {
   let rec findItemIndex = (l, index) => {
     match (l) {
       [] => None,
-      [first, ...rest] => if (fn(first)) Some(index) else findItemIndex(rest, index + 1)
+      [first, ...rest] =>
+        if (fn(first)) Some(index) else findItemIndex(rest, index + 1),
     }
   }
   findItemIndex(list, 0)
 }
 
-let product = (a, b) => {
+/**
+ * Combines two lists into a Cartesian product of tuples containing
+ * all ordered pairs `(a, b)`.
+ *
+ * @param list1: The list to provide values for the first tuple element
+ * @param list2: The list to provide values for the second tuple element
+ * @returns The new list containing all pairs of `(a, b)`
+ *
+ * @since v0.2.0
+ */
+export let product = (list1, list2) => {
   let mut list = []
-  forEach((aItem) => {
-    forEach((bItem) => {
-     list = [(aItem, bItem), ...list]
-    },b)
-  }, a)
+  forEach(aItem => {
+    forEach(bItem => {
+      list = [(aItem, bItem), ...list]
+    }, list2)
+  }, list1)
   reverse(list)
 }
 
-let sub = (start, length, list) => {
+/**
+ * Provides the subset of a list given zero-based start index and amount of elements
+ * to include.
+ *
+ * Fails if the start index or amount of elements are negative numbers.
+ *
+ * @param start: The index of the list where the subset will begin (inclusive)
+ * @param length: The amount of elements to be included in the subset
+ * @param list: The input list
+ * @returns The subset of the list
+ *
+ * @since v0.2.0
+ */
+export let sub = (start, length, list) => {
   take(length, drop(start, list))
 }
 
-// Join the given list of strings with the given separator
-// @param separator: String - The separator to insert between items in the string
-// @param items: List<String> - The input strings
-// @returns String
-let join = (separator: String, items: List<String>) => {
+/**
+ * Combine the given list of strings into one string with the specified
+ * separator inserted between each item.
+ *
+ * @param separator: The separator to insert between elements
+ * @param list: The list to combine
+ * @returns The combined elements with the separator between each
+ *
+ * @since v0.4.0
+ */
+export let join = (separator: String, list: List<String>) => {
   let rec iter = (sep, acc, rem) => {
-    match(rem) {
+    match (rem) {
       [] => acc,
       [hd, ...tl] => {
-        let newAcc = match(acc) {
+        let newAcc = match (acc) {
           None => Some(hd),
-          Some(s) => Some(hd ++ sep ++ s)
+          Some(s) => Some(hd ++ sep ++ s),
         }
         iter(sep, newAcc, tl)
-      }
+      },
     }
   }
 
   // Reverse and reduce to take advantage of TCE
-  match(iter(separator, None, reverse(items))) {
+  match (iter(separator, None, reverse(list))) {
     None => "",
     Some(s) => s,
   }
@@ -332,29 +742,33 @@ let join = (separator: String, items: List<String>) => {
 
 /**
  * Reverses the first list and appends the second list to the end.
- * 
+ *
  * @param list1: The list to reverse
  * @param list2: The list to append
+ * @returns The new list
+ *
  * @since v0.4.5
  */
-let rec revAppend = (list1, list2) => { 
+export let rec revAppend = (list1, list2) => {
   match (list1) {
     [hd, ...tl] => revAppend(tl, [hd, ...list2]),
-    [] => list2
+    [] => 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 list: The list to be sorted
+ * @returns The sorted list
+ *
  * @since v0.4.5
  */
-let sort = (comp, list) => { 
+export let sort = (comp, list) => {
   let rec merge = (left, right, list) => {
-    match((left, right)){
+    match ((left, right)) {
       (_, []) => {
         revAppend(list, left)
       },
@@ -362,19 +776,19 @@ let sort = (comp, list) => {
         revAppend(list, right)
       },
       ([lhd, ...ltl], [rhd, ...rtl]) => {
-        if(comp(lhd, rhd) < 0){
-          merge(ltl, right, append([lhd],list))
-        }else{
+        if (comp(lhd, rhd) < 0) {
+          merge(ltl, right, append([lhd], list))
+        } else {
           merge(left, rtl, append([rhd], list))
         }
-      }
+      },
     }
   }
 
-  let rec mergesort = (list) => {
-    if(length(list) <= 1){
+  let rec mergesort = list => {
+    if (length(list) <= 1) {
       list
-    }else{
+    } else {
       let middle = length(list) / 2
       let (left, right) = part(middle, list)
       merge(mergesort(left), mergesort(right), [])