@grain/stdlib 0.6.6 → 0.7.0

package/list.gr

@@ -13,6 +13,24 @@ from "runtime/unsafe/memory" include Memory
 from "runtime/unsafe/wasmi32" include WasmI32
 from "runtime/dataStructures" include DataStructures
 
+/**
+ * Creates a new list with all elements in reverse order.
+ *
+ * @param list: The list to reverse
+ * @returns The new list
+ *
+ * @since v0.1.0
+ */
+provide let reverse = list => {
+  let rec revHelp = (list, acc) => {
+    match (list) {
+      [] => acc,
+      [first, ...rest] => revHelp(rest, [first, ...acc]),
+    }
+  }
+  revHelp(list, [])
+}
+
 /**
  * Creates a new list of the specified length where each element is
  * initialized with the result of an initializer function. The initializer
@@ -27,17 +45,18 @@ from "runtime/dataStructures" include DataStructures
  * @since v0.3.0
  */
 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
-  let rec iter = (idx, length) => {
-    if (idx >= length) {
-      []
-    } else {
-      [fn(idx), ...iter(idx + 1, length)]
+  if (length < 2048) {
+    // For small lists, use a faster non-tail-recursive version
+    let rec iter = (idx, length) => {
+      if (idx >= length) [] else [fn(idx), ...iter(idx + 1, length)]
+    }
+    iter(0, length)
+  } else {
+    let rec iter = (idx, length, acc) => {
+      if (idx >= length) acc else iter(idx + 1, length, [fn(idx), ...acc])
     }
+    reverse(iter(0, length, []))
   }
-  iter(0, length)
 }
 
 /**
@@ -74,24 +93,6 @@ provide let isEmpty = 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
- */
-provide let reverse = list => {
-  let rec iter = (list, acc) => {
-    match (list) {
-      [] => acc,
-      [first, ...rest] => iter(rest, [first, ...acc]),
-    }
-  }
-  iter(list, [])
-}
-
 /**
  * Creates a new list with the elements of the first list followed by
  * the elements of the second list.
@@ -217,6 +218,56 @@ provide let mapi = (fn, list) => {
   iter(fn, list, 0)
 }
 
+/**
+ * Produces a new list initialized with the results of a mapper function
+ * called on each element of the input list.
+ * The mapper function can return `None` to exclude the element from the new 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 filtered mapped values
+ *
+ * @example List.filterMap(x => if (x % 2 == 0) Some(toString(x)) else None, [1, 2, 3, 4]) == ["2", "4"]
+ *
+ * @since v0.7.0
+ */
+provide let rec filterMap = (fn, list) => {
+  match (list) {
+    [] => [],
+    [first, ...rest] => match (fn(first)) {
+      Some(v) => [v, ...filterMap(fn, rest)],
+      None => filterMap(fn, rest),
+    },
+  }
+}
+
+/**
+ * Produces a new list initialized with the results of a mapper function
+ * called on each element of the input list and its index.
+ * The mapper function can return `None` to exclude the element from the new 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 filtered mapped values
+ *
+ * @example List.filterMapi((x, i) => if (x % 2 == 0) Some(toString(x)) else None, [1, 2, 3, 4]) == ["2", "4"]
+ * @example List.filterMapi((x, i) => if (i == 0) Some(toString(x)) else None, [1, 2, 3, 4]) == ["1"]
+ *
+ * @since v0.7.0
+ */
+provide let filterMapi = (fn, list) => {
+  let rec iter = (fn, list, index) => {
+    match (list) {
+      [] => [],
+      [first, ...rest] => match (fn(first, index)) {
+        Some(v) => [v, ...iter(fn, rest, index + 1)],
+        None => iter(fn, rest, index + 1),
+      },
+    }
+  }
+  iter(fn, list, 0)
+}
+
 /**
  * Produces a new list by calling a function on each element
  * of the input list. Each iteration produces an intermediate
@@ -242,7 +293,7 @@ provide let rec flatMap = (fn, 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
+ * @returns `true` if all elements satisfy the condition or `false` otherwise
  *
  * @since v0.1.0
  */
@@ -260,7 +311,7 @@ provide let rec every = (fn, 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
+ * @returns `true` if one or more elements satisfy the condition or `false` otherwise
  *
  * @since v0.1.0
  */
@@ -769,7 +820,7 @@ provide let rec takeWhile = (fn, list) => {
 }
 
 /**
- * Finds the first element in a list that satifies the given condition.
+ * Finds the first element in a list that satisfies 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
@@ -787,7 +838,7 @@ provide let rec find = (fn, list) => {
 }
 
 /**
- * Finds the first index in a list where the element satifies the given condition.
+ * Finds the first index in a list where the element satisfies 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
@@ -808,6 +859,31 @@ provide let findIndex = (fn, list) => {
   findItemIndex(list, 0)
 }
 
+/**
+ * Finds the first element in a list that satisfies the given condition and
+ * returns the result of applying a mapper function to it.
+ *
+ * @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(mapped)` containing the first value found with the given mapping or `None` otherwise
+ *
+ * @example
+ * let jsonObject = [(1, 'a'), (2, 'b'), (1, 'c')]
+ * let getItem = (key, obj) => List.findMap(((k, v)) => if (k == key) Some(v) else None, obj)
+ * assert getItem(1, jsonObject) == Some('a')
+ *
+ * @since v0.7.0
+ */
+provide let rec findMap = (fn, list) => {
+  match (list) {
+    [] => None,
+    [first, ...rest] => match (fn(first)) {
+      None => findMap(fn, rest),
+      Some(v) => Some(v),
+    },
+  }
+}
+
 /**
  * Combines two lists into a Cartesian product of tuples containing
  * all ordered pairs `(a, b)`.
@@ -972,3 +1048,224 @@ provide let sort = (compare=compare, list) => {
 
   mergesort(list)
 }
+
+/**
+ * Utilities for working with lists of key-key value pairs.
+ *
+ * @example
+ * let data = [
+ *  ("name", "Alice"),
+ *  ("age", "30"),
+ * ]
+ * assert List.Associative.get("name", data) == Some("Alice")
+ *
+ * @since v0.7.0
+ */
+provide module Associative {
+  /**
+   * Checks if the given key is present in the list of key-value pairs.
+   *
+   * @param key: The key to search for
+   * @param list: The list of key-value pairs
+   *
+   * @returns `true` if the key is found or `false` otherwise
+   *
+   * @example
+   * let data = [
+   *   ("name", "Alice"),
+   *   ("age", "30"),
+   * ]
+   * assert List.Associative.has("name", data) == true
+   * @example List.Associative.has("age", []) == false
+   *
+   * @since v0.7.0
+   */
+  provide let rec has = (key, list) => {
+    match (list) {
+      [] => false,
+      [(k, _), ...rest] when key == k => true,
+      [_, ...rest] => has(key, rest),
+    }
+  }
+
+  /**
+   * Retrieves the first value in the list of key-value pairs that matches the given key.
+   *
+   * @param key: The key to search for
+   * @param list: The list of key-value pairs
+   *
+   * @returns `Some(value)` if the key is found or `None` otherwise
+   *
+   * @example
+   * let data = [
+   *  ("name", "Alice"),
+   *  ("name", "Bob"),
+   *  ("age", "30"),
+   * ]
+   * assert List.Associative.get("name", data) == Some("Alice")
+   *
+   * @example List.Associative.get("age", []) == None
+   *
+   * @since v0.7.0
+   */
+  provide let rec get = (key, list) => {
+    match (list) {
+      [] => None,
+      [(k, v), ...rest] when key == k => Some(v),
+      [_, ...rest] => get(key, rest),
+    }
+  }
+
+  /**
+   * Retrieves all values in the list of key-value pairs that match the given key.
+   *
+   * @param key: The key to search for
+   * @param list: The list of key-value pairs
+   *
+   * @returns An array of values matching the given key
+   *
+   * @example
+   * let data = [
+   *  ("name", "Alice"),
+   *  ("name", "Bob"),
+   *  ("age", "30"),
+   * ]
+   * assert List.Associative.getAll("name", data) == [
+   *   "Alice",
+   *   "Bob"
+   * ]
+   *
+   * @example List.Associative.getAll("age", []) == []
+   *
+   * @since v0.7.0
+   */
+  provide let rec getAll = (key, list) => {
+    match (list) {
+      [] => [],
+      [(k, v), ...rest] when key == k => [v, ...getAll(key, rest)],
+      [_, ...rest] => getAll(key, rest),
+    }
+  }
+
+  /**
+   * Creates a new list with the first value in the list of key-value pairs that matches the key replaced.
+   * If the key is not found the item is appended to the list.
+   *
+   * @param key: The key to replace
+   * @param value: The new value to set
+   * @param list: The list of key-value pairs
+   *
+   * @returns A new list with the key-value pair replaced
+   *
+   * @example
+   * let data = [
+   *  ("name", "Alice"),
+   *  ("name", "Bob"),
+   *  ("age", "30"),
+   * ]
+   * assert List.Associative.set("name", "Charlie", data) == [("name", "Charlie"), ("name", "Bob"), ("age", "30")]
+   *
+   * @example List.Associative.set("age", "30", [("name", "Alice")]) == [("name", "Alice"), ("age", "30")]
+   *
+   * @since v0.7.0
+   */
+  provide let rec set = (key, value, list) => {
+    match (list) {
+      [] => [(key, value)],
+      [(k, _), ...rest] when key == k => [(k, value), ...rest],
+      [first, ...rest] => [first, ...set(key, value, rest)],
+    }
+  }
+
+  let rec setAllHelp = (key, value, list, hitMatch=false) => {
+    match (list) {
+      [] when !hitMatch => [(key, value)],
+      [] => [],
+      [(k, _), ...rest] when key == k =>
+        [(k, value), ...setAllHelp(key, value, rest, hitMatch=true)],
+      [first, ...rest] =>
+        [first, ...setAllHelp(key, value, rest, hitMatch=hitMatch)],
+    }
+  }
+  /**
+   * Creates a new list with all values in the list of key-value pairs that match the key replaced.
+   * If the key is not found the item is appended to the list.
+   *
+   * @param key: The key to replace
+   * @param value: The new value to set
+   * @param list: The list of key-value pairs
+   *
+   * @returns A new list with the key-value pairs replaced
+   *
+   * @example
+   * let data = [
+   *  ("name", "Alice"),
+   *  ("name", "Bob"),
+   *  ("age", "30"),
+   * ]
+   * assert List.Associative.setAll("name", "Charlie", data) == [("name", "Charlie"), ("name", "Charlie"), ("age", "30")]
+   *
+   * @example List.Associative.setAll("age", "30", [("name", "Alice")]) == [("name", "Alice"), ("age", "30")]
+   *
+   * @since v0.7.0
+   */
+  provide let setAll = (key, value, list) => setAllHelp(key, value, list)
+
+  /**
+   * Creates a new list with the first value in the list of key-value pairs that matches the key removed.
+   * If the key is not found, the list is returned unchanged.
+   *
+   * @param key: The key to remove
+   * @param list: The list of key-value pairs
+   *
+   * @returns The new list with the key-value pair removed
+   *
+   * @example
+   * let data = [
+   *   ("name", "Alice"),
+   *   ("name", "Bob"),
+   *   ("age", "30"),
+   * ]
+   * assert List.Associative.remove("name", data) == [("name", "Bob"), ("age", "30")]
+   *
+   * @example List.Associative.remove("age", [("name", "Alice")]) == []
+   *
+   * @since v0.7.0
+   */
+  provide let rec remove = (key, list) => {
+    match (list) {
+      [] => [],
+      [(k, v), ...rest] when key == k => rest,
+      [first, ...rest] => [first, ...remove(key, rest)],
+    }
+  }
+
+  /**
+   * Creates a new list with all values in the list of key-value pairs matching the key removed.
+   * If the key is not found, the list is returned unchanged.
+   *
+   * @param key: The key to remove
+   * @param list: The list of key-value pairs
+   *
+   * @returns The new list with the key-value pairs removed
+   *
+   * @example
+   * let data = [
+   *   ("name", "Alice"),
+   *   ("name", "Bob"),
+   *   ("age", "30"),
+   * ]
+   * assert List.Associative.removeAll("name", data) == [("age", "30")]
+   *
+   * @example List.Associative.removeAll("age", [("name", "Alice")]) == [("name", "Alice")]
+   *
+   * @since v0.7.0
+   */
+  provide let rec removeAll = (key, list) => {
+    match (list) {
+      [] => [],
+      [(k, v), ...rest] when key == k => removeAll(key, rest),
+      [first, ...rest] => [first, ...removeAll(key, rest)],
+    }
+  }
+}