@grain/stdlib 0.5.13 → 0.6.0

package/immutableset.gr

@@ -1,498 +0,0 @@
-/**
- * @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))
-}