feat(stdlib): Implement fromArray in PriorityQueue & ImmutablePriorityQueue modules (#1451)

feat(stdlib): Improved efficiency of constructing a PriorityQueue from a List

Author: alex-snezhko

compiler/test/stdlib/immutablepriorityqueue.test.gr

@@ -88,3 +88,6 @@ assert ImmutablePriorityQueue.drain(
   ImmutablePriorityQueue.fromList(Array.toList(lotsOfVals), (a, b) => b - a)
 ) ==
 List.reverse(sortedList)
+
+assert ImmutablePriorityQueue.fromList(Array.toList(lotsOfVals), compare) ==
+ImmutablePriorityQueue.fromArray(lotsOfVals, compare)

compiler/test/stdlib/priorityqueue.test.gr

@@ -78,3 +78,6 @@ assert PriorityQueue.drain(
   PriorityQueue.fromList(Array.toList(lotsOfVals), (a, b) => b - a)
 ) ==
 List.reverse(sortedList)
+
+assert PriorityQueue.fromList(Array.toList(lotsOfVals), compare) ==
+PriorityQueue.fromArray(lotsOfVals, compare)

stdlib/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.
@@ -330,3 +331,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)
+}

stdlib/immutablepriorityqueue.md

@@ -246,3 +246,33 @@ Returns:
 |----|-----------|
 |`ImmutablePriorityQueue<a>`|A priority queue containing the elements from the list|
 
+### ImmutablePriorityQueue.**fromArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>next</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|
+

stdlib/priorityqueue.gr

@@ -219,6 +219,29 @@ export let drain = pq => {
   List.reverse(drainRec([]))
 }
 
+/**
+ * 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) => {
+  let size = Array.length(array)
+  let array = Array.map(x => Some(x), array)
+  let heap = { size, array, comp }
+  for (let mut i = size - 1; i >= 0; i -= 1) {
+    siftDown(i, heap)
+  }
+  heap
+}
+
 /**
  * Constructs a new priority queue initialized with the elements in the list
  * using a custom comparator function, which is used to determine priority of
@@ -233,9 +256,6 @@ export let drain = pq => {
  * @since v0.5.3
  */
 export let fromList = (list, comp) => {
-  let heap = makeSized(List.length(list), comp)
-  List.forEach(val => {
-    push(val, heap)
-  }, list)
-  heap
+  let array = Array.fromList(list)
+  fromArray(array, comp)
 }

stdlib/priorityqueue.md

@@ -247,6 +247,36 @@ Returns:
 |----|-----------|
 |`List<a>`|A list of all elements in the priority in priority order|
 
+### PriorityQueue.**fromArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>next</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromArray : (Array<a>, ((a, a) -> Number)) -> PriorityQueue<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|
+|----|-----------|
+|`PriorityQueue<a>`|A priority queue containing the elements from the array|
+
 ### PriorityQueue.**fromList**
 
 <details disabled>