@grain/stdlib 0.4.4 → 0.5.0

package/map.gr

@@ -1,5 +1,9 @@
-// Standard library for Map (aka HashMap) functionality
-
+/**
+ * @module Map: A Map holds key-value pairs. Any value may be used as a key or value. Operations on a Map mutate the internal state, so it never needs to be re-assigned.
+ * @example import Map from "map"
+ *
+ * @since v0.2.0
+ */
 import List from "list"
 import Array from "array"
 import { hash } from "hash"
@@ -11,30 +15,49 @@ import { allocateArray } from "runtime/dataStructures"
 record Bucket<k, v> {
   mut key: k,
   mut value: v,
-  mut next: Option<Bucket<k, v>>
+  mut next: Option<Bucket<k, v>>,
 }
 
+/**
+ * @section Types: Type declarations included in the Map module.
+ */
+
 record Map<k, v> {
   mut size: Number,
-  mut buckets: Array<Option<Bucket<k, v>>>
-}
-
-// TODO: This could take an `eq` function to custom comparisons
-export let makeSized = (size) => {
-  let buckets = Array.make(size, None);
-  {
-    size: 0,
-    buckets
-  }
-}
-
+  mut buckets: Array<Option<Bucket<k, v>>>,
+}
+
+/**
+ * @section Values: Functions for working with Maps.
+ */
+
+/**
+ * Creates a new empty map with an initial storage of the given size. As values are added or removed, the internal storage may grow or shrink. Generally, you won't need to care about the storage size of your map and can use `Map.make()` instead.
+ *
+ * @param size: The initial storage size of the map
+ * @returns An empty map with the given initial storage size
+ *
+ * @since v0.2.0
+ */
+export let makeSized = size => { // TODO: This could take an `eq` function to custom comparisons
+  let buckets = Array.make(size, None)
+  { size: 0, buckets }
+}
+
+/**
+ * Creates a new, empty map.
+ *
+ * @returns An empty map
+ *
+ * @since v0.2.0
+ */
 export let make = () => {
   makeSized(16)
 }
 
 let getBucketIndex = (key, buckets) => {
-  let bucketsLength = Array.length(buckets);
-  let hashedKey = hash(key);
+  let bucketsLength = Array.length(buckets)
+  let hashedKey = hash(key)
   hashedKey % bucketsLength
 }
 
@@ -42,45 +65,45 @@ let rec copyNodeWithNewHash = (oldNode, next, tail) => {
   match (oldNode) {
     None => void,
     Some(node) => {
-      let idx = getBucketIndex(node.key, next);
-      let newNode = Some(node);
+      let idx = getBucketIndex(node.key, next)
+      let newNode = Some(node)
       match (tail[idx]) {
         None => {
-          next[idx] = newNode;
+          next[idx] = newNode
         },
         Some(tailNode) => {
           // If there's already a tail node, we add this to the end
-          tailNode.next = newNode;
-        }
+          tailNode.next = newNode
+        },
       }
       // Always place this node as the new tail
-      tail[idx] = newNode;
+      tail[idx] = newNode
       // Recurse with the next node
-      copyNodeWithNewHash(node.next, next, tail);
-    }
+      copyNodeWithNewHash(node.next, next, tail)
+    },
   }
 }
 
