@grain/stdlib 0.5.3 → 0.5.4

package/immutableset.gr

@@ -0,0 +1,498 @@
+/**
+ * @module ImmutableSet: An ImmutableSet is a collection of unique values. Operations on an ImmutableSet do not mutate the set's internal state.
+ * @example import ImmutableSet from "immutableset"
+ * 
+ * @since v0.5.4
+ */
+
+import List from "list"
+import Array from "array"
+
+// implementation based on the paper "Implementing Sets Efficiently in a
+// Functional Language" by Stephen Adams
+
+record Node<a> {
+  key: a,
+  size: Number,
+  left: ImmutableSet<a>,
+  right: ImmutableSet<a>,
+},
+/**
+ * @section Types: Type declarations included in the ImmutableSet module.
+ */
+enum ImmutableSet<a> {
+  Empty,
+  Tree(Node<a>),
+}
+
+/**
+ * @section Values: Functions and constants for working with ImmutableSets.
+ */
+
+// 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 set
+ * 
+ * @since v0.5.4
+ */
+export let empty = Empty
+
+// returns the minimum value in a tree
+let rec min = node => {
+  match (node) {
+    Tree({ key, left: Empty, _ }) => key,
+    Tree({ left, _ }) => min(left),
+    Empty => fail "Impossible: min of empty element in ImmutableSet",
+  }
+}
+
+/**
+ * Provides the count of values within the set.
+ *
+ * @param set: The set to inspect
+ * @returns The count of elements in the set
+ * 
+ * @since v0.5.4
+ */
+export let size = set => {
+  match (set) {
+    Empty => 0,
+    Tree({ size, _ }) => size,
+  }
+}
+
+/**
+ * Determines if the set contains no elements.
+ *
+ * @param set: The set to inspect
+ * @returns `true` if the given set is empty or `false` otherwise
+ * 
+ * @since v0.5.4
+ */
+export let isEmpty = set => {
+  match (set) {
+    Empty => true,
+    Tree(_) => false,
+  }
+}
+
+let unwrapTree = node => {
+  match (node) {
+    Empty => fail "Impossible: ImmutableSet 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, left, right) => {
+  Tree({ key, 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, left, right) => {
+  let { key: rKey, left: rl, right: rr, _ } = unwrapTree(right)
+  makeNode(rKey, makeNode(key, left, rl), rr)
+}
+
+// node rotation moving left child of right tree to the root
+let doubleL = (key, left, right) => {
+  let { key: rKey, left: rl, right: rr, _ } = unwrapTree(right)
+  let { key: rlKey, left: rll, right: rlr, _ } = unwrapTree(rl)
+  makeNode(rlKey, makeNode(key, left, rll), makeNode(rKey, rlr, rr))
+}
+
+// node rotation moving the right subtree of the left node to the right side
+let singleR = (key, left, right) => {
+  let { key: lKey, left: ll, right: lr, _ } = unwrapTree(left)
+  makeNode(lKey, ll, makeNode(key, lr, right))
+}
+
+// node rotation moving right child of left tree to the root
+let doubleR = (key, left, right) => {
+  let { key: lKey, left: ll, right: lr, _ } = unwrapTree(left)
+  let { key: lrKey, left: lrl, right: lrr, _ } = unwrapTree(lr)
+  makeNode(lrKey, makeNode(lKey, ll, lrl), makeNode(key, 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, 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, left, right)
+}
+
+/**
+ * Produces a new set by inserting the given value into the set. If the value
+ * already exists, the new set will have the same elements as the input set.
+ *
+ * @param key: The value to add
+ * @param set: The base set
+ * @returns A new set containing the new element
+ * 
+ * @since v0.5.4
+ */
+export let rec add = (key, set) => {
+  match (set) {
+    Empty => Tree({ key, size: 1, left: Empty, right: Empty }),
+    Tree({ key: nodeKey, left, right, _ }) => {
+      match (compare(key, nodeKey)) {
+        cmp when cmp < 0 => balancedNode(nodeKey, add(key, left), right),
+        cmp when cmp > 0 => balancedNode(nodeKey, left, add(key, right)),
+        _ => makeNode(key, left, right),
+      }
+    },
+  }
+}
+
+/**
+ * Determines if the set contains the given value.
+ *
+ * @param key: The value to search for
+ * @param set: The set to search
+ * @returns `true` if the set contains the given value or `false` otherwise
+ * 
+ * @since v0.5.4
+ */
+export let rec contains = (key, set) => {
+  match (set) {
+    Empty => false,
+    Tree({ key: nodeKey, left, right, _ }) => {
+      match (compare(key, nodeKey)) {
+        cmp when cmp < 0 => contains(key, left),
+        cmp when cmp > 0 => contains(key, right),
+        _ => true,
+      }
+    },
+  }
+}
+
+// removes the minimum element from a tree
+let rec removeMin = node => {
+  match (node) {
+    Tree({ left: Empty, right, _ }) => right,
+    Tree({ key, left, right, _ }) => balancedNode(key, removeMin(left), right),
+    _ => fail "Impossible: ImmutableSet 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) => {
+      balancedNode(min(right), left, removeMin(right))
+    },
+  }
+}
+
+/**
+ * Produces a new set without the given element. If the value doesn't exist in
+ * the set, the set will be returned unmodified.
+ *
+ * @param key: The value to exclude
+ * @param set: The set to exclude from
+ * @returns A new set without the excluded element
+ * 
+ * @since v0.5.4
+ */
+export let rec remove = (key, set) => {
+  match (set) {
+    Empty => Empty,
+    Tree({ key: nodeKey, left, right, _ }) => {
+      match (compare(key, nodeKey)) {
+        cmp when cmp < 0 => balancedNode(nodeKey, remove(key, left), right),
+        cmp when cmp > 0 => balancedNode(nodeKey, left, remove(key, right)),
+        _ => removeInner(left, right),
+      }
+    },
+  }
+}
+
+/**
+ * Iterates the set, calling an iterator function on each element.
+ *
+ * @param fn: The iterator function to call with each element
+ * @param set: The set to iterate
+ * 
+ * @since v0.5.4
+ */
+export let forEach = (fn, set) => {
+  let rec forEachInner = node => {
+    match (node) {
+      Empty => void,
+      Tree({ key, left, right, _ }) => {
+        forEachInner(left)
+        fn(key): Void
+        forEachInner(right)
+      },
+    }
+  }
+  forEachInner(set)
+}
+
+/**
+ * Combines all elements of a set using a reducer function.
+ *
+ * @param fn: The reducer function to call on each element, 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 set: The set to iterate
+ * @returns The final accumulator returned from `fn`
+ * 
+ * @since v0.5.4
+ */
+export let reduce = (fn, init, set) => {
+  let rec reduceInner = (acc, node) => {
+    match (node) {
+      Empty => acc,
+      Tree({ key, left, right, _ }) => {
+        let newAcc = fn(reduceInner(acc, left), key)
+        reduceInner(newAcc, right)
+      },
+    }
+  }
+  reduceInner(init, set)
+}
+
+// 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, left, right) => {
+  match ((left, right)) {
+    (Empty, node) | (node, Empty) => add(key, node),
+    (Tree(left) as leftOpt, Tree(right) as rightOpt) => {
+      if (weight * left.size < right.size) {
+        balancedNode(right.key, concat3(key, leftOpt, right.left), right.right)
+      } else if (weight * right.size < left.size) {
+        balancedNode(left.key, left.left, concat3(key, left.right, rightOpt))
+      } else {
+        makeNode(key, leftOpt, rightOpt)
+      }
+    },
+  }
+}
+
+// returns a tree containing all of the nodes in the input tree whose values
+// are less than the given value
+let rec splitLt = (splitKey, node) => {
+  match (node) {
+    Empty => Empty,
+    Tree({ key, left, right, _ }) => {
+      match (compare(key, splitKey)) {
+        // we want this node, join it to the output
+        cmp when cmp < 0 => concat3(key, left, splitLt(splitKey, right)),
+        cmp when cmp > 0 => splitLt(splitKey, left),
+        _ => left,
+      }
+    },
+  }
+}
+
+// returns a tree containing all of the nodes in the input tree whose values
+// are greater than the given value
+let rec splitGt = (splitKey, node) => {
+  match (node) {
+    Empty => Empty,
+    Tree({ key, left, right, _ }) => {
+      match (compare(key, splitKey)) {
+        // we want this node, join it to the output
+        cmp when cmp > 0 => concat3(key, splitGt(splitKey, left), right),
+        cmp when cmp < 0 => splitGt(splitKey, right),
+        _ => right,
+      }
+    },
+  }
+}
+
+// concatenates two trees of arbitrary size
+let concat = (node1, node2) => {
+  match (node2) {
+    Empty => node1,
+    _ => concat3(min(node2), node1, removeMin(node2)),
+  }
+}
+
+/**
+ * Produces a new set without the elements from the input set where a predicate function returns `false`.
+ *
+ * @param fn: The predicate function to indicate which elements to exclude from the set, where returning `false` indicates the value should be excluded
+ * @param set: The set to iterate
+ * @returns A new set excluding the elements not fulfilling the predicate
+ * 
+ * @since v0.5.4
+ */
+export let filter = (fn, set) => {
+  let rec filterInner = node => {
+    match (node) {
+      Empty => Empty,
+      Tree({ key, left, right, _ }) => {
+        if (fn(key)) {
+          concat3(key, filterInner(left), filterInner(right))
+        } else {
+          concat(filterInner(left), filterInner(right))
+        }
+      },
+    }
+  }
+  filterInner(set)
+}
+
+/**
+ * Produces a new set without the elements from the input set where a predicate function returns `true`.
+ *
+ * @param fn: The predicate function to indicate which elements to exclude from the set, where returning `true` indicates the value should be excluded
+ * @param set: The set to iterate
+ * @returns A new set excluding the elements fulfilling the predicate
+ * 
+ * @since v0.5.4
+ */
+export let reject = (fn, set) => {
+  filter(key => !fn(key), set)
+}
+
+/**
+ * Combines two sets into a single set containing all elements from both sets.
+ *
+ * @param set1: The first set to combine
+ * @param set2: The second set to combine
+ * @returns A set containing all elements of both sets
+ * 
+ * @since v0.5.4
+ */
+export let rec union = (set1, set2) => {
+  match ((set1, set2)) {
+    (Empty, node) | (node, Empty) => node,
+    (node1, Tree(node2)) => {
+      let l = splitLt(node2.key, node1)
+      let r = splitGt(node2.key, node1)
+      concat3(node2.key, union(l, node2.left), union(r, node2.right))
+    },
+  }
+}
+
+/**
+ * Combines two sets into a single set containing only the elements not shared between both sets.
+ *
+ * @param set1: The first set to combine
+ * @param set2: The second set to combine
+ * @returns A set containing only unshared elements from both sets
+ * 
+ * @since v0.5.4
+ */
+export let diff = (set1, set2) => {
+  let rec diffInner = (node1, node2) => {
+    match ((node1, node2)) {
+      (Empty, node) | (node, Empty) => node,
+      (node1, Tree(node2)) => {
+        let l = splitLt(node2.key, node1)
+        let r = splitGt(node2.key, node1)
+        concat(diffInner(l, node2.left), diffInner(r, node2.right))
+      },
+    }
+  }
+  union(diffInner(set1, set2), diffInner(set2, set1))
+}
+
+/**
+ * Combines two sets into a single set containing only the elements shared between both sets.
+ *
+ * @param set1: The first set to combine
+ * @param set2: The second set to combine
+ * @returns A set containing only shared elements from both sets
+ * 
+ * @since v0.5.4
+ */
+export let rec intersect = (set1, set2) => {
+  match ((set1, set2)) {
+    (Empty, _) | (_, Empty) => Empty,
+    (node1, Tree(node2)) => {
+      let l = splitLt(node2.key, node1)
+      let r = splitGt(node2.key, node1)
+      if (contains(node2.key, node1)) {
+        concat3(node2.key, intersect(l, node2.left), intersect(r, node2.right))
+      } else {
+        concat(intersect(l, node2.left), intersect(r, node2.right))
+      }
+    },
+  }
+}
+
+/**
+ * Creates a set from a list.
+ *
+ * @param list: The list to convert
+ * @returns A set containing all list values
+ * 
+ * @since v0.5.4
+ */
+export let fromList = list => {
+  List.reduce((set, key) => add(key, set), empty, list)
+}
+
+/**
+ * Converts a set into a list of its elements.
+ *
+ * @param set: The set to convert
+ * @returns A list containing all set values
+ * 
+ * @since v0.5.4
+ */
+export let toList = set => {
+  let rec toListInner = (acc, node) => {
+    match (node) {
+      Empty => acc,
+      Tree({ key, left, right, _ }) => {
+        toListInner([key, ...toListInner(acc, right)], left)
+      },
+    }
+  }
+  toListInner([], set)
+}
+
+/**
+ * Creates a set from an array.
+ *
+ * @param array: The array to convert
+ * @returns A set containing all array values
+ * 
+ * @since v0.5.4
+ */
+export let fromArray = array => {
+  Array.reduce((set, key) => add(key, set), empty, array)
+}
+
+/**
+ * Converts a set into an array of its elements.
+ *
+ * @param set: The set to convert
+ * @returns An array containing all set values
+ * 
+ * @since v0.5.4
+ */
+export let toArray = set => {
+  Array.fromList(toList(set))
+}