@grain/stdlib 0.5.2 → 0.5.3

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/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]
 

package/runtime/compare.gr

@@ -0,0 +1,178 @@
+/* grainc-flags --no-pervasives */
+
+import WasmI32, {
+  eq as (==),
+  ne as (!=),
+  and as (&),
+  xor as (^),
+  or as (|),
+  add as (+),
+  sub as (-),
+  mul as (*),
+  ltS as (<),
+  gtS as (>),
+  remS as (%),
+  shl as (<<),
+  shrU as (>>>),
+} from "runtime/unsafe/wasmi32"
+import WasmI64 from "runtime/unsafe/wasmi64"
+import Memory from "runtime/unsafe/memory"
+import Tags from "runtime/unsafe/tags"
+import { tagSimpleNumber } from "runtime/dataStructures"
+import { isNumber, cmp as numberCompare } from "runtime/numbers"
+
+primitive (!): Bool -> Bool = "@not"
+primitive (||): (Bool, Bool) -> Bool = "@or"
+primitive (&&): (Bool, Bool) -> Bool = "@and"
+
+@unsafe
+let zero = WasmI32.fromGrain(0)
+
+@unsafe
+let rec heapCompareHelp = (heapTag, xptr, yptr) => {
+  match (heapTag) {
+    t when t == Tags._GRAIN_ADT_HEAP_TAG => {
+      // Check if the same constructor variant
+      let xvariant = WasmI32.load(xptr, 12n)
+      let yvariant = WasmI32.load(yptr, 12n)
+      if (xvariant != yvariant) {
+        tagSimpleNumber(xvariant - yvariant)
+      } else {
+        let xarity = WasmI32.load(xptr, 16n)
+        let yarity = WasmI32.load(yptr, 16n)
+
+        let mut result = 0
+
+        let bytes = xarity * 4n
+        for (let mut i = 0n; i < bytes; i += 4n) {
+          let sub = compareHelp(
+            WasmI32.load(xptr + i, 20n),
+            WasmI32.load(yptr + i, 20n)
+          )
+          if (WasmI32.fromGrain(sub) != zero) {
+            result = sub
+            break
+          }
+        }
+
+        result
+      }
+    },
+    t when t == Tags._GRAIN_RECORD_HEAP_TAG => {
+      let xlength = WasmI32.load(xptr, 12n)
+      let ylength = WasmI32.load(yptr, 12n)
+
+      let mut result = 0
+
+      let bytes = xlength * 4n
+      for (let mut i = 0n; i < bytes; i += 4n) {
+        let sub = compareHelp(
+          WasmI32.load(xptr + i, 16n),
+          WasmI32.load(yptr + i, 16n)
+        )
+        if (WasmI32.fromGrain(sub) != zero) {
+          result = sub
+          break
+        }
+      }
+
+      result
+    },
+    t when t == Tags._GRAIN_ARRAY_HEAP_TAG => {
+      let xlength = WasmI32.load(xptr, 4n)
+      let ylength = WasmI32.load(yptr, 4n)
+
+      // Check if the same length
+      if (xlength != ylength) {
+        tagSimpleNumber(xlength - ylength)
+      } else {
+        let mut result = 0
+        let bytes = xlength * 4n
+        for (let mut i = 0n; i < bytes; i += 4n) {
+          let sub = compareHelp(
+            WasmI32.load(xptr + i, 8n),
+            WasmI32.load(yptr + i, 8n)
+          )
+          if (WasmI32.fromGrain(sub) != zero) {
+            result = sub
+            break
+          }
+        }
+
+        result
+      }
+    },
+    t when (
+      t == Tags._GRAIN_STRING_HEAP_TAG || t == Tags._GRAIN_BYTES_HEAP_TAG
+    ) => {
+      let xlength = WasmI32.load(xptr, 4n)
+      let ylength = WasmI32.load(yptr, 4n)
+
+      if (xlength == ylength) {
+        tagSimpleNumber(Memory.compare(xptr + 8n, yptr + 8n, xlength))
+      } else {
+        if (xlength < ylength) {
+          let sub = Memory.compare(xptr + 8n, yptr + 8n, xlength)
+          // The shorter one comes first
+          if (sub == 0n) -1 else tagSimpleNumber(sub)
+        } else {
+          let sub = Memory.compare(xptr + 8n, yptr + 8n, ylength)
+          // The shorter one comes first
+          if (sub == 0n) 1 else tagSimpleNumber(sub)
+        }
+      }
+    },
+    t when t == Tags._GRAIN_TUPLE_HEAP_TAG => {
+      let xsize = WasmI32.load(xptr, 4n)
+      let ysize = WasmI32.load(yptr, 4n)
+
+      let mut result = 0
+      let bytes = xsize * 4n
+      for (let mut i = 0n; i < bytes; i += 4n) {
+        let sub = compareHelp(
+          WasmI32.load(xptr + i, 8n),
+          WasmI32.load(yptr + i, 8n)
+        )
+        if (WasmI32.fromGrain(sub) != zero) {
+          result = sub
+          break
+        }
+      }
+
+      result
+    },
+    _ => {
+      // No other implementation
+      tagSimpleNumber(xptr - yptr)
+    },
+  }
+}, compareHelp = (x, y) => {
+  let xtag = x & Tags._GRAIN_GENERIC_TAG_MASK
+  let ytag = y & Tags._GRAIN_GENERIC_TAG_MASK
+  if ((xtag & ytag) != Tags._GRAIN_GENERIC_HEAP_TAG_TYPE) {
+    // Short circuit for non-pointer values
+    if ((xtag & Tags._GRAIN_NUMBER_TAG_MASK) == Tags._GRAIN_NUMBER_TAG_TYPE) {
+      // Signed comparisons are necessary for numbers
+      if (x < y) -1 else if (x > y) 1 else 0
+    } else {
+      // Unsigned comparisons are necessary for other stack-allocated values
+      if (WasmI32.ltU(x, y)) -1 else if (WasmI32.gtU(x, y)) 1 else 0
+    }
+  } else if (isNumber(x)) {
+    // Numbers have special comparison rules, e.g. NaN == NaN
+    tagSimpleNumber(numberCompare(x, y, true))
+  } else {
+    // Handle all other heap allocated things
+    // Can short circuit if pointers are the same
+    if (x == y) {
+      0
+    } else {
+      heapCompareHelp(WasmI32.load(x, 0n), x, y)
+    }
+  }
+}
+
+@unsafe
+export let compare = (x: a, y: a) => {
+  compareHelp(WasmI32.fromGrain(x), WasmI32.fromGrain(y))
+}

package/runtime/compare.md

@@ -0,0 +1,6 @@
+### Compare.**compare**
+
+```grain
+compare : (a, a) -> Number
+```
+

package/runtime/equal.gr

@@ -14,13 +14,12 @@ import WasmI32, {
 } from "runtime/unsafe/wasmi32"
 import WasmI64 from "runtime/unsafe/wasmi64"
 import Tags from "runtime/unsafe/tags"
+import { isNumber, numberEqual } from "runtime/numbers"
 
 primitive (!): Bool -> Bool = "@not"
 primitive (||): (Bool, Bool) -> Bool = "@or"
 primitive (&&): (Bool, Bool) -> Bool = "@and"
 
-import { isNumber, numberEqual } from "runtime/numbers"
-
 @unsafe
 let cycleMarker = 0x80000000n