@grain/stdlib 0.4.4 → 0.5.0

package/set.gr

@@ -10,29 +10,34 @@ import { hash } from "hash"
 
 record Bucket<t> {
   mut key: t,
-  mut next: Option<Bucket<t>>
+  mut next: Option<Bucket<t>>,
 }
 
+/**
+ * @section Types: Type declarations included in the Set module.
+ */
+
 record Set<k> {
   mut size: Number,
-  mut buckets: Array<Option<Bucket<k>>>
+  mut buckets: Array<Option<Bucket<k>>>,
 }
 
+/**
+ * @section Values: Functions for working with Sets.
+ */
+
 // TODO: This could take an `eq` function to custom comparisons
 /**
- * Creates a new empty set with an initial storage of the given length. As values are added or removed, the length may grow or shrink. Generally, you won't need to care about the length of your set and can use `Set.make()` instead.
+ * Creates a new empty set 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 set and can use `Set.make()` instead.
  *
- * @param storageLength: The initial storage length of the set
- * @returns An empty set with the given initial storage length
+ * @param size: The initial storage size of the set
+ * @returns An empty set with the given initial storage size
  * 
  * @since 0.3.0
  */
-export let makeSized = (storageLength) => {
-  let buckets = Array.make(storageLength, None);
-  {
-    size: 0,
-    buckets
-  }
+export let makeSized = size => {
+  let buckets = Array.make(size, None)
+  { size: 0, buckets }
 }
 /**
  * Creates a new, empty set.
@@ -46,8 +51,8 @@ export let make = () => {
 }
 
 let getBucketIndex = (key, buckets) => {
-  let bucketsLength = Array.length(buckets);
-  let hashedKey = hash(key);
+  let bucketsLength = Array.length(buckets)
+  let hashedKey = hash(key)
   hashedKey % bucketsLength
 }
 
@@ -55,45 +60,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 = (set) => {
-  let currentBuckets = set.buckets;
-  let currentSize = Array.length(currentBuckets);
-  let nextSize = currentSize * 2;
+let resize = set => {
+  let currentBuckets = set.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);
-    set.buckets = nextBuckets;
-    Array.forEach((old) => {
-      copyNodeWithNewHash(old, nextBuckets, tailNodes);
-    }, currentBuckets);
-    Array.forEach((tail) => {
+    let tailNodes = Array.make(nextSize, None)
+    set.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
   }
@@ -105,7 +110,7 @@ let rec nodeInBucket = (key, node) => {
   } else {
     match (node.next) {
       None => false,
-      Some(next) => nodeInBucket(key, next)
+      Some(next) => nodeInBucket(key, next),
     }
   }
 }
@@ -119,24 +124,24 @@ let rec nodeInBucket = (key, node) => {
  * @since 0.3.0
  */
 export let add = (key, set) => {
-  let buckets = set.buckets;
+  let buckets = set.buckets
   let idx = getBucketIndex(key, buckets)
-  let bucket = buckets[idx];
+  let bucket = buckets[idx]
   match (bucket) {
     None => {
-      buckets[idx] = Some({ key, next: None });
-      set.size = incr(set.size);
+      buckets[idx] = Some({ key, next: None })
+      set.size = incr(set.size)
     },
     Some(node) => {
       if (!nodeInBucket(key, node)) {
-        buckets[idx] = Some({ key, next: bucket });
-        set.size = incr(set.size);
-      };
-    }
+        buckets[idx] = Some({ key, next: bucket })
+        set.size = incr(set.size)
+      }
+    },
   }
   // Resize if there are more than 2x the amount of nodes as buckets
-  if (set.size > (Array.length(buckets) * 2)) {
-    resize(set);
+  if (set.size > Array.length(buckets) * 2) {
+    resize(set)
   } else {
     void
   }
@@ -152,12 +157,12 @@ export let add = (key, set) => {
  * @since 0.3.0
  */
 export let contains = (key, set) => {
-  let buckets = set.buckets;
-  let idx = getBucketIndex(key, buckets);
-  let bucket = buckets[idx];
+  let buckets = set.buckets
+  let idx = getBucketIndex(key, buckets)
+  let bucket = buckets[idx]
   match (bucket) {
     None => false,
-    Some(node) => nodeInBucket(key, node)
+    Some(node) => nodeInBucket(key, node),
   }
 }
 
@@ -166,12 +171,12 @@ 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)
       }
