@grain/stdlib 0.6.5 → 0.7.0

package/set.gr

@@ -11,7 +11,6 @@ module Set
 from "list" include List
 from "array" include Array
 from "hash" include Hash
-use Hash.{ hash }
 
 record rec Bucket<t> {
   mut key: t,
@@ -20,6 +19,7 @@ record rec Bucket<t> {
 
 abstract record Set<k> {
   mut size: Number,
+  hashInstance: Hash.HashInstance,
   mut buckets: Array<Option<Bucket<k>>>,
 }
 
@@ -41,25 +41,28 @@ provide record InternalSetStats {
  * @param size: The initial storage size of the set
  * @returns An empty set with the given initial storage size
  *
+ * @throws Failure(String): If WASI random_get fails
+ *
  * @since v0.3.0
  * @history v0.6.0: Merged with `makeSized`; modified signature to accept size
  */
 provide let make = (size=16) => {
   let buckets = Array.make(size, None)
-  { size: 0, buckets }
+  let hashInstance = Hash.make()
+  { size: 0, hashInstance, buckets }
 }
 
-let getBucketIndex = (key, buckets) => {
+let getBucketIndex = (hashInstance, key, buckets) => {
   let bucketsLength = Array.length(buckets)
-  let hashedKey = hash(key)
+  let hashedKey = Hash.hash(hashInstance, key)
   hashedKey % bucketsLength
 }
 
-let rec copyNodeWithNewHash = (oldNode, next, tail) => {
+let rec copyNodeWithNewHash = (hashInstance, oldNode, next, tail) => {
   match (oldNode) {
     None => void,
     Some(node) => {
-      let idx = getBucketIndex(node.key, next)
+      let idx = getBucketIndex(hashInstance, node.key, next)
       let newNode = Some(node)
       match (tail[idx]) {
         None => {
@@ -73,7 +76,7 @@ let rec copyNodeWithNewHash = (oldNode, next, tail) => {
       // Always place this node as the new tail
       tail[idx] = newNode
       // Recurse with the next node
-      copyNodeWithNewHash(node.next, next, tail)
+      copyNodeWithNewHash(hashInstance, node.next, next, tail)
     },
   }
 }
@@ -87,8 +90,9 @@ let resize = set => {
     // This tracks the tail nodes so we can set their `next` to None
     let tailNodes = Array.make(nextSize, None)
     set.buckets = nextBuckets
+    let hashInstance = set.hashInstance
     Array.forEach(old => {
-      copyNodeWithNewHash(old, nextBuckets, tailNodes)
+      copyNodeWithNewHash(hashInstance, old, nextBuckets, tailNodes)
     }, currentBuckets)
     Array.forEach(tail => {
       match (tail) {
@@ -124,7 +128,8 @@ let rec nodeInBucket = (key, node) => {
  */
 provide let add = (key, set) => {
   let buckets = set.buckets
-  let idx = getBucketIndex(key, buckets)
+  let hashInstance = set.hashInstance
+  let idx = getBucketIndex(hashInstance, key, buckets)
   let bucket = buckets[idx]
   match (bucket) {
     None => {
@@ -157,7 +162,8 @@ provide let add = (key, set) => {
  */
 provide let contains = (key, set) => {
   let buckets = set.buckets
-  let idx = getBucketIndex(key, buckets)
+  let hashInstance = set.hashInstance
+  let idx = getBucketIndex(hashInstance, key, buckets)
   let bucket = buckets[idx]
   match (bucket) {
     None => false,
@@ -189,7 +195,8 @@ let rec removeInBucket = (key, node) => {
  */
 provide let remove = (key, set) => {
   let buckets = set.buckets
-  let idx = getBucketIndex(key, buckets)
+  let hashInstance = set.hashInstance
+  let idx = getBucketIndex(hashInstance, key, buckets)
   let bucket = buckets[idx]
   match (bucket) {
     None => void,

package/set.md

@@ -55,7 +55,7 @@ Functions and constants included in the Set module.
 </details>
 
 ```grain
-make : (?size: Number) => Set<a>
+make: (?size: Number) => Set<a>
 ```
 
 Creates a new empty set with an initial storage of the given size. As
@@ -75,6 +75,12 @@ Returns:
 |----|-----------|
 |`Set<a>`|An empty set with the given initial storage size|
 
+Throws:
+
+`Failure(String)`
+
+* If WASI random_get fails
+
 ### Set.**add**
 
 <details disabled>
@@ -83,7 +89,7 @@ No other changes yet.
 </details>
 
 ```grain
-add : (key: a, set: Set<a>) => Void
+add: (key: a, set: Set<a>) => Void
 ```
 
 Adds a new value to the set. If the value already exists, nothing happens.
@@ -103,7 +109,7 @@ No other changes yet.
 </details>
 
 ```grain
-contains : (key: a, set: Set<a>) => Bool
+contains: (key: a, set: Set<a>) => Bool
 ```
 
 Determines if the set contains the given value.
@@ -129,7 +135,7 @@ No other changes yet.
 </details>
 
 ```grain
-remove : (key: a, set: Set<a>) => Void
+remove: (key: a, set: Set<a>) => Void
 ```
 
 Removes the given value from the set. If the value doesn't exist, nothing happens.
@@ -149,7 +155,7 @@ No other changes yet.
 </details>
 
 ```grain
-size : (set: Set<a>) => Number
+size: (set: Set<a>) => Number
 ```
 
 Provides the count of values within the set.
@@ -174,7 +180,7 @@ No other changes yet.
 </details>
 
 ```grain
-isEmpty : (set: Set<a>) => Bool
+isEmpty: (set: Set<a>) => Bool
 ```
 
 Determines if the set contains no elements.
@@ -199,7 +205,7 @@ No other changes yet.
 </details>
 
 ```grain
-clear : (set: Set<a>) => Void
+clear: (set: Set<a>) => Void
 ```
 
 Resets the set by removing all values.
@@ -225,7 +231,7 @@ Parameters:
 </details>
 
 ```grain
-forEach : (fn: (a => Void), set: Set<a>) => Void
+forEach: (fn: (a => Void), set: Set<a>) => Void
 ```
 
 Iterates the set, calling an iterator function on each element.
@@ -245,7 +251,7 @@ No other changes yet.
 </details>
 
 ```grain
-reduce : (fn: ((a, b) => a), init: a, set: Set<b>) => a
+reduce: (fn: ((a, b) => a), init: a, set: Set<b>) => a
 ```
 
 Combines all elements of a set using a reducer function.
@@ -272,7 +278,7 @@ No other changes yet.
 </details>
 
 ```grain
-filter : (fn: (a => Bool), set: Set<a>) => Void
+filter: (fn: (a => Bool), set: Set<a>) => Void
 ```
 
 Removes elements from a set where a predicate function returns `false`.
@@ -292,7 +298,7 @@ No other changes yet.
 </details>
 
 ```grain
-reject : (fn: (a => Bool), set: Set<a>) => Void
+reject: (fn: (a => Bool), set: Set<a>) => Void
 ```
 
 Removes elements from a set where a predicate function returns `true`.
@@ -312,7 +318,7 @@ No other changes yet.
 </details>
 
 ```grain
-toList : (set: Set<a>) => List<a>
+toList: (set: Set<a>) => List<a>
 ```
 
 Converts a set into a list of its elements.
@@ -337,7 +343,7 @@ No other changes yet.
 </details>
 
 ```grain
-fromList : (list: List<a>) => Set<a>
+fromList: (list: List<a>) => Set<a>
 ```
 
 Creates a set from a list.
@@ -362,7 +368,7 @@ No other changes yet.
 </details>
 
 ```grain
-toArray : (set: Set<a>) => Array<a>
+toArray: (set: Set<a>) => Array<a>
 ```
 
 Converts a set into an array of its elements.
@@ -387,7 +393,7 @@ No other changes yet.
 </details>
 
 ```grain
-fromArray : (array: Array<a>) => Set<a>
+fromArray: (array: Array<a>) => Set<a>
 ```
 
 Creates a set from an array.
@@ -412,7 +418,7 @@ No other changes yet.
 </details>
 
 ```grain
-union : (set1: Set<a>, set2: Set<a>) => Set<a>
+union: (set1: Set<a>, set2: Set<a>) => Set<a>
 ```
 
 Combines two sets into a single set containing all elements from both sets.
@@ -438,7 +444,7 @@ No other changes yet.
 </details>
 
 ```grain
-diff : (set1: Set<a>, set2: Set<a>) => Set<a>
+diff: (set1: Set<a>, set2: Set<a>) => Set<a>
 ```
 
 Combines two sets into a single set containing only the elements not shared between both sets.
@@ -464,7 +470,7 @@ No other changes yet.
 </details>
 
 ```grain
-intersect : (set1: Set<a>, set2: Set<a>) => Set<a>
+intersect: (set1: Set<a>, set2: Set<a>) => Set<a>
 ```
 
 Combines two sets into a single set containing only the elements shared between both sets.
@@ -497,7 +503,7 @@ Returns:
 </details>
 
 ```grain
-getInternalStats : (set: Set<a>) => InternalSetStats
+getInternalStats: (set: Set<a>) => InternalSetStats
 ```
 
 Provides data representing the internal state state of the set.
@@ -559,7 +565,7 @@ Functions and constants included in the Set.Immutable module.
 </details>
 
 ```grain
-empty : Set<a>
+empty: Set<a>
 ```
 
 An empty set
@@ -579,7 +585,7 @@ An empty set
 </details>
 
 ```grain
-size : (set: Set<a>) => Number
+size: (set: Set<a>) => Number
 ```
 
 Provides the count of values within the set.
@@ -611,7 +617,7 @@ Returns:
 </details>
 
 ```grain
-isEmpty : (set: Set<a>) => Bool
+isEmpty: (set: Set<a>) => Bool
 ```
 
 Determines if the set contains no elements.
@@ -643,7 +649,7 @@ Returns:
 </details>
 
 ```grain
-add : (key: a, set: Set<a>) => Set<a>
+add: (key: a, set: Set<a>) => Set<a>
 ```
 
 Produces a new set by inserting the given value into the set. If the value
@@ -677,7 +683,7 @@ Returns:
 </details>
 
 ```grain
-contains : (key: a, set: Set<a>) => Bool
+contains: (key: a, set: Set<a>) => Bool
 ```
 
 Determines if the set contains the given value.
@@ -710,7 +716,7 @@ Returns:
 </details>
 
 ```grain
-remove : (key: a, set: Set<a>) => Set<a>
+remove: (key: a, set: Set<a>) => Set<a>
 ```
 
 Produces a new set without the given element. If the value doesn't exist in
@@ -744,7 +750,7 @@ Returns:
 </details>
 
 ```grain
-forEach : (fn: (a => Void), set: Set<a>) => Void
+forEach: (fn: (a => Void), set: Set<a>) => Void
 ```
 
 Iterates the set, calling an iterator function on each element.
@@ -771,7 +777,7 @@ Parameters:
 </details>
 
 ```grain
-reduce : (fn: ((a, b) => a), init: a, set: Set<b>) => a
+reduce: (fn: ((a, b) => a), init: a, set: Set<b>) => a
 ```
 
 Combines all elements of a set using a reducer function.
@@ -805,7 +811,7 @@ Returns:
 </details>
 
 ```grain
-filter : (fn: (a => Bool), set: Set<a>) => Set<a>
+filter: (fn: (a => Bool), set: Set<a>) => Set<a>
 ```
 
 Produces a new set without the elements from the input set where a predicate function returns `false`.
@@ -838,7 +844,7 @@ Returns:
 </details>
 
 ```grain
-reject : (fn: (a => Bool), set: Set<a>) => Set<a>
+reject: (fn: (a => Bool), set: Set<a>) => Set<a>
 ```
 
 Produces a new set without the elements from the input set where a predicate function returns `true`.
@@ -871,7 +877,7 @@ Returns:
 </details>
 
 ```grain
-union : (set1: Set<a>, set2: Set<a>) => Set<a>
+union: (set1: Set<a>, set2: Set<a>) => Set<a>
 ```
 
 Combines two sets into a single set containing all elements from both sets.
@@ -904,7 +910,7 @@ Returns:
 </details>
 
 ```grain
-diff : (set1: Set<a>, set2: Set<a>) => Set<a>
+diff: (set1: Set<a>, set2: Set<a>) => Set<a>
 ```
 
 Combines two sets into a single set containing only the elements not shared between both sets.
@@ -937,7 +943,7 @@ Returns:
 </details>
 
 ```grain
-intersect : (set1: Set<a>, set2: Set<a>) => Set<a>
+intersect: (set1: Set<a>, set2: Set<a>) => Set<a>
 ```
 
 Combines two sets into a single set containing only the elements shared between both sets.
@@ -970,7 +976,7 @@ Returns:
 </details>
 
 ```grain
-fromList : (list: List<a>) => Set<a>
+fromList: (list: List<a>) => Set<a>
 ```
 
 Creates a set from a list.
@@ -1002,7 +1008,7 @@ Returns:
 </details>
 
 ```grain
-toList : (set: Set<a>) => List<a>
+toList: (set: Set<a>) => List<a>
 ```
 
 Converts a set into a list of its elements.
@@ -1034,7 +1040,7 @@ Returns:
 </details>
 
 ```grain
-fromArray : (array: Array<a>) => Set<a>
+fromArray: (array: Array<a>) => Set<a>
 ```
 
 Creates a set from an array.
@@ -1066,7 +1072,7 @@ Returns:
 </details>
 
 ```grain
-toArray : (set: Set<a>) => Array<a>
+toArray: (set: Set<a>) => Array<a>
 ```
 
 Converts a set into an array of its elements.

package/stack.gr

@@ -25,12 +25,12 @@ abstract record Stack<a> {
 /**
  * Creates a new stack 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 the
+ * won’t need to care about the storage size of your stack and can use the
  * default size.
  *
  * @param size: The initial storage size of the stack
  * @returns An empty stack
- * 
+ *
  * @since v0.6.0
  */
 provide let make = (size=16) => {
@@ -134,6 +134,95 @@ provide let copy = stack => {
   { size, array: Array.copy(array) }
 }
 
+/**
+ * Creates a list containing the elements of a stack.
+ *
+ * @param stack: The stack to convert
+ * @returns A list containing all stack values
+ *
+ * @example
+ * let stack = Stack.make()
+ * Stack.push(1, stack)
+ * Stack.push(2, stack)
+ * assert Stack.toList(stack) == [2, 1]
+ *
+ * @since v0.7.0
+ */
+provide let toList = stack => {
+  let size = stack.size
+  List.init(size, i => match (stack.array[size - i - 1]) {
+    Some(v) => v,
+    None => fail "Impossible: None in stack bounds on toList",
+  })
+}
+
+/**
+ * Creates a stack from a list.
+ *
+ * @param list: The list to convert
+ * @returns A stack containing all list values
+ *
+ * @example
+ * let stack = Stack.fromList([3, 2, 1])
+ * assert Stack.pop(stack) == Some(3)
+ * assert Stack.pop(stack) == Some(2)
+ * assert Stack.pop(stack) == Some(1)
+ * assert Stack.pop(stack) == None
+ *
+ * @since v0.7.0
+ */
+provide let fromList = list => {
+  let stack = make(size=List.length(list))
+  List.forEach(v => push(v, stack), List.reverse(list))
+  stack
+}
+
+/**
+ * Creates an array containing the elements of a stack.
+ *
+ * @param stack: The stack to convert
+ * @returns An array containing all stack values
+ *
+ * @example
+ * let stack = Stack.make()
+ * Stack.push(1, stack)
+ * Stack.push(2, stack)
+ * assert Stack.toArray(stack) == [> 2, 1]
+ *
+ * @since v0.7.0
+ */
+provide let toArray = stack => {
+  let size = stack.size
+  Array.init(size, i => match (stack.array[size - i - 1]) {
+    Some(v) => v,
+    None => fail "Impossible: None in stack bounds on toList",
+  })
+}
+
+/**
+ * Creates a stack from an array.
+ *
+ * @param arr: The array to convert
+ * @returns A stack containing all array values
+ *
+ * @example
+ * let s = Stack.fromArray([> 3, 2, 1])
+ * assert Stack.pop(s) == Some(3)
+ * assert Stack.pop(s) == Some(2)
+ * assert Stack.pop(s) == Some(1)
+ * assert Stack.pop(s) == None
+ *
+ * @since v0.7.0
+ */
+provide let fromArray = arr => {
+  let arrLen = Array.length(arr)
+  let stack = make(size=arrLen)
+  for (let mut i = arrLen - 1; i >= 0; i -= 1) {
+    push(arr[i], stack)
+  }
+  stack
+}
+
 /**
  * An immutable stack implementation.
  */
@@ -237,4 +326,84 @@ provide module Immutable {
       { data } => List.length(data),
     }
   }
+
+  /**
+   * Creates a list containing the elements of a stack.
+   *
+   * @param stack: The stack to convert
+   * @returns A list containing all stack values
+   *
+   * @example
+   * use Stack.{ module Immutable as Stack }
+   * let stack = Stack.empty
+   * let stack = Stack.push(1, stack)
+   * let stack = Stack.push(2, stack)
+   * assert Stack.toList(stack) == [2, 1]
+   *
+   * @since v0.7.0
+   */
+  provide let toList = stack => {
+    stack.data
+  }
+
+  /**
+   * Creates a stack from a list.
+   *
+   * @param list: The list to convert
+   * @returns A stack containing all list values
+   *
+   * @example
+   * use Stack.{ module Immutable as Stack }
+   * let stack = Stack.fromList([2, 1])
+   * assert Stack.peek(stack) == Some(2)
+   * let stack = Stack.pop(stack)
+   * assert Stack.peek(stack) == Some(1)
+   * let stack = Stack.pop(stack)
+   * assert Stack.isEmpty(stack)
+   *
+   * @since v0.7.0
+   */
+  provide let fromList = list => {
+    { data: list, }
+  }
+
+  /**
+   * Creates an array containing the elements of a stack.
+   *
+   * @param stack: The stack to convert
+   * @returns An array containing all stack values
+   *
+   * @example
+   * use Stack.{ module Immutable as Stack }
+   * let stack = Stack.empty
+   * let stack = Stack.push(1, stack)
+   * let stack = Stack.push(2, stack)
+   * assert Stack.toArray(stack) == [> 2, 1]
+   *
+   * @since v0.7.0
+   */
+  provide let toArray = stack => {
+    Array.fromList(stack.data)
+  }
+
+  /**
+   * Creates a stack from an array.
+   *
+   * @param arr: The array to convert
+   * @returns A stack containing all array values
+   *
+   * @example
+   * use Stack.{ module Immutable as Stack }
+   * let stack = Stack.fromArray([> 2, 1])
+   * assert Stack.peek(stack) == Some(2)
+   * let stack = Stack.pop(stack)
+   * assert Stack.peek(stack) == Some(1)
+   * let stack = Stack.pop(stack)
+   * assert Stack.isEmpty(stack)
+   *
+   * @since v0.7.0
+   */
+  provide let fromArray = arr => {
+    { data: Array.toList(arr), }
+  }
 }