@grain/stdlib 0.5.0 → 0.5.3

package/priorityqueue.gr

@@ -0,0 +1,241 @@
+/**
+ * @module PriorityQueue: A mutable priority queue implementation. A priority queue is a data structure that maintains elements in a priority order. Elements with higher priority are served before elements with lower priority when extracting from the priority queue.
+ *
+ * @example import PriorityQueue from "priorityqueue"
+ *
+ * @since v0.5.3
+ */
+
+import Array from "array"
+import List from "list"
+import Number from "number"
+import Option from "option"
+
+/**
+ * @section Types: Type declarations included in the PriorityQueue module.
+ */
+
+/**
+ * Mutable data structure which maintains a priority order for its elements.
+ */
+record PriorityQueue<a> {
+  mut size: Number,
+  mut array: Array<Option<a>>,
+  comp: (a, a) -> Number,
+}
+
+/**
+ * @section Values: Functions for working with PriorityQueues.
+ */
+
+let swap = (i1, i2, array) => {
+  let t = array[i2]
+  array[i2] = array[i1]
+  array[i1] = t
+}
+
+let get = (array, i) =>
+  Option.expect(
+    "Impossible: " ++
+    toString(i) ++
+    " in PriorityQueue's inner storage array is None",
+    array[i]
+  )
+
+let rec siftDown = (i, pq) => {
+  let leftI = 2 * i + 1
+  let rightI = 2 * i + 2
+
+  // we want to find the smaller child from the current tree node to sift down to
+  let mut swapWithI = i
+  if (leftI < pq.size && pq.comp(get(pq.array, leftI), get(pq.array, i)) < 0) {
+    swapWithI = leftI
+  }
+  if (
+    rightI < pq.size &&
+    pq.comp(get(pq.array, rightI), get(pq.array, swapWithI)) < 0
+  ) {
+    swapWithI = rightI
+  }
+  if (swapWithI != i) {
+    swap(i, swapWithI, pq.array)
+    siftDown(swapWithI, pq)
+  }
+}
+
+let rec siftUp = (i, pq) => {
+  let parentI = Number.trunc((i - 1) / 2)
+  // we should only sift up if the element is smaller than its parent
+  if (i > 0 && pq.comp(get(pq.array, i), get(pq.array, parentI)) < 0) {
+    swap(i, parentI, pq.array)
+    siftUp(parentI, pq)
+  }
+}
+
+/**
+ * Creates a new priority queue with a given internal storage size and 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.
+ * 
+ * Generally, you won't need to care about the storage size of your priority
+ * queue and can use `PriorityQueue.make()` instead.
+ * 
+ * @param size: The initial storage size of the priority queue
+ * @param comp: The comparator function used to indicate priority order
+ * @returns An empty priority queue
+ *
+ * @since v0.5.3
+ */
+export let makeSized = (size, comp) => {
+  { size: 0, array: Array.make(size, None), comp }
+}
+
+/**
+ * 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 PriorityQueue.make(compare) // creates a min priority queue of numbers using the compare pervasive
+ * @example PriorityQueue.make((a, b) => String.length(b) - String.length(a)) // creates a priority queue by string length (longest to shortest)
+ *
+ * @since v0.5.3
+ */
+export let make = comp => {
+  makeSized(16, 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
+ *
+ * @since v0.5.3
+ */
+export let size = pq => {
+  pq.size
+}
+
+/**
+ * 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
+ *
+ * @since v0.5.3
+ */
+export let isEmpty = pq => {
+  pq.size == 0
+}
+
+/**
+ * Adds a new element to the priority queue.
+ * 
+ * @param val: The value to add into the priority queue
+ * @param pq: The priority queue to update
+ *
+ * @since v0.5.3
+ */
+export let push = (val, pq) => {
+  let arrLen = Array.length(pq.array)
+  // double size of internal array if out of space
+  if (pq.size == arrLen) {
+    let oldArr = pq.array
+    pq.array = Array.make(arrLen * 2, None)
+    Array.forEachi((val, i) => {
+      pq.array[i] = val
+    }, oldArr)
+  }
+  pq.array[pq.size] = Some(val)
+  pq.size += 1
+  // reorder heap to ensure that binary heap property of parent nodes having
+  // larger values than their children is upheld
+  siftUp(pq.size - 1, 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
+ *
+ * @since v0.5.3
+ */
+export let peek = pq => {
+  if (pq.size == 0) {
+    None
+  } else {
+    pq.array[0]
+  }
+}
+
+/**
+ * Removes and retrieves the highest priority element in the priority queue.
+ * 
+ * @param pq: The priority queue to inspect
+ * @returns `Some(value)` containing the highest priority element or `None` if the priority queue is empty
+ *
+ * @since v0.5.3
+ */
+export let pop = pq => {
+  if (pq.size == 0) {
+    None
+  } else {
+    let root = pq.array[0]
+
+    pq.array[0] = pq.array[pq.size - 1]
+    pq.array[pq.size - 1] = None
+    pq.size -= 1
+    // reorder heap to ensure that binary heap property of parent nodes having
+    // larger values than their children is upheld
+    siftDown(0, pq)
+    root
+  }
+}
+
+/**
+ * Clears the priority queue and produces a list of all of the 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
+ *
+ * @since v0.5.3
+ */
+export let drain = pq => {
+  let rec drainRec = acc => {
+    match (pop(pq)) {
+      Some(val) => drainRec([val, ...acc]),
+      None => acc,
+    }
+  }
+  List.reverse(drainRec([]))
+}
+
+/**
+ * Constructs a new priority queue initialized with the elements in the list
+ * 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 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
+ *
+ * @since v0.5.3
+ */
+export let fromList = (list, comp) => {
+  let heap = makeSized(List.length(list), comp)
+  List.forEach(val => {
+    push(val, heap)
+  }, list)
+  heap
+}

package/priorityqueue.md

@@ -0,0 +1,279 @@
+---
+title: PriorityQueue
+---
+
+A mutable priority queue implementation. A priority queue is a data structure that maintains elements in a priority order. Elements with higher priority are served before elements with lower priority when extracting from the priority queue.
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+import PriorityQueue from "priorityqueue"
+```
+
+## Types
+
+Type declarations included in the PriorityQueue module.
+
+### PriorityQueue.**PriorityQueue**
+
+```grain
+type PriorityQueue<a>
+```
+
+Mutable data structure which maintains a priority order for its elements.
+
+## Values
+
+Functions for working with PriorityQueues.
+
+### PriorityQueue.**makeSized**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+makeSized : (Number, ((a, a) -> Number)) -> PriorityQueue<a>
+```
+
+Creates a new priority queue with a given internal storage size and 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.
+
+Generally, you won't need to care about the storage size of your priority
+queue and can use `PriorityQueue.make()` instead.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`size`|`Number`|The initial storage size of the priority queue|
+|`comp`|`(a, a) -> Number`|The comparator function used to indicate priority order|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`PriorityQueue<a>`|An empty priority queue|
+
+### PriorityQueue.**make**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+make : ((a, a) -> Number) -> PriorityQueue<a>
+```
+
+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.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`comp`|`(a, a) -> Number`|The comparator function used to indicate priority order|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`PriorityQueue<a>`|An empty priority queue|
+
+Examples:
+
+```grain
+PriorityQueue.make(compare) // creates a min priority queue of numbers using the compare pervasive
+```
+
+```grain
+PriorityQueue.make((a, b) => String.length(b) - String.length(a)) // creates a priority queue by string length (longest to shortest)
+```
+
+### PriorityQueue.**size**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+size : PriorityQueue<a> -> Number
+```
+
+Gets the number of elements in a priority queue.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`pq`|`PriorityQueue<a>`|The priority queue to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The number of elements in the priority queue|
+
+### PriorityQueue.**isEmpty**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isEmpty : PriorityQueue<a> -> Bool
+```
+
+Determines if the priority queue contains no elements.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`pq`|`PriorityQueue<a>`|The priority queue to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the priority queue is empty and `false` otherwise|
+
+### PriorityQueue.**push**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+push : (a, PriorityQueue<a>) -> Void
+```
+
+Adds a new element to the priority queue.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`val`|`a`|The value to add into the priority queue|
+|`pq`|`PriorityQueue<a>`|The priority queue to update|
+
+### PriorityQueue.**peek**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+peek : PriorityQueue<a> -> Option<a>
+```
+
+Retrieves the highest priority element in the priority queue. It is not
+removed from the queue.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`pq`|`PriorityQueue<a>`|The priority queue to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<a>`|`Some(value)` containing the highest priority element or `None` if the priority queue is empty|
+
+### PriorityQueue.**pop**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+pop : PriorityQueue<a> -> Option<a>
+```
+
+Removes and retrieves the highest priority element in the priority queue.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`pq`|`PriorityQueue<a>`|The priority queue to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<a>`|`Some(value)` containing the highest priority element or `None` if the priority queue is empty|
+
+### PriorityQueue.**drain**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+drain : PriorityQueue<a> -> List<a>
+```
+
+Clears the priority queue and produces a list of all of the elements in the priority
+queue in priority order.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`pq`|`PriorityQueue<a>`|The priority queue to drain|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<a>`|A list of all elements in the priority in priority order|
+
+### PriorityQueue.**fromList**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromList : (List<a>, ((a, a) -> Number)) -> PriorityQueue<a>
+```
+
+Constructs a new priority queue initialized with the elements in the list
+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|
+|-----|----|-----------|
+|`list`|`List<a>`|A list of values used to initialize the priority queue|
+|`comp`|`(a, a) -> Number`|A comparator function used to assign priority to elements|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`PriorityQueue<a>`|A priority queue containing the elements from the list|
+

package/random.md

@@ -5,7 +5,7 @@ title: Random
 Pseudo-random number generation.
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.0</code></summary>
 No other changes yet.
 </details>
 
@@ -30,7 +30,7 @@ Functions for working with pseudo-random number generators.
 ### Random.**make**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.0</code></summary>
 No other changes yet.
 </details>
 
@@ -55,7 +55,7 @@ Returns:
 ### Random.**makeUnseeded**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.0</code></summary>
 No other changes yet.
 </details>
 
@@ -74,7 +74,7 @@ Returns:
 ### Random.**nextInt32**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.0</code></summary>
 No other changes yet.
 </details>
 
@@ -99,7 +99,7 @@ Returns:
 ### Random.**nextInt64**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.0</code></summary>
 No other changes yet.
 </details>
 
@@ -124,7 +124,7 @@ Returns:
 ### Random.**nextInt32InRange**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.0</code></summary>
 No other changes yet.
 </details>
 
@@ -152,7 +152,7 @@ Returns:
 ### Random.**nextInt64InRange**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.0</code></summary>
 No other changes yet.
 </details>
 

package/regex.gr

@@ -487,7 +487,7 @@ enum MergeMode {
 }
 
 let mergeAdjacent = lst => {
-  // see [TODO] below
+  // TODO: see below
   let readyForAccum = (l, mode) => {
     match (l) {
       [] => true,
@@ -512,7 +512,7 @@ let mergeAdjacent = lst => {
       // drop empty elements
       [REEmpty, ...tl] => loop(mode, accum, tl),
       [RELiteralString(""), ...tl] => loop(mode, accum, tl),
-      // [TODO] Clean up with or-patterns (grain-lang/grain#696)
+      // TODO(#696): Clean up with or-patterns
       _ when readyForAccum(l, mode) => {
         match (accum) {
           [] => [],
@@ -592,7 +592,7 @@ REGEX PARSING DEFINITIONS
 
 // Range parsing ("[a-z]")
 
-// [TODO] (#769) When byte-based regexes are supported, we'll need another limit of 255 for those.
+// TODO(#769): When byte-based regexes are supported, we'll need another limit of 255 for those.
 let rangeLimit = 0x10FFFF
 
 // These are snake-cased to avoid confusion with their capitalized counterparts
@@ -1578,7 +1578,7 @@ let rec parseAtom = (buf: RegExBuf) => {
         Err(
           parseErr(buf, "unmatched `" ++ Char.toString(c) ++ "` in pattern", 0)
         ),
-      // [TODO] case-insensitive (#691)
+      // TODO(#691): Enable case-insensitive regular expression matching
       Ok(c) when buf.config.caseSensitive => {
         ignore(next(buf))
         Ok(RELiteral(c))
@@ -3320,7 +3320,7 @@ record RegularExpression {
  * @section Values: Functions for working with regular expressions.
  */
 
-// [TODO] When #661 is resolved, re-add the following pieces of documentation:
+// TODO(#661): re-add the following pieces of documentation:
 /*
  [Under POSIX character classes]