@grain/stdlib 0.5.3 → 0.5.5

package/immutablemap.md

@@ -0,0 +1,479 @@
+---
+title: ImmutableMap
+---
+
+An ImmutableMap holds key-value pairs. Any value may be used as a key or value. Operations on an ImmutableMap do not mutate the map's internal state.
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+import ImmutableMap from "immutablemap"
+```
+
+## Types
+
+Type declarations included in the ImmutableMap module.
+
+### ImmutableMap.**ImmutableMap**
+
+```grain
+type ImmutableMap<k, v>
+```
+
+## Values
+
+Functions and constants for working with ImmutableMaps.
+
+### ImmutableMap.**empty**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+empty : ImmutableMap<a, b>
+```
+
+An empty map
+
+### ImmutableMap.**size**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+size : ImmutableMap<a, b> -> Number
+```
+
+Provides the count of key-value pairs stored within the map.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`ImmutableMap<a, b>`|The map to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The count of key-value pairs in the map|
+
+### ImmutableMap.**isEmpty**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isEmpty : ImmutableMap<a, b> -> Bool
+```
+
+Determines if the map contains no key-value pairs.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`ImmutableMap<a, b>`|The map to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the given map is empty or `false` otherwise|
+
+### ImmutableMap.**set**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+set : (a, b, ImmutableMap<a, b>) -> ImmutableMap<a, b>
+```
+
+Produces a new map containing a new key-value pair. If the key already exists in the map, the value is replaced.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`key`|`a`|The unique key in the map|
+|`value`|`b`|The value to store|
+|`map`|`ImmutableMap<a, b>`|The base map|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableMap<a, b>`|A new map containing the new key-value pair|
+
+### ImmutableMap.**get**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+get : (a, ImmutableMap<a, b>) -> Option<b>
+```
+
+Retrieves the value for the given key.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`key`|`a`|The key to access|
+|`map`|`ImmutableMap<a, b>`|The map to access|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<b>`|`Some(value)` if the key exists in the map or `None` otherwise|
+
+### ImmutableMap.**contains**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+contains : (a, ImmutableMap<a, b>) -> Bool
+```
+
+Determines if the map contains the given key. In such a case, it will always contain a value for the given key.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`key`|`a`|The key to search for|
+|`map`|`ImmutableMap<a, b>`|The map to search|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the map contains the given key or `false` otherwise|
+
+### ImmutableMap.**remove**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+remove : (a, ImmutableMap<a, b>) -> ImmutableMap<a, b>
+```
+
+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.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`key`|`a`|The key to exclude|
+|`map`|`ImmutableMap<a, b>`|The map to exclude from|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableMap<a, b>`|A new map without the given key|
+
+### ImmutableMap.**update**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+update :
+  (a, (Option<b> -> Option<b>), ImmutableMap<a, b>) -> ImmutableMap<a, b>
+```
+
+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.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`key`|`a`|The unique key in the map|
+|`fn`|`Option<b> -> Option<b>`|The updater function|
+|`map`|`ImmutableMap<a, b>`|The base map|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableMap<a, b>`|A new map with the value at the given key modified according to the function's output|
+
+### ImmutableMap.**forEach**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+forEach : (((a, b) -> Void), ImmutableMap<a, b>) -> Void
+```
+
+Iterates the map, calling an iterator function with each key and value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`(a, b) -> Void`|The iterator function to call with each key and value|
+|`map`|`ImmutableMap<a, b>`|The map to iterate|
+
+### ImmutableMap.**reduce**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+reduce : (((a, b, c) -> a), a, ImmutableMap<b, c>) -> a
+```
+
+Combines all key-value pairs of a map using a reducer function.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`(a, b, c) -> a`|The reducer function to call on each key and value, where the value returned will be the next accumulator value|
+|`init`|`a`|The initial value to use for the accumulator on the first iteration|
+|`map`|`ImmutableMap<b, c>`|The map to iterate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`a`|The final accumulator returned from `fn`|
+
+### ImmutableMap.**keys**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+keys : ImmutableMap<a, b> -> List<a>
+```
+
+Enumerates all keys in the given map.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`ImmutableMap<a, b>`|The map to enumerate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<a>`|A list containing all keys from the given map|
+
+### ImmutableMap.**values**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+values : ImmutableMap<a, b> -> List<b>
+```
+
+Enumerates all values in the given map.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`ImmutableMap<a, b>`|The map to enumerate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<b>`|A list containing all values from the given map|
+
+### ImmutableMap.**filter**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+filter : (((a, b) -> Bool), ImmutableMap<a, b>) -> ImmutableMap<a, b>
+```
+
+Produces a new map excluding the key-value pairs where a predicate function returns `false`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`(a, b) -> Bool`|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|
+|`map`|`ImmutableMap<a, b>`|The map to iterate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableMap<a, b>`|A new map excluding the key-value pairs not fulfilling the predicate|
+
+### ImmutableMap.**reject**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+reject : (((a, b) -> Bool), ImmutableMap<a, b>) -> ImmutableMap<a, b>
+```
+
+Produces a new map excluding the key-value pairs where a predicate function returns `true`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`(a, b) -> Bool`|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|
+|`map`|`ImmutableMap<a, b>`|The map to iterate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableMap<a, b>`|A new map excluding the key-value pairs fulfilling the predicate|
+
+### ImmutableMap.**fromList**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromList : List<(a, b)> -> ImmutableMap<a, b>
+```
+
+Creates a map from a list.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`list`|`List<(a, b)>`|The list to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableMap<a, b>`|A map containing all key-value pairs from the list|
+
+### ImmutableMap.**toList**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toList : ImmutableMap<a, b> -> List<(a, b)>
+```
+
+Enumerates all key-value pairs in the given map.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`ImmutableMap<a, b>`|The map to enumerate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<(a, b)>`|A list containing all key-value pairs from the given map|
+
+### ImmutableMap.**fromArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromArray : Array<(a, b)> -> ImmutableMap<a, b>
+```
+
+Creates a map from an array.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`array`|`Array<(a, b)>`|The array to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableMap<a, b>`|A map containing all key-value pairs from the array|
+
+### ImmutableMap.**toArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toArray : ImmutableMap<a, b> -> Array<(a, b)>
+```
+
+Converts a map into an array of its key-value pairs.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`map`|`ImmutableMap<a, b>`|The map to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Array<(a, b)>`|An array containing all key-value pairs from the given map|
+

package/immutablepriorityqueue.gr

@@ -7,6 +7,7 @@
  */
 
 import List from "list"
+import Array from "array"
 
 // implementation based on immutable skew binomial queue with global root optimization
 // as described in the paper "Optimal Purely Functional Priority Queues" by Chris Okasaki.
@@ -40,18 +41,28 @@ record ImmutablePriorityQueue<a> {
 }
 
 /**
- * @section Values: Functions for working with ImmutablePriorityQueues.
+ * @section Values: Functions and constants for working with ImmutablePriorityQueues.
  */
 
+/**
+ * An empty priority queue with the default `compare` comparator.
+ *
+ * @since v0.5.4
+ */
+export let empty = {
+  let empty = { comp: compare, size: 0, root: None }
+  empty
+}
+
 /**
  * Creates a new priority queue with a comparator function, which is used to
  * determine priority of elements. The comparator function takes two elements
  * and must return 0 if both share priority, a positive number if the first
  * has greater priority, and a negative number if the first has less priority.
- * 
+ *
  * @param comp: The comparator function used to indicate priority order
  * @returns An empty priority queue
- * 
+ *
  * @example ImmutablePriorityQueue.make(compare) // creates a min priority queue of numbers using the compare pervasive
  * @example ImmutablePriorityQueue.make((a, b) => String.length(b) - String.length(a)) // creates a priority queue by string length (longest to shortest)
  *
@@ -63,7 +74,7 @@ export let make = comp => {
 
 /**
  * Gets the number of elements in a priority queue.
- * 
+ *
  * @param pq: The priority queue to inspect
  * @returns The number of elements in the priority queue
  *
@@ -75,7 +86,7 @@ export let size = pq => {
 
 /**
  * Determines if the priority queue contains no elements.
- * 
+ *
  * @param pq: The priority queue to check
  * @returns `true` if the priority queue is empty and `false` otherwise
  *
@@ -120,7 +131,7 @@ let skewInsert = (comp, val, pq) => {
 
 /**
  * Produces a new priority queue by inserting the given element into the given priority queue.
- * 
+ *
  * @param val: The value to add into the priority queue
  * @param pq: The priority queue
  * @returns A new priority queue with the given element inserted
@@ -131,8 +142,8 @@ export let push = (val, pq) => {
     None => { comp, size: 1, root: Some({ rootVal: val, pq: [] }) },
     Some({ rootVal, pq }) => {
       // make the new value the root if it has higher priority than the highest priority value
-      let (morePriorityVal, lessPriorityVal) = if (comp(val, rootVal) <= 0)
-          (val, rootVal) else (rootVal, val)
+      let (morePriorityVal, lessPriorityVal) =
+        if (comp(val, rootVal) <= 0) (val, rootVal) else (rootVal, val)
 
       let newRoot = Some(
         { rootVal: morePriorityVal, pq: skewInsert(comp, lessPriorityVal, pq) }
@@ -145,7 +156,7 @@ export let push = (val, pq) => {
 /**
  * Retrieves the highest priority element in the priority queue. It is not
  * removed from the queue.
- * 
+ *
  * @param pq: The priority queue to inspect
  * @returns `Some(value)` containing the highest priority element or `None` if the priority queue is empty
  *
@@ -161,8 +172,8 @@ export let peek = pq => {
 let linkNodes = (comp, node1, node2) => {
   // make the node with higher priority the parent of the node with smaller
   // priority to presere heap-ordering
-  let (morePriority, lessPriority) = if (comp(node1.val, node2.val) <= 0)
-      (node1, node2) else (node2, node1)
+  let (morePriority, lessPriority) =
+    if (comp(node1.val, node2.val) <= 0) (node1, node2) else (node2, node1)
   {
     val: morePriority.val,
     rank: morePriority.rank + 1,
@@ -216,7 +227,7 @@ let merge = (comp, pq1, pq2) =>
 let rec separateHighestPriority = (comp, pq) => {
   match (pq) {
     // empty list case should never happen; this is here just to satisfy the compiler
-    [] => fail "getHighestPriority called with empty PQ",
+    [] => fail "Impossible: getHighestPriority called with empty PQ",
     [node] => (node, []),
     [node, ...rest] => {
       let (currMinNode, currNonMinNodes) = separateHighestPriority(comp, rest)
@@ -256,7 +267,7 @@ let withoutHighestPriority = (comp, pq) => {
 let rec findHighestPriority = (comp, pq) => {
   match (pq) {
     // empty list case should never happen; this is here just to satisfy the compiler
-    [] => fail "findHighestPriority with empty PQ",
+    [] => fail "Impossible: findHighestPriority with empty PQ",
     [node] => node.val,
     [node, ...rest] => {
       let currMin = findHighestPriority(comp, rest)
@@ -269,7 +280,7 @@ let rec findHighestPriority = (comp, pq) => {
  * Produces a new priority queue without the highest priority element in the
  * given priority queue. If the input priority queue is empty, this function will
  * return it.
- * 
+ *
  * @param pq: The priority queue
  * @returns A new priority queue without the highest priority element
  *
@@ -298,7 +309,7 @@ export let pop = pq => {
 
 /**
  * Produces a list of all elements in the priority queue in priority order.
- * 
+ *
  * @param pq: The priority queue to drain
  * @returns A list of all elements in the priority in priority order
  *
@@ -320,7 +331,7 @@ export let drain = pq => {
  * elements. The comparator function takes two elements and must return 0 if
  * both share priority, a positive number if the first has greater priority,
  * and a negative number if the first has less priority.
- * 
+ *
  * @param list: A list of values used to initialize the priority queue
  * @param comp: A comparator function used to assign priority to elements
  * @returns A priority queue containing the elements from the list
@@ -330,3 +341,20 @@ export let drain = pq => {
 export let fromList = (list, comp) => {
   List.reduce((pq, val) => push(val, pq), make(comp), list)
 }
+
+/**
+ * Constructs a new priority queue initialized with the elements in the array
+ * using a custom comparator function, which is used to determine priority of
+ * elements. The comparator function takes two elements and must return 0 if
+ * both share priority, a positive number if the first has greater priority,
+ * and a negative number if the first has less priority.
+ *
+ * @param array: An array of values used to initialize the priority queue
+ * @param comp: A comparator function used to assign priority to elements
+ * @returns A priority queue containing the elements from the array
+ *
+ * @since v0.5.4
+ */
+export let fromArray = (array, comp) => {
+  Array.reduce((pq, val) => push(val, pq), make(comp), array)
+}

package/immutablepriorityqueue.md

@@ -27,7 +27,20 @@ Immutable data structure which maintains a priority order for its elements.
 
 ## Values
 
-Functions for working with ImmutablePriorityQueues.
+Functions and constants for working with ImmutablePriorityQueues.
+
+### ImmutablePriorityQueue.**empty**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+empty : ImmutablePriorityQueue<a>
+```
+
+An empty priority queue with the default `compare` comparator.
 
 ### ImmutablePriorityQueue.**make**
 
@@ -246,3 +259,33 @@ Returns:
 |----|-----------|
 |`ImmutablePriorityQueue<a>`|A priority queue containing the elements from the list|
 
+### ImmutablePriorityQueue.**fromArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromArray : (Array<a>, ((a, a) -> Number)) -> ImmutablePriorityQueue<a>
+```
+
+Constructs a new priority queue initialized with the elements in the array
+using a custom comparator function, which is used to determine priority of
+elements. The comparator function takes two elements and must return 0 if
+both share priority, a positive number if the first has greater priority,
+and a negative number if the first has less priority.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`array`|`Array<a>`|An array of values used to initialize the priority queue|
+|`comp`|`(a, a) -> Number`|A comparator function used to assign priority to elements|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutablePriorityQueue<a>`|A priority queue containing the elements from the array|
+