-let resize = (map) => {
-  let currentBuckets = map.buckets;
-  let currentSize = Array.length(currentBuckets);
-  let nextSize = currentSize * 2;
+let resize = map => {
+  let currentBuckets = map.buckets
+  let currentSize = Array.length(currentBuckets)
+  let nextSize = currentSize * 2
   if (nextSize >= currentSize) {
-    let nextBuckets = Array.make(nextSize, None);
+    let nextBuckets = Array.make(nextSize, None)
     // This tracks the tail nodes so we can set their `next` to None
-    let tailNodes = Array.make(nextSize, None);
-    map.buckets = nextBuckets;
-    Array.forEach((old) => {
-      copyNodeWithNewHash(old, nextBuckets, tailNodes);
-    }, currentBuckets);
-    Array.forEach((tail) => {
+    let tailNodes = Array.make(nextSize, None)
+    map.buckets = nextBuckets
+    Array.forEach(old => {
+      copyNodeWithNewHash(old, nextBuckets, tailNodes)
+    }, currentBuckets)
+    Array.forEach(tail => {
       match (tail) {
         None => void,
         Some(node) => {
-          node.next = None;
-        }
+          node.next = None
+        },
       }
-    }, tailNodes);
+    }, tailNodes)
   } else {
     void
   }
@@ -88,35 +111,44 @@ let resize = (map) => {
 
 let rec replaceInBucket = (key, value, node) => {
   if (key == node.key) {
-    node.value = value;
+    node.value = value
     false
   } else {
     match (node.next) {
       None => true,
-      Some(next) => replaceInBucket(key, value, next)
+      Some(next) => replaceInBucket(key, value, next),
     }
   }
 }
 
+/**
+ * Adds a new key-value pair to the map. If the key already exists in the map, the value is replaced.
+ *
+ * @param key: The unique key in the map
+ * @param value: The value to store
+ * @param map: The map to modify
+ *
+ * @since v0.2.0
+ */
 export let set = (key, value, map) => {
-  let buckets = map.buckets;
+  let buckets = map.buckets
   let idx = getBucketIndex(key, buckets)
-  let bucket = buckets[idx];
+  let bucket = buckets[idx]
   match (bucket) {
     None => {
-      buckets[idx] = Some({ key, value, next: None });
-      map.size = incr(map.size);
+      buckets[idx] = Some({ key, value, next: None })
+      map.size = incr(map.size)
     },
     Some(node) => {
       if (replaceInBucket(key, value, node)) {
-        buckets[idx] = Some({ key, value, next: bucket });
-        map.size = incr(map.size);
-      };
-    }
+        buckets[idx] = Some({ key, value, next: bucket })
+        map.size = incr(map.size)
+      }
+    },
   }
   // Resize if there are more than 2x the amount of nodes as buckets
-  if (map.size > (Array.length(buckets) * 2)) {
-    resize(map);
+  if (map.size > Array.length(buckets) * 2) {
+    resize(map)
   } else {
     void
   }
@@ -128,18 +160,27 @@ let rec valueFromBucket = (key, node) => {
   } else {
     match (node.next) {
       None => None,
-      Some(next) => valueFromBucket(key, next)
+      Some(next) => valueFromBucket(key, next),
     }
   }
 }
 
+/**
+ * Retrieves the value for the given key.
+ *
+ * @param key: The key to access
+ * @param map: The map to access
+ * @returns `Some(value)` if the key exists in the map or `None` otherwise
+ *
+ * @since v0.2.0
+ */
 export let get = (key, map) => {
-  let buckets = map.buckets;
-  let idx = getBucketIndex(key, buckets);
-  let bucket = buckets[idx];
+  let buckets = map.buckets
+  let idx = getBucketIndex(key, buckets)
+  let bucket = buckets[idx]
   match (bucket) {
     None => None,
-    Some(node) => valueFromBucket(key, node)
+    Some(node) => valueFromBucket(key, node),
   }
 }
 
@@ -149,18 +190,27 @@ let rec nodeInBucket = (key, node) => {
   } else {
     match (node.next) {
       None => false,
-      Some(next) => nodeInBucket(key, next)
+      Some(next) => nodeInBucket(key, next),
     }
   }
 }
 
+/**
+ * Determines if the map contains the given key. In such a case, it will always contain a value for the given key.
+ *
+ * @param key: The key to search for
+ * @param map: The map to search
+ * @returns `true` if the map contains the given key or `false` otherwise
+ *
+ * @since v0.2.0
+ */
 export let contains = (key, map) => {
-  let buckets = map.buckets;
-  let idx = getBucketIndex(key, buckets);
-  let bucket = buckets[idx];
+  let buckets = map.buckets
+  let idx = getBucketIndex(key, buckets)
+  let bucket = buckets[idx]
   match (bucket) {
     None => false,
-    Some(node) => nodeInBucket(key, node)
+    Some(node) => nodeInBucket(key, node),
   }
 }
 
@@ -169,130 +219,230 @@ let rec removeInBucket = (key, node) => {
     None => false,
     Some(next) => {
       if (key == next.key) {
-        node.next = next.next;
+        node.next = next.next
         true
       } else {
         removeInBucket(key, next)
       }
-    }
+    },
   }
 }
 
+/**
+ * Removes the given key from the map, which also removes the value. If the key pair doesn't exist, nothing happens.
+ *
+ * @param key: The key to remove
+ * @param map: The map to update
+ *
+ * @since v0.2.0
+ */
 export let remove = (key, map) => {
-  let buckets = map.buckets;
-  let idx = getBucketIndex(key, buckets);
-  let bucket = buckets[idx];
+  let buckets = map.buckets
+  let idx = getBucketIndex(key, buckets)
+  let bucket = buckets[idx]
   match (bucket) {
     None => void,
     Some(node) => {
       // If it is a top-level node, just replace with next node
       if (key == node.key) {
-        map.size = decr(map.size);
-        buckets[idx] = node.next;
+        map.size = decr(map.size)
+        buckets[idx] = node.next
       } else {
         if (removeInBucket(key, node)) {
-          map.size = decr(map.size);
+          map.size = decr(map.size)
         }
       }
-    }
+    },
   }
 }
 
