@grain/stdlib 0.5.7 → 0.5.9

package/number.gr

@@ -16,6 +16,7 @@ import {
   isInteger,
   isRational,
   isBoxedNumber,
+  isNaN,
   scalbn,
 } from "runtime/numbers"
 import Atoi from "runtime/atoi/parse"
@@ -814,8 +815,7 @@ export let isFinite = (x: Number) => {
 }
 
 /**
- * Checks if a number contains the NaN value (Not A Number).
- * Only boxed floating point numbers can contain NaN.
+ * Checks if a number is the float NaN value (Not A Number).
  *
  * @param x: The number to check
  * @returns `true` if the value is NaN, otherwise `false`
@@ -825,25 +825,7 @@ export let isFinite = (x: Number) => {
 @unsafe
 export let isNaN = (x: Number) => {
   let asPtr = WasmI32.fromGrain(x)
-  if (isBoxedNumber(asPtr)) {
-    // Boxed numbers can have multiple subtypes, of which float32 and float64 can be NaN.
-    let tag = WasmI32.load(asPtr, 4n)
-    if (WasmI32.eq(tag, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG)) {
-      // uses the fact that NaN is the only number not equal to itself
-      let wf64 = WasmF64.load(asPtr, 8n)
-      WasmF64.ne(wf64, wf64)
-    } else if (WasmI32.eq(tag, Tags._GRAIN_FLOAT32_BOXED_NUM_TAG)) {
-      let wf32 = WasmF32.load(asPtr, 8n)
-      WasmF32.ne(wf32, wf32)
-    } else {
-      // Neither rational numbers nor boxed integers can be infinite or NaN.
-      // Grain doesn't allow creating a rational with denominator of zero either.
-      false
-    }
-  } else {
-    // Simple numbers are integers and cannot be NaN.
-    false
-  }
+  isNaN(asPtr)
 }
 
 /**

package/number.md

@@ -656,8 +656,7 @@ No other changes yet.
 isNaN : Number -> Bool
 ```
 
-Checks if a number contains the NaN value (Not A Number).
-Only boxed floating point numbers can contain NaN.
+Checks if a number is the float NaN value (Not A Number).
 
 Parameters:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grain/stdlib",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "The standard library for the Grain language.",
   "license": "MIT",
   "homepage": "https://grain-lang.org",

package/runtime/compare.gr

@@ -161,7 +161,7 @@ compareHelp = (x, y) => {
     }
   } else if (isNumber(x)) {
     // Numbers have special comparison rules, e.g. NaN == NaN
-    tagSimpleNumber(numberCompare(x, y, true))
+    tagSimpleNumber(numberCompare(x, y))
   } else {
     // Handle all other heap allocated things
     // Can short circuit if pointers are the same

package/runtime/debugPrint.gr

@@ -0,0 +1,51 @@
+import Utils from "runtime/numberUtils"
+import WasmI32, { add as (+) } from "runtime/unsafe/wasmi32"
+import WasmF64 from "runtime/unsafe/wasmf64"
+import Memory from "runtime/unsafe/memory"
+
+import foreign wasm fd_write: (
+  WasmI32,
+  WasmI32,
+  WasmI32,
+  WasmI32,
+) -> WasmI32 from "wasi_snapshot_preview1"
+
+@unsafe
+export let print = (s: String) => {
+  let ptr = WasmI32.fromGrain(s)
+  // iov: [<ptr to string> <nbytes of string> <ptr to newline> <nbytes of newline>] (32 bytes)
+  // buf: <iov> <written> <newline char>
+  // fd_write(STDOUT (1), iov, len(iov), written)
+  let buf = Memory.malloc(37n)
+  let iov = buf
+  let written = buf + 32n
+  let lf = buf + 36n
+  WasmI32.store(iov, ptr + 8n, 0n)
+  WasmI32.store(iov, WasmI32.load(ptr, 4n), 4n)
+  WasmI32.store8(lf, 10n, 0n)
+  WasmI32.store(iov, lf, 8n)
+  WasmI32.store(iov, 1n, 12n)
+  fd_write(1n, iov, 2n, written)
+  Memory.free(buf)
+  void
+}
+
+@unsafe
+export let printI32 = val => {
+  print(Utils.itoa32(val, 10n))
+}
+
+@unsafe
+export let printI64 = val => {
+  print(Utils.itoa64(val, 10n))
+}
+
+@unsafe
+export let printF32 = val => {
+  print(Utils.dtoa(WasmF64.promoteF32(val)))
+}
+
+@unsafe
+export let printF64 = val => {
+  print(Utils.dtoa(val))
+}

package/runtime/debugPrint.md

@@ -0,0 +1,30 @@
+### DebugPrint.**print**
+
+```grain
+print : String -> Void
+```
+
+### DebugPrint.**printI32**
+
+```grain
+printI32 : WasmI32 -> Void
+```
+
+### DebugPrint.**printI64**
+
+```grain
+printI64 : WasmI64 -> Void
+```
+
+### DebugPrint.**printF32**
+
+```grain
+printF32 : WasmF32 -> Void
+```
+
+### DebugPrint.**printF64**
+
+```grain
+printF64 : WasmF64 -> Void
+```
+

package/runtime/numbers.gr

@@ -107,6 +107,29 @@ export let isRational = x => {
   }
 }
 
+@unsafe
+export let isNaN = x => {
+  if (isBoxedNumber(x)) {
+    // Boxed numbers can have multiple subtypes, of which float32 and float64 can be NaN.
+    let tag = WasmI32.load(x, 4n)
+    if (WasmI32.eq(tag, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG)) {
+      // uses the fact that NaN is the only number not equal to itself
+      let wf64 = WasmF64.load(x, 8n)
+      WasmF64.ne(wf64, wf64)
+    } else if (WasmI32.eq(tag, Tags._GRAIN_FLOAT32_BOXED_NUM_TAG)) {
+      let wf32 = WasmF32.load(x, 8n)
+      WasmF32.ne(wf32, wf32)
+    } else {
+      // Neither rational numbers nor boxed integers can be infinite or NaN.
+      // Grain doesn't allow creating a rational with denominator of zero either.
+      false
+    }
+  } else {
+    // Simple numbers are integers and cannot be NaN.
+    false
+  }
+}
+
 @unsafe
 let isBigInt = x => {
   if (isBoxedNumber(x)) {
@@ -1777,8 +1800,11 @@ let cmpBigInt = (x: WasmI32, y: WasmI32) => {
   }
 }
 
+// cmpFloat applies a total ordering relation:
+// unlike regular float logic, NaN is considered equal to itself and
+// smaller than any other number
 @unsafe
-let cmpFloat = (x: WasmI32, y: WasmI32, is64: Bool, totalOrdering: Bool) => {
+let cmpFloat = (x: WasmI32, y: WasmI32, is64: Bool) => {
   let xf = if (is64) {
     boxedFloat64Number(x)
   } else {
@@ -1787,13 +1813,13 @@ let cmpFloat = (x: WasmI32, y: WasmI32, is64: Bool, totalOrdering: Bool) => {
   if (isSimpleNumber(y)) {
     let yf = WasmF64.convertI32S(untagSimple(y))
     // special NaN cases
-    if (totalOrdering && WasmF64.ne(xf, xf)) {
+    if (WasmF64.ne(xf, xf)) {
       if (WasmF64.ne(yf, yf)) {
         0n
       } else {
         -1n
       }
-    } else if (totalOrdering && WasmF64.ne(yf, yf)) {
+    } else if (WasmF64.ne(yf, yf)) {
       if (WasmF64.ne(xf, xf)) {
         0n
       } else {
@@ -1834,13 +1860,13 @@ let cmpFloat = (x: WasmI32, y: WasmI32, is64: Bool, totalOrdering: Bool) => {
         },
       }
       // special NaN cases
-      if (totalOrdering && WasmF64.ne(xf, xf)) {
+      if (WasmF64.ne(xf, xf)) {
         if (WasmF64.ne(yf, yf)) {
           0n
         } else {
           -1n
         }
-      } else if (totalOrdering && WasmF64.ne(yf, yf)) {
+      } else if (WasmF64.ne(yf, yf)) {
         if (WasmF64.ne(xf, xf)) {
           0n
         } else {
@@ -1854,7 +1880,7 @@ let cmpFloat = (x: WasmI32, y: WasmI32, is64: Bool, totalOrdering: Bool) => {
 }
 
 @unsafe
-let cmpSmallInt = (x: WasmI32, y: WasmI32, is64: Bool, totalOrdering: Bool) => {
+let cmpSmallInt = (x: WasmI32, y: WasmI32, is64: Bool) => {
   let xi = if (is64) {
     boxedInt64Number(x)
   } else {
@@ -1890,10 +1916,10 @@ let cmpSmallInt = (x: WasmI32, y: WasmI32, is64: Bool, totalOrdering: Bool) => {
         ) -1n else 1n
       },
       t when WasmI32.eq(t, Tags._GRAIN_FLOAT32_BOXED_NUM_TAG) => {
-        WasmI32.sub(0n, cmpFloat(y, x, false, totalOrdering))
+        WasmI32.sub(0n, cmpFloat(y, x, false))
       },
       t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
-        WasmI32.sub(0n, cmpFloat(y, x, true, totalOrdering))
+        WasmI32.sub(0n, cmpFloat(y, x, true))
       },
       _ => {
         throw UnknownNumberTag
@@ -1903,7 +1929,7 @@ let cmpSmallInt = (x: WasmI32, y: WasmI32, is64: Bool, totalOrdering: Bool) => {
 }
 
 @unsafe
-let cmpRational = (x: WasmI32, y: WasmI32, totalOrdering: Bool) => {
+let cmpRational = (x: WasmI32, y: WasmI32) => {
   if (isSimpleNumber(y)) {
     let xf = WasmF64.div(
       BI.toFloat64(boxedRationalNumerator(x)),
@@ -1915,10 +1941,10 @@ let cmpRational = (x: WasmI32, y: WasmI32, totalOrdering: Bool) => {
     let yBoxedNumberTag = boxedNumberTag(y)
     match (yBoxedNumberTag) {
       t when WasmI32.eq(t, Tags._GRAIN_INT32_BOXED_NUM_TAG) => {
-        WasmI32.sub(0n, cmpSmallInt(y, x, false, totalOrdering))
+        WasmI32.sub(0n, cmpSmallInt(y, x, false))
       },
       t when WasmI32.eq(t, Tags._GRAIN_INT64_BOXED_NUM_TAG) => {
-        WasmI32.sub(0n, cmpSmallInt(y, x, true, totalOrdering))
+        WasmI32.sub(0n, cmpSmallInt(y, x, true))
       },
       t when WasmI32.eq(t, Tags._GRAIN_BIGINT_BOXED_NUM_TAG) => {
         WasmI32.sub(0n, cmpBigInt(y, x))
@@ -1951,10 +1977,10 @@ let cmpRational = (x: WasmI32, y: WasmI32, totalOrdering: Bool) => {
         }
       },
       t when WasmI32.eq(t, Tags._GRAIN_FLOAT32_BOXED_NUM_TAG) => {
-        WasmI32.sub(0n, cmpFloat(y, x, false, totalOrdering))
+        WasmI32.sub(0n, cmpFloat(y, x, false))
       },
       t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
-        WasmI32.sub(0n, cmpFloat(y, x, true, totalOrdering))
+        WasmI32.sub(0n, cmpFloat(y, x, true))
       },
       _ => {
         throw UnknownNumberTag
@@ -1964,30 +1990,31 @@ let cmpRational = (x: WasmI32, y: WasmI32, totalOrdering: Bool) => {
 }
 
 @unsafe
-export let cmp = (x: WasmI32, y: WasmI32, totalOrdering: Bool) => {
+export let cmp = (x: WasmI32, y: WasmI32) => {
   if (isSimpleNumber(x)) {
     if (isSimpleNumber(y)) {
-      if (WasmI32.ltS(x, y)) -1n else if (WasmI32.gtS(x, y)) 1n else 0n
+      // fast comparison path for simple numbers
+      WasmI32.sub(x, y)
     } else {
       let yBoxedNumberTag = boxedNumberTag(y)
       match (yBoxedNumberTag) {
         t when WasmI32.eq(t, Tags._GRAIN_INT32_BOXED_NUM_TAG) => {
-          WasmI32.sub(0n, cmpSmallInt(y, x, false, totalOrdering))
+          WasmI32.sub(0n, cmpSmallInt(y, x, false))
         },
         t when WasmI32.eq(t, Tags._GRAIN_INT64_BOXED_NUM_TAG) => {
-          WasmI32.sub(0n, cmpSmallInt(y, x, true, totalOrdering))
+          WasmI32.sub(0n, cmpSmallInt(y, x, true))
         },
         t when WasmI32.eq(t, Tags._GRAIN_BIGINT_BOXED_NUM_TAG) => {
           WasmI32.sub(0n, cmpBigInt(y, x))
         },
         t when WasmI32.eq(t, Tags._GRAIN_RATIONAL_BOXED_NUM_TAG) => {
-          WasmI32.sub(0n, cmpRational(y, x, totalOrdering))
+          WasmI32.sub(0n, cmpRational(y, x))
         },
         t when WasmI32.eq(t, Tags._GRAIN_FLOAT32_BOXED_NUM_TAG) => {
-          WasmI32.sub(0n, cmpFloat(y, x, false, totalOrdering))
+          WasmI32.sub(0n, cmpFloat(y, x, false))
         },
         t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
-          WasmI32.sub(0n, cmpFloat(y, x, true, totalOrdering))
+          WasmI32.sub(0n, cmpFloat(y, x, true))
         },
         _ => {
           throw UnknownNumberTag
@@ -1998,22 +2025,22 @@ export let cmp = (x: WasmI32, y: WasmI32, totalOrdering: Bool) => {
     let xBoxedNumberTag = boxedNumberTag(x)
     match (xBoxedNumberTag) {
       t when WasmI32.eq(t, Tags._GRAIN_INT32_BOXED_NUM_TAG) => {
-        cmpSmallInt(x, y, false, totalOrdering)
+        cmpSmallInt(x, y, false)
       },
       t when WasmI32.eq(t, Tags._GRAIN_INT64_BOXED_NUM_TAG) => {
-        cmpSmallInt(x, y, true, totalOrdering)
+        cmpSmallInt(x, y, true)
       },
       t when WasmI32.eq(t, Tags._GRAIN_BIGINT_BOXED_NUM_TAG) => {
         cmpBigInt(x, y)
       },
       t when WasmI32.eq(t, Tags._GRAIN_RATIONAL_BOXED_NUM_TAG) => {
-        cmpRational(x, y, totalOrdering)
+        cmpRational(x, y)
       },
       t when WasmI32.eq(t, Tags._GRAIN_FLOAT32_BOXED_NUM_TAG) => {
-        cmpFloat(x, y, false, totalOrdering)
+        cmpFloat(x, y, false)
       },
       t when WasmI32.eq(t, Tags._GRAIN_FLOAT64_BOXED_NUM_TAG) => {
-        cmpFloat(x, y, true, totalOrdering)
+        cmpFloat(x, y, true)
       },
       _ => {
         throw UnknownNumberTag
@@ -2022,39 +2049,46 @@ export let cmp = (x: WasmI32, y: WasmI32, totalOrdering: Bool) => {
   }
 }
 
+// In the comparison functions below, NaN is neither greater than, less than,
+// or equal to any other number (including NaN), so any comparison involving
+// NaN is always false. The only exception to this rule is `compare`, which
+// applies a total ordering relation to allow numbers to be sortable (with
+// NaN being considered equal to itself and less than all other numbers in
+// this case).
+
 @unsafe
 export let (<) = (x: Number, y: Number) => {
   let x = WasmI32.fromGrain(x)
   let y = WasmI32.fromGrain(y)
-  WasmI32.ltS(cmp(x, y, false), 0n)
+  !isNaN(x) && !isNaN(y) && WasmI32.ltS(cmp(x, y), 0n)
 }
 
 @unsafe
 export let (>) = (x: Number, y: Number) => {
   let x = WasmI32.fromGrain(x)
   let y = WasmI32.fromGrain(y)
-  WasmI32.gtS(cmp(x, y, false), 0n)
+  !isNaN(x) && !isNaN(y) && WasmI32.gtS(cmp(x, y), 0n)
 }
 
 @unsafe
 export let (<=) = (x: Number, y: Number) => {
   let x = WasmI32.fromGrain(x)
   let y = WasmI32.fromGrain(y)
-  WasmI32.leS(cmp(x, y, false), 0n)
+  !isNaN(x) && !isNaN(y) && WasmI32.leS(cmp(x, y), 0n)
 }
 
 @unsafe
 export let (>=) = (x: Number, y: Number) => {
   let x = WasmI32.fromGrain(x)
   let y = WasmI32.fromGrain(y)
-  WasmI32.geS(cmp(x, y, false), 0n)
+  !isNaN(x) && !isNaN(y) && WasmI32.geS(cmp(x, y), 0n)
 }
 
 @unsafe
 export let compare = (x: Number, y: Number) => {
   let x = WasmI32.fromGrain(x)
   let y = WasmI32.fromGrain(y)
-  WasmI32.toGrain(tagSimple(cmp(x, y, true))): Number
+  WasmI32.toGrain(tagSimple(cmp(x, y))): Number
 }
 
 /*

package/runtime/numbers.md

@@ -22,6 +22,12 @@ isInteger : WasmI32 -> Bool
 isRational : WasmI32 -> Bool
 ```
 
+### Numbers.**isNaN**
+
+```grain
+isNaN : WasmI32 -> Bool
+```
+
 ### Numbers.**isNumber**
 
 ```grain
@@ -109,7 +115,7 @@ numberEqual : (WasmI32, WasmI32) -> Bool
 ### Numbers.**cmp**
 
 ```grain
-cmp : (WasmI32, WasmI32, Bool) -> WasmI32
+cmp : (WasmI32, WasmI32) -> WasmI32
 ```
 
 ### Numbers.**(<)**

package/stack.gr

@@ -2,6 +2,7 @@
  * @module Stack: An immutable stack implementation. A stack is a LIFO (last-in-first-out) data structure where new values are added, retrieved, and removed from the end.
  * @example import Stack from "stack"
  *
+ * @since v0.3.0
  * @deprecated This module will be renamed to ImmutableStack in the v0.6.0 release of Grain.
  */
 