-    }
+    },
   }
 }
 
@@ -184,34 +189,34 @@ let rec removeInBucket = (key, node) => {
  * @since 0.3.0
  */
 export let remove = (key, set) => {
-  let buckets = set.buckets;
-  let idx = getBucketIndex(key, buckets);
-  let bucket = buckets[idx];
+  let buckets = set.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) {
-        set.size = decr(set.size);
-        buckets[idx] = node.next;
+        set.size = decr(set.size)
+        buckets[idx] = node.next
       } else {
         if (removeInBucket(key, node)) {
-          set.size = decr(set.size);
+          set.size = decr(set.size)
         }
       }
-    }
+    },
   }
 }
 
 /**
- * Returns the number of values within the set.
+ * Provides the count of values within the set.
  *
  * @param set: The set to inspect
- * @returns The number of elements in the set
+ * @returns The count of elements in the set
  * 
  * @since 0.3.0
  */
-export let size = (set) => {
+export let size = set => {
   set.size
 }
 
@@ -223,7 +228,7 @@ export let size = (set) => {
  * 
  * @since 0.3.0
  */
-export let isEmpty = (set) => {
+export let isEmpty = set => {
   size(set) == 0
 }
 
@@ -234,21 +239,21 @@ export let isEmpty = (set) => {
  * 
  * @since 0.3.0
  */
-export let clear = (set) => {
-  set.size = 0;
-  let buckets = set.buckets;
+export let clear = set => {
+  set.size = 0
+  let buckets = set.buckets
   Array.forEachi((bucket, idx) => {
-    buckets[idx] = None;
-  }, buckets);
+    buckets[idx] = None
+  }, buckets)
 }
 
 let rec forEachBucket = (fn, node) => {
   match (node) {
     None => void,
     Some({ key, next }) => {
-      fn(key);
-      forEachBucket(fn, next);
-    }
+      fn(key): Void
+      forEachBucket(fn, next)
+    },
   }
 }
 
@@ -259,19 +264,19 @@ let rec forEachBucket = (fn, node) => {
  * @param set: The set to iterate
  * 
  * @since 0.3.0
+ * @history v0.5.0: Ensured the iterator function return type is always `Void`
  */
 export let forEach = (fn, set) => {
-  let buckets = set.buckets;
-  Array.forEach((bucket) => {
+  let buckets = set.buckets
+  Array.forEach(bucket => {
     forEachBucket(fn, bucket)
-  }, buckets);
+  }, buckets)
 }
 
 let rec reduceEachBucket = (fn, node, acc) => {
   match (node) {
     None => acc,
-    Some({ key, next }) =>
-      reduceEachBucket(fn, next, fn(acc, key))
+    Some({ key, next }) => reduceEachBucket(fn, next, fn(acc, key)),
   }
 }
 
@@ -286,11 +291,11 @@ let rec reduceEachBucket = (fn, node, acc) => {
  * @since 0.3.0
  */
 export let reduce = (fn, init, set) => {
-  let buckets = set.buckets;
-  let mut acc = init;
-  Array.forEach((bucket) => {
+  let buckets = set.buckets
+  let mut acc = init
+  Array.forEach(bucket => {
     acc = reduceEachBucket(fn, bucket, acc)
-  }, buckets);
+  }, buckets)
   acc
 }
 
@@ -303,15 +308,14 @@ export let reduce = (fn, init, set) => {
  * @since 0.3.0
  */
 export let filter = (predicate, set) => {
-  let keysToRemove = reduce((list, key) =>
-    if (!predicate(key)) {
-      [key, ...list]
-    } else {
-      list
-    }, [], set);
-  List.forEach((key) => {
-    remove(key, set);
-  }, keysToRemove);
+  let keysToRemove = reduce((list, key) => if (!predicate(key)) {
+    [key, ...list]
+  } else {
+    list
+  }, [], set)
+  List.forEach(key => {
+    remove(key, set)
+  }, keysToRemove)
 }
 
 /**
@@ -323,7 +327,7 @@ export let filter = (predicate, set) => {
  * @since 0.3.0
  */
 export let reject = (predicate, set) => {
-  filter((key) => !predicate(key), set)
+  filter(key => !predicate(key), set)
 }
 
 /**
@@ -334,7 +338,7 @@ export let reject = (predicate, set) => {
  * 
  * @since 0.3.0
  */
-export let toList = (set) => {
+export let toList = set => {
   reduce((list, key) => [key, ...list], [], set)
 }
 
@@ -346,11 +350,11 @@ export let toList = (set) => {
  * 
  * @since 0.3.0
  */
-export let fromList = (list) => {
-  let set = make();
-  List.forEach((key) => {
-    add(key, set);
-  }, list);
+export let fromList = list => {
+  let set = make()
+  List.forEach(key => {
+    add(key, set)
+  }, list)
   set
 }
 
@@ -362,7 +366,7 @@ export let fromList = (list) => {
  * 
  * @since 0.3.0
  */
-export let toArray = (set) => {
+export let toArray = set => {
   Array.fromList(toList(set))
 }
 
@@ -374,11 +378,11 @@ export let toArray = (set) => {
  * 
  * @since 0.3.0
  */
-export let fromArray = (array) => {
-  let set = make();
-  Array.forEach((key) => {
-    add(key, set);
-  }, array);
+export let fromArray = array => {
+  let set = make()
+  Array.forEach(key => {
+    add(key, set)
+  }, array)
   set
 }
 
@@ -392,13 +396,13 @@ export let fromArray = (array) => {
  * @since 0.3.0
  */
 export let union = (set1, set2) => {
-  let set = make();
-  forEach((key) => {
-    add(key, set);
+  let set = make()
+  forEach(key => {
+    add(key, set)
   }, set1)
-  forEach((key) => {
-    add(key, set);
-  }, set2);
+  forEach(key => {
+    add(key, set)
+  }, set2)
   set
 }
 
@@ -412,17 +416,17 @@ export let union = (set1, set2) => {
  * @since 0.3.0
  */
 export let diff = (set1, set2) => {
-  let set = make();
-  forEach((key) => {
+  let set = make()
+  forEach(key => {
     if (!contains(key, set2)) {
-      add(key, set);
+      add(key, set)
     }
   }, set1)
-  forEach((key) => {
+  forEach(key => {
     if (!contains(key, set1)) {
-      add(key, set);
+      add(key, set)
     }
-  }, set2);
+  }, set2)
   set
 }
 
@@ -436,17 +440,17 @@ export let diff = (set1, set2) => {
  * @since 0.3.0
  */
 export let intersect = (set1, set2) => {
-  let set = make();
-  forEach((key) => {
+  let set = make()
+  forEach(key => {
     if (contains(key, set2)) {
-      add(key, set);
+      add(key, set)
     }
   }, set1)
-  forEach((key) => {
+  forEach(key => {
     if (contains(key, set1)) {
-      add(key, set);
+      add(key, set)
     }
-  }, set2);
+  }, set2)
   set
 }
 
@@ -460,6 +464,6 @@ export let intersect = (set1, set2) => {
  * 
  * @since 0.3.0
  */
-export let getInternalStats = (set) => {
+export let getInternalStats = set => {
   (set.size, Array.length(set.buckets))
 }

package/set.md

@@ -13,24 +13,20 @@ No other changes yet.
 import Set from "set"
 ```
 
-### Set.**Bucket**
+## Types
 
-```grain
-record Bucket<t> {
-  key: t,
-  next: Option<Bucket<t>>,
-}
-```
+Type declarations included in the Set module.
 
 ### Set.**Set**
 
 ```grain
-record Set<k> {
-  size: Number,
-  buckets: Array<Option<Bucket<k>>>,
-}
+type Set<k>
 ```
 
+## Values
+
+Functions for working with Sets.
+
 ### Set.**makeSized**
 
 <details disabled>
@@ -42,19 +38,19 @@ No other changes yet.
 makeSized : Number -> Set<a>
 ```
 
-Creates a new empty set with an initial storage of the given length. As values are added or removed, the length may grow or shrink. Generally, you won't need to care about the length of your set and can use `Set.make()` instead.
+Creates a new empty set 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 set and can use `Set.make()` instead.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`storageLength`|`Number`|The initial storage length of the set|
+|`size`|`Number`|The initial storage size of the set|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Set<a>`|An empty set with the given initial storage length|
+|`Set<a>`|An empty set with the given initial storage size|
 
 ### Set.**make**
 
@@ -152,7 +148,7 @@ No other changes yet.
 size : Set<a> -> Number
 ```
 
-Returns the number of values within the set.
+Provides the count of values within the set.
 
 Parameters:
 
@@ -164,7 +160,7 @@ Returns:
 
 |type|description|
 |----|-----------|
-|`Number`|The number of elements in the set|
+|`Number`|The count of elements in the set|
 
 ### Set.**isEmpty**
 
@@ -212,13 +208,20 @@ Parameters:
 
 ### Set.**forEach**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.3.0</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.3.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>next</code></td><td>Ensured the iterator function return type is always `Void`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-forEach : ((a -> b), Set<a>) -> Void
+forEach : ((a -> Void), Set<a>) -> Void
 ```
 
 Iterates the set, calling an iterator function on each element.
@@ -227,7 +230,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> b`|The iterator function to call with each element|
+|`fn`|`a -> Void`|The iterator function to call with each element|
 |`set`|`Set<a>`|The set to iterate|
 
 ### Set.**reduce**

package/stack.gr

@@ -13,7 +13,7 @@ import List from "list"
  * Stacks are immutable data structures that store their data in a List.
  */
 record Stack<a> {
-    data: List<a>
+  data: List<a>,
 }
 
 /**
@@ -26,33 +26,33 @@ record Stack<a> {
  * @returns An empty stack
  */
 export let make = () => {
-    { data: [] }
+  { data: [], }
 }
 
 /**
  * Checks if the given stack contains no items.
  *
  * @param stack: The stack to check
- * @returns `true` if the stack has no items, and `false` otherwise
+ * @returns `true` if the stack has no items or `false` otherwise
  */
-export let isEmpty = (stack) => {
-    match (stack) {
-        { data: [] } => true,
-        _ => false
-    }
+export let isEmpty = stack => {
+  match (stack) {
+    { data: [] } => true,
+    _ => false,
+  }
 }
 
 /**
- * Returns `Some(item)` where `item` is the value at the top of the stack, and `None` otherwise.
+ * Provides the value at the top of the stack, if it exists.
  *
  * @param stack: The stack to inspect
- * @returns The value at the top of the stack, if it exists
+ * @returns `Some(value)` containing the value at the top of the stack or `None` otherwise.
  */
-export let peek = (stack) => {
-    match (stack) {
-        { data: [] } => None,
-        { data } => List.head(data)
-    }
+export let peek = stack => {
+  match (stack) {
+    { data: [] } => None,
+    { data } => List.head(data),
+  }
 }
 
 /**
@@ -63,10 +63,10 @@ export let peek = (stack) => {
  * @returns A new stack with the item added to the end
  */
 export let push = (value, stack) => {
-    match (stack) {
-        { data: [] } => { data: [value] },
-        { data } => { data: [value, ...data] }
-    }
+  match (stack) {
+    { data: [] } => { data: [value], },
+    { data } => { data: [value, ...data], },
+  }
 }
 
 /**
@@ -75,11 +75,11 @@ export let push = (value, stack) => {
  * @param stack: The stack being updated
  * @returns A new stack with the last item removed
  */
-export let pop = (stack) => {
-    match (stack) {
-        { data: [] } => stack,
-        { data: [head, ...tail] } => { data: tail, }
-    }
+export let pop = stack => {
+  match (stack) {
+    { data: [] } => stack,
+    { data: [head, ...tail] } => { data: tail, },
+  }
 }
 
 /**
@@ -88,9 +88,9 @@ export let pop = (stack) => {
  * @param stack: The stack to inspect
  * @returns The count of the items in the stack
  */
-export let size = (stack) => {
-    match (stack) {
-        { data: [] } => 0,
-        { data } => List.length(data)
-    }
+export let size = stack => {
+  match (stack) {
+    { data: [] } => 0,
+    { data } => List.length(data),
+  }
 }