+/**
+ * Updates a value in the map by calling an updater function that receives the previously stored value as an `Option` and returns the new value to be stored as an `Option`. If the key didn't exist previously, the value will be `None`. If `None` is returned from the updater function, the key-value pair is removed.
+ *
+ * @param key: The unique key in the map
+ * @param fn: The updater function
+ * @param map: The map to modify
+ *
+ * @since v0.3.0
+ */
 export let update = (key, fn, map) => {
-  let val = get(key, map);
+  let val = get(key, map)
   match (fn(val)) {
     Some(next) => set(key, next, map),
-    None => remove(key, map)
+    None => remove(key, map),
   }
 }
 
-export let size = (map) => {
+/**
+ * Provides the count of key-value pairs stored within the map.
+ *
+ * @param map: The map to inspect
+ * @returns The count of key-value pairs in the map
+ *
+ * @since v0.2.0
+ */
+export let size = map => {
   map.size
 }
 
-export let isEmpty = (map) => {
+/**
+ * Determines if the map contains no key-value pairs.
+ *
+ * @param map: The map to inspect
+ * @returns `true` if the given map is empty or `false` otherwise
+ *
+ * @since v0.2.0
+ */
+export let isEmpty = map => {
   size(map) == 0
 }
 
-export let clear = (map) => {
-  map.size = 0;
-  let buckets = map.buckets;
+/**
+ * Resets the map by removing all key-value pairs.
+ *
+ * @param map: The map to reset
+ *
+ * @since v0.2.0
+ */
+export let clear = map => {
+  map.size = 0
+  let buckets = map.buckets
   Array.forEachi((bucket, idx) => {
-    buckets[idx] = None;
-  }, buckets);
+    buckets[idx] = None
+  }, buckets)
 }
 
 let rec forEachBucket = (fn, node) => {
   match (node) {
     None => void,
     Some({ key, value, next }) => {
-      fn(key, value);
-      forEachBucket(fn, next);
-    }
+      fn(key, value): Void
+      forEachBucket(fn, next)
+    },
   }
 }
 
+/**
+ * Iterates the map, calling an iterator function with each key and value.
+ *
+ * @param fn: The iterator function to call with each key and value
+ * @param map: The map to iterate
+ *
+ * @since v0.2.0
+ * @history v0.5.0: Ensured the iterator function return type is always `Void`
+ */
 export let forEach = (fn, map) => {
-  let buckets = map.buckets;
-  Array.forEach((bucket) => {
+  let buckets = map.buckets
+  Array.forEach(bucket => {
     forEachBucket(fn, bucket)
-  }, buckets);
+  }, buckets)
 }
 
 let rec reduceEachBucket = (fn, node, acc) => {
   match (node) {
     None => acc,
     Some({ key, value, next }) =>
-      reduceEachBucket(fn, next, fn(acc, key, value))
+      reduceEachBucket(fn, next, fn(acc, key, value)),
   }
 }
 
+/**
+ * Combines all key-value pairs of a map using a reducer function.
+ *
+ * @param fn: The reducer function to call on each key and value, where the value returned will be the next accumulator value
+ * @param init: The initial value to use for the accumulator on the first iteration
+ * @param map: The map to iterate
+ * @returns The final accumulator returned from `fn`
+ *
+ * @since v0.2.0
+ */
 export let reduce = (fn, init, map) => {
-  let buckets = map.buckets;
-  let mut acc = init;
-  Array.forEach((bucket) => {
+  let buckets = map.buckets
+  let mut acc = init
+  Array.forEach(bucket => {
     acc = reduceEachBucket(fn, bucket, acc)
-  }, buckets);
+  }, buckets)
   acc
 }
 