@@ -37,6 +38,7 @@ export let empty = {
  *
  * @returns An empty stack
  *
+ * @since v0.3.0
  * @deprecated This will be removed in the v0.6.0 release of Grain.
  */
 export let make = () => {
@@ -48,6 +50,8 @@ export let make = () => {
  *
  * @param stack: The stack to check
  * @returns `true` if the stack has no items or `false` otherwise
+ *
+ * @since v0.3.0
  */
 export let isEmpty = stack => {
   match (stack) {
@@ -61,6 +65,9 @@ export let isEmpty = stack => {
  *
  * @param stack: The stack to inspect
  * @returns `Some(value)` containing the value at the top of the stack or `None` otherwise.
+ *
+ * @since v0.3.0
+ * @history v0.3.1: Rename from `head` to `peek`
  */
 export let peek = stack => {
   match (stack) {
@@ -75,6 +82,8 @@ export let peek = stack => {
  * @param value: The item to be added
  * @param stack: The stack being updated
  * @returns A new stack with the item added to the end
+ *
+ * @since v0.3.0
  */
 export let push = (value, stack) => {
   match (stack) {
@@ -88,6 +97,8 @@ export let push = (value, stack) => {
  *
  * @param stack: The stack being updated
  * @returns A new stack with the last item removed
+ *
+ * @since v0.3.0
  */
 export let pop = stack => {
   match (stack) {
@@ -101,6 +112,8 @@ export let pop = stack => {
  *
  * @param stack: The stack to inspect
  * @returns The count of the items in the stack
+ *
+ * @since v0.3.2
  */
 export let size = stack => {
   match (stack) {

package/stack.md

@@ -6,6 +6,11 @@ title: Stack
 
 An immutable stack implementation. A stack is a LIFO (last-in-first-out) data structure where new values are added, retrieved, and removed from the end.
 
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
 ```grain
 import Stack from "stack"
 ```
@@ -43,6 +48,11 @@ An empty stack.
 
 > **Deprecated:** This will be removed in the v0.6.0 release of Grain.
 
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
 ```grain
 make : () -> Stack<a>
 ```
@@ -57,6 +67,11 @@ Returns:
 
 ### Stack.**isEmpty**
 
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
 ```grain
 isEmpty : Stack<a> -> Bool
 ```
@@ -77,6 +92,18 @@ Returns:
 
 ### Stack.**peek**
 
+<details>
+<summary>Added in <code>0.3.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.3.1</code></td><td>Rename from `head` to `peek`</td></tr>
+</tbody>
+</table>
+</details>
+
 ```grain
 peek : Stack<a> -> Option<a>
 ```
@@ -97,6 +124,11 @@ Returns:
 
 ### Stack.**push**
 
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
 ```grain
 push : (a, Stack<a>) -> Stack<a>
 ```
@@ -118,6 +150,11 @@ Returns:
 
 ### Stack.**pop**
 
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
 ```grain
 pop : Stack<a> -> Stack<a>
 ```
@@ -138,6 +175,11 @@ Returns:
 
 ### Stack.**size**
 
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.2</code></summary>
+No other changes yet.
+</details>
+
 ```grain
 size : Stack<a> -> Number
 ```

package/runtime/unsafe/printWasm.gr

@@ -1,41 +0,0 @@
-import Conv from "runtime/unsafe/conv"
-import WasmI32 from "runtime/unsafe/wasmi32"
-import Memory from "runtime/unsafe/memory"
-
-// [FIXME] These all leak ATM (grain-lang/grain#791)
-
-@unsafe
-export let printI32 = val => {
-  let conv = Conv.toInt32(val)
-  let s1 = toString(conv)
-  let s2 = "n"
-  let s = s1 ++ s2
-  print(s)
-}
-
-@unsafe
-export let printI64 = val => {
-  let conv = Conv.toInt64(val)
-  let s1 = toString(conv)
-  let s2 = "N"
-  let s = s1 ++ s2
-  print(s)
-}
-
-@unsafe
-export let printF32 = val => {
-  let conv = Conv.toFloat32(val)
-  let s1 = toString(conv)
-  let s2 = "w"
-  let s = s1 ++ s2
-  print(s)
-}
-
-@unsafe
-export let printF64 = val => {
-  let conv = Conv.toFloat64(val)
-  let s1 = toString(conv)
-  let s2 = "W"
-  let s = s1 ++ s2
-  print(s)
-}

package/runtime/unsafe/printWasm.md

@@ -1,24 +0,0 @@
-### PrintWasm.**printI32**
-
-```grain
-printI32 : WasmI32 -> Void
-```
-
-### PrintWasm.**printI64**
-
-```grain
-printI64 : WasmI64 -> Void
-```
-
-### PrintWasm.**printF32**
-
-```grain
-printF32 : WasmF32 -> Void
-```
-
-### PrintWasm.**printF64**
-
-```grain
-printF64 : WasmF64 -> Void
-```
-