@grain/stdlib 0.5.13 → 0.6.0

package/map.gr

@@ -1,60 +1,60 @@
 /**
- * @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"
+ * 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.
+ *
+ * An immutable map implementation is available in the `Immutable` submodule.
+ * @example from "map" include Map
  *
  * @since v0.2.0
  */
-import List from "list"
-import Array from "array"
-import { hash } from "hash"
-import Memory from "runtime/unsafe/memory"
-import WasmI32 from "runtime/unsafe/wasmi32"
-import { allocateArray, untagSimpleNumber } from "runtime/dataStructures"
+module Map
+
+from "list" include List
+from "array" include Array
+from "option" include Option
+from "runtime/dataStructures" include DataStructures
+use DataStructures.{ allocateArray, untagSimpleNumber }
+from "hash" include Hash
+use Hash.{ hash }
+from "runtime/unsafe/memory" include Memory
+from "runtime/unsafe/wasmi32" include WasmI32
 
 // TODO: Consider implementing this as List<(Box<k>, Box<v>)>
-record Bucket<k, v> {
+record rec Bucket<k, v> {
   mut key: k,
   mut value: v,
   mut next: Option<Bucket<k, v>>,
 }
 
-/**
- * @section Types: Type declarations included in the Map module.
- */
-
-record Map<k, v> {
+abstract record Map<k, v> {
   mut size: Number,
   mut buckets: Array<Option<Bucket<k, v>>>,
 }
 
 /**
- * @section Values: Functions for working with Maps.
+ * Represents the internal state of a map.
  */
+provide record InternalMapStats {
+  currentSize: Number,
+  bucketCount: Number,
+}
 
 /**
- * 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.
+ * 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 the default size.
  *
  * @param size: The initial storage size of the map
  * @returns An empty map with the given initial storage size
  *
  * @since v0.2.0
+ * @history v0.6.0: Merged with `makeSized`; modified signature to accept size
  */
-export let makeSized = size => { // TODO: This could take an `eq` function to custom comparisons
+provide let make = (size=16) => { // 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)
@@ -130,7 +130,7 @@ let rec replaceInBucket = (key, value, node) => {
  *
  * @since v0.2.0
  */
-export let set = (key, value, map) => {
+provide let set = (key, value, map) => {
   let buckets = map.buckets
   let idx = getBucketIndex(key, buckets)
   let bucket = buckets[idx]
@@ -174,7 +174,7 @@ let rec valueFromBucket = (key, node) => {
  *
  * @since v0.2.0
  */
-export let get = (key, map) => {
+provide let get = (key, map) => {
   let buckets = map.buckets
   let idx = getBucketIndex(key, buckets)
   let bucket = buckets[idx]
@@ -204,7 +204,7 @@ let rec nodeInBucket = (key, node) => {
  *
  * @since v0.2.0
  */
-export let contains = (key, map) => {
+provide let contains = (key, map) => {
   let buckets = map.buckets
   let idx = getBucketIndex(key, buckets)
   let bucket = buckets[idx]
@@ -236,7 +236,7 @@ let rec removeInBucket = (key, node) => {
  *
  * @since v0.2.0
  */
-export let remove = (key, map) => {
+provide let remove = (key, map) => {
   let buckets = map.buckets
   let idx = getBucketIndex(key, buckets)
   let bucket = buckets[idx]
@@ -265,7 +265,7 @@ export let remove = (key, map) => {
  *
  * @since v0.3.0
  */
-export let update = (key, fn, map) => {
+provide let update = (key, fn, map) => {
   let val = get(key, map)
   match (fn(val)) {
     Some(next) => set(key, next, map),
@@ -281,7 +281,7 @@ export let update = (key, fn, map) => {
  *
  * @since v0.2.0
  */
-export let size = map => {
+provide let size = map => {
   map.size
 }
 
@@ -293,7 +293,7 @@ export let size = map => {
  *
  * @since v0.2.0
  */
-export let isEmpty = map => {
+provide let isEmpty = map => {
   size(map) == 0
 }
 
@@ -304,7 +304,7 @@ export let isEmpty = map => {
  *
  * @since v0.2.0
  */
-export let clear = map => {
+provide let clear = map => {
   map.size = 0
   let buckets = map.buckets
   Array.forEachi((bucket, idx) => {
@@ -331,7 +331,7 @@ let rec forEachBucket = (fn, node) => {
  * @since v0.2.0
  * @history v0.5.0: Ensured the iterator function return type is always `Void`
  */
-export let forEach = (fn, map) => {
+provide let forEach = (fn, map) => {
   let buckets = map.buckets
   Array.forEach(bucket => {
     forEachBucket(fn, bucket)
@@ -356,7 +356,7 @@ let rec reduceEachBucket = (fn, node, acc) => {
  *
  * @since v0.2.0
  */
-export let reduce = (fn, init, map) => {
+provide let reduce = (fn, init, map) => {
   let buckets = map.buckets
   let mut acc = init
   Array.forEach(bucket => {
@@ -373,7 +373,7 @@ export let reduce = (fn, init, map) => {
  *
  * @since v0.2.0
  */
-export let keys = map => {
+provide let keys = map => {
   reduce((list, key, _value) => [key, ...list], [], map)
 }
 
@@ -385,7 +385,7 @@ export let keys = map => {
  *
  * @since v0.2.0
  */
-export let values = map => {
+provide let values = map => {
   reduce((list, _key, value) => [value, ...list], [], map)
 }
 
@@ -397,7 +397,7 @@ export let values = map => {
  *
  * @since v0.2.0
  */
-export let toList = map => {
+provide let toList = map => {
   reduce((list, key, value) => [(key, value), ...list], [], map)
 }
 
@@ -409,7 +409,7 @@ export let toList = map => {
  *
  * @since v0.2.0
  */
-export let fromList = list => {
+provide let fromList = list => {
   let map = make()
   List.forEach(pair => {
     let (key, value) = pair
@@ -427,24 +427,26 @@ export let fromList = list => {
  * @since v0.2.0
  */
 @unsafe
-export let toArray: Map<a, b> -> Array<(a, b)> = map => {
+provide let toArray = (map: Map<a, b>) => {
+  use WasmI32.{ (*) }
   let length = untagSimpleNumber(map.size)
   let array = WasmI32.toGrain(allocateArray(length))
   @unsafe
   let reducer = (i, key, value) => {
+    use WasmI32.{ (+) as addWasmI32 }
     // Assign the values into the array.
     // We store them directly to prevent GC on uninitialized array data.
     let array = WasmI32.fromGrain(array)
     let item = (key, value)
     WasmI32.store(
-      WasmI32.add(array, WasmI32.mul(untagSimpleNumber(i), 4n)),
+      addWasmI32(array, untagSimpleNumber(i) * 4n),
       Memory.incRef(WasmI32.fromGrain(item)),
       8n
     )
     i + 1
   }
   reduce(reducer, 0, map)
-  array
+  array: Array<(a, b)>
 }
 
 /**
@@ -455,7 +457,7 @@ export let toArray: Map<a, b> -> Array<(a, b)> = map => {
  *
  * @since v0.2.0
  */
-export let fromArray = array => {
+provide let fromArray = array => {
   let map = make()
   Array.forEach(pair => {
     let (key, value) = pair
@@ -472,12 +474,16 @@ export let fromArray = array => {
  *
  * @since v0.2.0
  */
-export let filter = (predicate, map) => {
-  let keysToRemove = reduce((list, key, value) => if (!predicate(key, value)) {
-    [key, ...list]
-  } else {
-    list
-  }, [], map)
+provide let filter = (fn, map) => {
+  let keysToRemove = reduce(
+    (list, key, value) => if (!fn(key, value)) {
+      [key, ...list]
+    } else {
+      list
+    },
+    [],
+    map
+  )
   List.forEach(key => {
     remove(key, map)
   }, keysToRemove)
@@ -491,11 +497,10 @@ export let filter = (predicate, map) => {
  *
  * @since v0.2.0
  */
-export let reject = (predicate, map) => {
-  filter((key, value) => !predicate(key, value), map)
+provide let reject = (fn, map) => {
+  filter((key, value) => !fn(key, value), map)
 }
 
-// TODO(#190): Should return a Record type instead of a Tuple
 /**
  * Provides data representing the internal state state of the map.
  *
@@ -503,7 +508,505 @@ export let reject = (predicate, map) => {
  * @returns The internal state of the map
  *
  * @since v0.2.0
+ * @history v0.6.0: Return `InternalMapStats` record instead of a tuple
  */
-export let getInternalStats = map => {
-  (map.size, Array.length(map.buckets))
+provide let getInternalStats = map => {
+  { currentSize: map.size, bucketCount: Array.length(map.buckets) }
+}
+
+/**
+ * An immutable map implementation.
+ *
+ * @since v0.6.0
+ * @history v0.5.4: Originally in `"immutablemap"` module
+ */
+provide module Immutable {
+  // implementation based on the paper "Implementing Sets Efficiently in a
+  // Functional Language" by Stephen Adams
+  record rec Node<k, v> {
+    key: k,
+    val: v,
+    size: Number,
+    left: Map<k, v>,
+    right: Map<k, v>,
+  }
+  and abstract enum Map<k, v> {
+    Empty,
+    Tree(Node<k, v>),
+  }
+
+  // semi-arbitrary value chosen for algorithm for determining when to balance
+  // trees; no tree can have a left subtree containing this number of times
+  // more elements than its right subtree or vice versa
+  let weight = 4
+
+  /**
+   * An empty map
+   *
+   * @since v0.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let empty = Empty
+
+  // returns the key-value pair of the minimum key in a tree
+  let rec min = node => {
+    match (node) {
+      Tree({ key, val, left: Empty, _ }) => (key, val),
+      Tree({ left, _ }) => min(left),
+      Empty => fail "Impossible: min of empty element in Map.Immutable",
+    }
+  }
+
+  /**
+   * 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.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let size = map => {
+    match (map) {
+      Empty => 0,
+      Tree({ size, _ }) => size,
+    }
+  }
+
+  /**
+   * 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.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let isEmpty = map => {
+    match (map) {
+      Empty => true,
+      Tree(_) => false,
+    }
+  }
+
+  let unwrapTree = node => {
+    match (node) {
+      Empty =>
+        fail "Impossible: Map.Immutable unwrapTree got an empty tree node",
+      Tree(tree) => tree,
+    }
+  }
+
+  // helper function for creating a tree node with correct size from
+  // two balanced trees
+  let makeNode = (key, val, left, right) => {
+    Tree({ key, val, size: 1 + size(left) + size(right), left, right })
+  }
+
+  // note: see Figure 1 of paper referenced above for visual illustration of
+  // the rotations below
+
+  // node rotation moving the left subtree of the right node to the left side
+  let singleL = (key, val, left, right) => {
+    let { key: rKey, val: rVal, left: rl, right: rr, _ } = unwrapTree(right)
+    makeNode(rKey, rVal, makeNode(key, val, left, rl), rr)
+  }
+
+  // node rotation moving left child of right tree to the root
+  let doubleL = (key, val, left, right) => {
+    let { key: rKey, val: rVal, left: rl, right: rr, _ } = unwrapTree(right)
+    let { key: rlKey, val: rlVal, left: rll, right: rlr, _ } = unwrapTree(rl)
+    makeNode(
+      rlKey,
+      rlVal,
+      makeNode(key, val, left, rll),
+      makeNode(rKey, rVal, rlr, rr)
+    )
+  }
+
+  // node rotation moving the right subtree of the left node to the right side
+  let singleR = (key, val, left, right) => {
+    let { key: lKey, val: lVal, left: ll, right: lr, _ } = unwrapTree(left)
+    makeNode(lKey, lVal, ll, makeNode(key, val, lr, right))
+  }
+
+  // node rotation moving right child of left tree to the root
+  let doubleR = (key, val, left, right) => {
+    let { key: lKey, val: lVal, left: ll, right: lr, _ } = unwrapTree(left)
+    let { key: lrKey, val: lrVal, left: lrl, right: lrr, _ } = unwrapTree(lr)
+    makeNode(
+      lrKey,
+      lrVal,
+      makeNode(lKey, lVal, ll, lrl),
+      makeNode(key, val, lrr, right)
+    )
+  }
+
+  // creates a new node after either the left or right trees have just had an
+  // element inserted or removed from them, maintaining balance in the tree
+  let balancedNode = (key, val, left, right) => {
+    let makeNodeFn = if (size(left) + size(right) < 2) {
+      makeNode
+    } else if (size(right) > weight * size(left)) {
+      // if the right tree is too much larger than the left then move part of
+      // the right tree to the left side
+      let { left: rl, right: rr, _ } = unwrapTree(right)
+      if (size(rl) < size(rr)) singleL else doubleL
+    } else if (size(left) > weight * size(right)) {
+      // if the left tree is too much larger than the right then move part of
+      // the left tree to the right side
+      let { left: ll, right: lr, _ } = unwrapTree(left)
+      if (size(lr) < size(ll)) singleR else doubleR
+    } else {
+      // if neither tree is too much larger than the other then simply create
+      // a new node
+      makeNode
+    }
+
+    makeNodeFn(key, val, left, right)
+  }
+
+  /**
+   * Produces a new map containing a new key-value pair. 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 base map
+   * @returns A new map containing the new key-value pair
+   *
+   * @since v0.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let rec set = (key, value, map) => {
+    match (map) {
+      Empty => Tree({ key, val: value, size: 1, left: Empty, right: Empty }),
+      Tree({ key: nodeKey, val: nodeVal, left, right, _ }) => {
+        match (compare(key, nodeKey)) {
+          cmp when cmp < 0 =>
+            balancedNode(nodeKey, nodeVal, set(key, value, left), right),
+          cmp when cmp > 0 =>
+            balancedNode(nodeKey, nodeVal, left, set(key, value, right)),
+          _ => makeNode(key, value, left, right),
+        }
+      },
+    }
+  }
+
+  /**
+   * 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.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let rec get = (key, map) => {
+    match (map) {
+      Empty => None,
+      Tree({ key: nodeKey, val: nodeVal, left, right, _ }) => {
+        match (compare(key, nodeKey)) {
+          cmp when cmp < 0 => get(key, left),
+          cmp when cmp > 0 => get(key, right),
+          _ => Some(nodeVal),
+        }
+      },
+    }
+  }
+
+  /**
+   * 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.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let rec contains = (key, map) => {
+    Option.isSome(get(key, map))
+  }
+
+  // removes the minimum element from a tree
+  let rec removeMin = node => {
+    match (node) {
+      Tree({ left: Empty, right, _ }) => right,
+      Tree({ key, val, left, right, _ }) =>
+        balancedNode(key, val, removeMin(left), right),
+      _ => fail "Impossible: Map.Immutable removeMin on empty node",
+    }
+  }
+
+  // helper function for removing a node by creating a new node containing the
+  // removed node's left and right subtrees
+  let removeInner = (left, right) => {
+    match ((left, right)) {
+      (Empty, node) | (node, Empty) => node,
+      (left, right) => {
+        let (minKey, minVal) = min(right)
+        balancedNode(minKey, minVal, left, removeMin(right))
+      },
+    }
+  }
+
+  /**
+   * Produces a new map without the key-value pair corresponding to the given
+   * key. If the key doesn't exist in the map, the map will be returned unmodified.
+   *
+   * @param key: The key to exclude
+   * @param map: The map to exclude from
+   * @returns A new map without the given key
+   *
+   * @since v0.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let rec remove = (key, map) => {
+    match (map) {
+      Empty => Empty,
+      Tree({ key: nodeKey, val: nodeVal, left, right, _ }) => {
+        match (compare(key, nodeKey)) {
+          cmp when cmp < 0 =>
+            balancedNode(nodeKey, nodeVal, remove(key, left), right),
+          cmp when cmp > 0 =>
+            balancedNode(nodeKey, nodeVal, left, remove(key, right)),
+          _ => removeInner(left, right),
+        }
+      },
+    }
+  }
+
+  /**
+   * Produces a new 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 excluded.
+   *
+   * @param key: The unique key in the map
+   * @param fn: The updater function
+   * @param map: The base map
+   * @returns A new map with the value at the given key modified according to the function's output
+   *
+   * @since v0.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let update = (key, fn, map) => {
+    let val = get(key, map)
+    match (fn(val)) {
+      Some(next) => set(key, next, map),
+      None => remove(key, map),
+    }
+  }
+
+  /**
+   * 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.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let forEach = (fn, map) => {
+    let rec forEachInner = node => {
+      match (node) {
+        Empty => void,
+        Tree({ key, val, left, right, _ }) => {
+          forEachInner(left)
+          fn(key, val): Void
+          forEachInner(right)
+        },
+      }
+    }
+    forEachInner(map)
+  }
+
+  /**
+   * 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.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let reduce = (fn, init, map) => {
+    let rec reduceInner = (acc, node) => {
+      match (node) {
+        Empty => acc,
+        Tree({ key, val, left, right, _ }) => {
+          let newAcc = fn(reduceInner(acc, left), key, val)
+          reduceInner(newAcc, right)
+        },
+      }
+    }
+    reduceInner(init, map)
+  }
+
+  // joins two trees with a value, preserving the BST property of left children
+  // being less the node and right children being greater than the node
+  let rec concat3 = (key, val, left, right) => {
+    match ((left, right)) {
+      (Empty, node) | (node, Empty) => set(key, val, node),
+      (Tree(left) as leftOpt, Tree(right) as rightOpt) => {
+        let { size: lSize, key: lKey, left: lLeft, right: lRight, val: lVal } =
+          left
+        let { size: rSize, key: rKey, left: rLeft, right: rRight, val: rVal } =
+          right
+        if (weight * lSize < rSize) {
+          balancedNode(rKey, rVal, concat3(key, val, leftOpt, rLeft), rRight)
+        } else if (weight * rSize < lSize) {
+          balancedNode(lKey, lVal, lLeft, concat3(key, val, lRight, rightOpt))
+        } else {
+          makeNode(key, val, leftOpt, rightOpt)
+        }
+      },
+    }
+  }
+
+  // concatenates two trees of arbitrary size
+  let concat = (node1, node2) => {
+    match (node2) {
+      Empty => node1,
+      _ => {
+        let (minKey, minVal) = min(node2)
+        concat3(minKey, minVal, node1, removeMin(node2))
+      },
+    }
+  }
+
+  let reduceRight = (fn, init, map) => {
+    let rec reduceInner = (acc, node) => {
+      match (node) {
+        Empty => acc,
+        Tree({ key, val, left, right, _ }) => {
+          let newAcc = fn(reduceInner(acc, right), key, val)
+          reduceInner(newAcc, left)
+        },
+      }
+    }
+    reduceInner(init, 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.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let keys = map => {
+    reduceRight((list, key, _) => [key, ...list], [], 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.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let values = map => {
+    reduceRight((list, _, value) => [value, ...list], [], map)
+  }
+
+  /**
+   * Produces a new map excluding the key-value pairs where a predicate function returns `false`.
+   *
+   * @param fn: The predicate function to indicate which key-value pairs to exclude from the map, where returning `false` indicates the key-value pair should be excluded
+   * @param map: The map to iterate
+   * @returns A new map excluding the key-value pairs not fulfilling the predicate
+   *
+   * @since v0.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let filter = (fn, map) => {
+    let rec filterInner = node => {
+      match (node) {
+        Empty => Empty,
+        Tree({ key, val, left, right, _ }) => {
+          if (fn(key, val)) {
+            concat3(key, val, filterInner(left), filterInner(right))
+          } else {
+            concat(filterInner(left), filterInner(right))
+          }
+        },
+      }
+    }
+    filterInner(map)
+  }
+
+  /**
+   * Produces a new map excluding the key-value pairs where a predicate function returns `true`.
+   *
+   * @param fn: The predicate function to indicate which key-value pairs to exclude from the map, where returning `true` indicates the key-value pair should be excluded
+   * @param map: The map to iterate
+   * @returns A new map excluding the key-value pairs fulfilling the predicate
+   *
+   * @since v0.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let reject = (fn, map) => {
+    filter((key, val) => !fn(key, val), map)
+  }
+
+  /**
+   * 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.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let fromList = list => {
+    List.reduce((map, (key, val)) => set(key, val, map), empty, list)
+  }
+
+  /**
+   * 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.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let toList = map => {
+    reduceRight((list, key, val) => [(key, val), ...list], [], map)
+  }
+
+  /**
+   * 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.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let fromArray = array => {
+    Array.reduce((map, (key, val)) => set(key, val, map), empty, array)
+  }
+
+  /**
+   * 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.6.0
+   * @history v0.5.4: Originally in `"immutablemap"` module
+   */
+  provide let toArray = map => {
+    Array.fromList(toList(map))
+  }
 }