-export let keys = (map) => {
+/**
+ * Enumerates all keys in the given map.
+ *
+ * @param map: The map to enumerate
+ * @returns A list containing all keys from the given map
+ *
+ * @since v0.2.0
+ */
+export let keys = map => {
   reduce((list, key, _value) => [key, ...list], [], map)
 }
 
-export let values = (map) => {
+/**
+ * Enumerates all values in the given map.
+ *
+ * @param map: The map to enumerate
+ * @returns A list containing all values from the given map
+ *
+ * @since v0.2.0
+ */
+export let values = map => {
   reduce((list, _key, value) => [value, ...list], [], map)
 }
 
-export let toList = (map) => {
+/**
+ * Enumerates all key-value pairs in the given map.
+ *
+ * @param map: The map to enumerate
+ * @returns A list containing all key-value pairs from the given map
+ *
+ * @since v0.2.0
+ */
+export let toList = map => {
   reduce((list, key, value) => [(key, value), ...list], [], map)
 }
 
-export let fromList = (list) => {
-  let map = make();
-  List.forEach((pair) => {
-    let (key, value) = pair;
-    set(key, value, map);
-  }, list);
+/**
+ * Creates a map from a list.
+ *
+ * @param list: The list to convert
+ * @returns A map containing all key-value pairs from the list
+ *
+ * @since v0.2.0
+ */
+export let fromList = list => {
+  let map = make()
+  List.forEach(pair => {
+    let (key, value) = pair
+    set(key, value, map)
+  }, list)
   map
 }
 
-let setInArray = (array) => {
+let setInArray = array => {
   @disableGC
   let rec iter = (i, key, value) => {
     array[i] = (key, value)
     // no decRef on key and value, since they are stored in array
     Memory.decRef(WasmI32.fromGrain(iter))
+    Memory.incRef(WasmI32.fromGrain((+)))
+    Memory.incRef(WasmI32.fromGrain(i))
     i + 1
   }
   iter
 }
 
+/**
+ * Converts a map into an array of its key-value pairs.
+ *
+ * @param map: The map to convert
+ * @returns An array containing all key-value pairs from the given map
+ *
+ * @since v0.2.0
+ */
 @disableGC
-export let rec toArray = (map) => {
+export let rec toArray = map => {
   let length = WasmI32.shrS(WasmI32.fromGrain(map.size), 1n)
-  // TODO(#783): Removing parens around Array<a> causes a parse error
-  let array = WasmI32.toGrain(allocateArray(length)): (Array<a>)
+  let array = WasmI32.toGrain(allocateArray(length)): Array<a>
   Memory.incRef(WasmI32.fromGrain(setInArray))
   Memory.incRef(WasmI32.fromGrain(array))
   let setInArray = setInArray(array)
@@ -306,33 +456,64 @@ export let rec toArray = (map) => {
   array
 }
 
-export let fromArray = (array) => {
-  let map = make();
-  Array.forEach((pair) => {
-    let (key, value) = pair;
-    set(key, value, map);
-  }, array);
+/**
+ * Creates a map from an array.
+ *
+ * @param array: The array to convert
+ * @returns A map containing all key-value pairs from the array
+ *
+ * @since v0.2.0
+ */
+export let fromArray = array => {
+  let map = make()
+  Array.forEach(pair => {
+    let (key, value) = pair
+    set(key, value, map)
+  }, array)
   map
 }
 
+/**
+ * Removes key-value pairs from a map where a predicate function returns `false`.
+ *
+ * @param fn: The predicate function to indicate which key-value pairs to remove from the map, where returning `false` indicates the key-value pair should be removed
+ * @param map: The map to iterate
+ *
+ * @since v0.2.0
+ */
 export let filter = (predicate, map) => {
-  let keysToRemove = reduce((list, key, value) =>
-    if (!predicate(key, value)) {
-      [key, ...list]
-    } else {
-      list
-    }, [], map);
-  List.forEach((key) => {
-    remove(key, map);
-  }, keysToRemove);
-}
-
+  let keysToRemove = reduce((list, key, value) => if (!predicate(key, value)) {
+    [key, ...list]
+  } else {
+    list
+  }, [], map)
+  List.forEach(key => {
+    remove(key, map)
+  }, keysToRemove)
+}
+
+/**
+ * Removes key-value pairs from a map where a predicate function returns `true`.
+ *
+ * @param fn: The predicate function to indicate which key-value pairs to remove from the map, where returning `true` indicates the key-value pair should be removed
+ * @param map: The map to iterate
+ *
+ * @since v0.2.0
+ */
 export let reject = (predicate, map) => {
   filter((key, value) => !predicate(key, value), map)
 }
 
 // TODO: Should return a Record type instead of a Tuple
 // Waiting on https://github.com/grain-lang/grain/issues/190
-export let getInternalStats = (map) => {
+/**
+ * Provides data representing the internal state state of the map.
+ *
+ * @param map: The map to inspect
+ * @returns The internal state of the map
+ *
+ * @since v0.2.0
+ */
+export let getInternalStats = map => {
   (map.size, Array.length(map.buckets))
 }