@grain/stdlib 0.5.13 → 0.6.1

package/int64.gr

@@ -1,47 +1,42 @@
 /**
- * @module Int64: Utilities for working with the Int64 type.
- * @example import Int64 from "int64"
+ * Utilities for working with the Int64 type.
+ *
+ * @example from "int64" include Int64
  *
  * @since v0.2.0
  */
-import WasmI32 from "runtime/unsafe/wasmi32"
-import WasmI64 from "runtime/unsafe/wasmi64"
-import Exception from "runtime/exception"
+module Int64
+
+from "runtime/unsafe/wasmi32" include WasmI32
+from "runtime/unsafe/wasmi64" include WasmI64
+use WasmI64.{ (==), (!=), (&), (|), (^), (<<), (>>), (<), (<=), (>), (>=) }
+from "runtime/exception" include Exception
 
-import { newInt64 } from "runtime/dataStructures"
+from "runtime/dataStructures" include DataStructures
+use DataStructures.{ newInt64 }
 
-import {
+from "runtime/numbers" include Numbers
+use Numbers.{
   coerceNumberToInt64 as fromNumber,
   coerceInt64ToNumber as toNumber,
-} from "runtime/numbers"
+}
 
-/**
- * @section Conversions: Functions for converting between Numbers and the Int64 type.
- */
+provide { fromNumber, toNumber }
 
 /**
- * Converts a Number to an Int64.
+ * Converts a Uint64 to an Int64.
  *
  * @param number: The value to convert
- * @returns The Number represented as an Int64
- *
- * @since v0.2.0
- */
-export fromNumber
-
-/**
- * Converts an Int64 to a Number.
- *
- * @param value: The value to convert
- * @returns The Int64 represented as a Number
+ * @returns The Uint64 represented as an Int64
  *
- * @since v0.2.0
- */
-export toNumber
-
-/**
- * @section Operations: Mathematical operations for Int64 values.
+ * @since v0.6.0
  */
+@unsafe
+provide let fromUint64 = (number: Uint64) => {
+  let x = WasmI64.load(WasmI32.fromGrain(number), 8n)
+  let result = newInt64(x)
+  WasmI32.toGrain(result): Int64
+}
 
 /**
  * Increments the value by one.
@@ -52,9 +47,10 @@ export toNumber
  * @since v0.2.0
  */
 @unsafe
-export let incr = (value: Int64) => {
+provide let incr = (value: Int64) => {
+  use WasmI64.{ (+) }
   let value = WasmI32.fromGrain(value)
-  let ptr = newInt64(WasmI64.add(WasmI64.load(value, 8n), 1N))
+  let ptr = newInt64(WasmI64.load(value, 8n) + 1N)
   WasmI32.toGrain(ptr): Int64
 }
 
@@ -67,9 +63,10 @@ export let incr = (value: Int64) => {
  * @since v0.2.0
  */
 @unsafe
-export let decr = (value: Int64) => {
+provide let decr = (value: Int64) => {
+  use WasmI64.{ (-) }
   let value = WasmI32.fromGrain(value)
-  let ptr = newInt64(WasmI64.sub(WasmI64.load(value, 8n), 1N))
+  let ptr = newInt64(WasmI64.load(value, 8n) - 1N)
   WasmI32.toGrain(ptr): Int64
 }
 
@@ -80,13 +77,15 @@ export let decr = (value: Int64) => {
  * @param y: The second operand
  * @returns The sum of the two operands
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `add`
  */
 @unsafe
-export let add = (x: Int64, y: Int64) => {
+provide let (+) = (x: Int64, y: Int64) => {
+  use WasmI64.{ (+) }
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt64(WasmI64.add(xv, yv))
+  let ptr = newInt64(xv + yv)
   WasmI32.toGrain(ptr): Int64
 }
 
@@ -97,13 +96,15 @@ export let add = (x: Int64, y: Int64) => {
  * @param y: The second operand
  * @returns The difference of the two operands
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `sub`
  */
 @unsafe
-export let sub = (x: Int64, y: Int64) => {
+provide let (-) = (x: Int64, y: Int64) => {
+  use WasmI64.{ (-) }
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt64(WasmI64.sub(xv, yv))
+  let ptr = newInt64(xv - yv)
   WasmI32.toGrain(ptr): Int64
 }
 
@@ -114,13 +115,15 @@ export let sub = (x: Int64, y: Int64) => {
  * @param y: The second operand
  * @returns The product of the two operands
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `*`
  */
 @unsafe
-export let mul = (x: Int64, y: Int64) => {
+provide let (*) = (x: Int64, y: Int64) => {
+  use WasmI64.{ (*) }
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt64(WasmI64.mul(xv, yv))
+  let ptr = newInt64(xv * yv)
   WasmI32.toGrain(ptr): Int64
 }
 
@@ -131,30 +134,15 @@ export let mul = (x: Int64, y: Int64) => {
  * @param y: The second operand
  * @returns The quotient of its operands
  *
- * @since v0.2.0
- */
-@unsafe
-export let div = (x: Int64, y: Int64) => {
-  let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt64(WasmI64.divS(xv, yv))
-  WasmI32.toGrain(ptr): Int64
-}
-
-/**
- * Computes the quotient of its operands using unsigned division.
- *
- * @param x: The first operand
- * @param y: The second operand
- * @returns The quotient of its operands
- *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `div`
  */
 @unsafe
-export let divU = (x: Int64, y: Int64) => {
+provide let (/) = (x: Int64, y: Int64) => {
+  use WasmI64.{ (/) }
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt64(WasmI64.divU(xv, yv))
+  let ptr = newInt64(xv / yv)
   WasmI32.toGrain(ptr): Int64
 }
 
@@ -168,34 +156,18 @@ export let divU = (x: Int64, y: Int64) => {
  * @since v0.2.0
  */
 @unsafe
-export let rem = (x: Int64, y: Int64) => {
+provide let rem = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
   let ptr = newInt64(WasmI64.remS(xv, yv))
   WasmI32.toGrain(ptr): Int64
 }
 
-/**
- * Computes the remainder of the division of its operands using unsigned division.
- *
- * @param x: The first operand
- * @param y: The second operand
- * @returns The remainder of its operands
- *
- * @since v0.2.0
- */
-@unsafe
-export let remU = (x: Int64, y: Int64) => {
-  let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt64(WasmI64.remU(xv, yv))
-  WasmI32.toGrain(ptr): Int64
-}
-
 @unsafe
 let abs = n => {
-  let mask = WasmI64.shrS(n, 63N)
-  WasmI64.sub(WasmI64.xor(n, mask), mask)
+  use WasmI64.{ (-) }
+  let mask = n >> 63N
+  (n ^ mask) - mask
 }
 
 /**
@@ -208,10 +180,12 @@ let abs = n => {
  *
  * @throws ModuloByZero: When `y` is zero
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `mod`
  */
 @unsafe
-export let mod = (x: Int64, y: Int64) => {
+provide let (%) = (x: Int64, y: Int64) => {
+  use WasmI64.{ (-) }
   let xval = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yval = WasmI64.load(WasmI32.fromGrain(y), 8n)
 
@@ -219,26 +193,18 @@ export let mod = (x: Int64, y: Int64) => {
     throw Exception.ModuloByZero
   }
 
-  let ptr = if (WasmI64.ltS(WasmI64.xor(xval, yval), 0N)) {
+  let ptr = if ((xval ^ yval) < 0N) {
     let xabs = abs(xval)
     let yabs = abs(yval)
     let mval = WasmI64.remS(xabs, yabs)
-    let mres = WasmI64.sub(yabs, mval)
-    newInt64(
-      if (WasmI64.ne(mval, 0N)) (
-        if (WasmI64.ltS(yval, 0N)) WasmI64.sub(0N, mres) else mres
-      ) else 0N
-    )
+    let mres = yabs - mval
+    newInt64(if (mval != 0N) (if (yval < 0N) 0N - mres else mres) else 0N)
   } else {
     newInt64(WasmI64.remS(xval, yval))
   }
   WasmI32.toGrain(ptr): Int64
 }
 
-/**
- * @section Bitwise operations: Functions for operating on bits of Int64 values.
- */
-
 /**
  * Rotates the bits of the value left by the given number of bits.
  *
@@ -249,7 +215,7 @@ export let mod = (x: Int64, y: Int64) => {
  * @since v0.4.0
  */
 @unsafe
-export let rotl = (value: Int64, amount: Int64) => {
+provide let rotl = (value: Int64, amount: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(value), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(amount), 8n)
   let ptr = newInt64(WasmI64.rotl(xv, yv))
@@ -266,7 +232,7 @@ export let rotl = (value: Int64, amount: Int64) => {
  * @since v0.4.0
  */
 @unsafe
-export let rotr = (value: Int64, amount: Int64) => {
+provide let rotr = (value: Int64, amount: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(value), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(amount), 8n)
   let ptr = newInt64(WasmI64.rotr(xv, yv))
@@ -280,13 +246,14 @@ export let rotr = (value: Int64, amount: Int64) => {
  * @param amount: The number of bits to shift by
  * @returns The shifted value
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `shl`
  */
 @unsafe
-export let shl = (value: Int64, amount: Int64) => {
+provide let (<<) = (value: Int64, amount: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(value), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(amount), 8n)
-  let ptr = newInt64(WasmI64.shl(xv, yv))
+  let ptr = newInt64(xv << yv)
   WasmI32.toGrain(ptr): Int64
 }
 
@@ -297,37 +264,17 @@ export let shl = (value: Int64, amount: Int64) => {
  * @param amount: The amount to shift by
  * @returns The shifted value
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `shr`
  */
 @unsafe
-export let shr = (value: Int64, amount: Int64) => {
+provide let (>>) = (value: Int64, amount: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(value), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(amount), 8n)
-  let ptr = newInt64(WasmI64.shrS(xv, yv))
+  let ptr = newInt64(xv >> yv)
   WasmI32.toGrain(ptr): Int64
 }
 
-/**
- * Shifts the bits of the value right by the given number of bits.
- *
- * @param value: The value to shift
- * @param amount: The amount to shift by
- * @returns The shifted value
- *
- * @since v0.2.0
- */
-@unsafe
-export let shrU = (value: Int64, amount: Int64) => {
-  let xv = WasmI64.load(WasmI32.fromGrain(value), 8n)
-  let yv = WasmI64.load(WasmI32.fromGrain(amount), 8n)
-  let ptr = newInt64(WasmI64.shrU(xv, yv))
-  WasmI32.toGrain(ptr): Int64
-}
-
-/**
- * @section Comparisons: Functions for comparing Int64 values.
- */
-
 /**
  * Checks if the first value is equal to the second value.
  *
@@ -335,13 +282,14 @@ export let shrU = (value: Int64, amount: Int64) => {
  * @param y: The second value
  * @returns `true` if the first value is equal to the second value or `false` otherwise
  *
- * @since v0.4.0
+ * @since v0.6.0
+ * @history v0.4.0: Originally named `eq`
  */
 @unsafe
-export let eq = (x: Int64, y: Int64) => {
+provide let (==) = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  WasmI64.eq(xv, yv)
+  xv == yv
 }
 
 /**
@@ -351,13 +299,14 @@ export let eq = (x: Int64, y: Int64) => {
  * @param y: The second value
  * @returns `true` if the first value is not equal to the second value or `false` otherwise
  *
- * @since v0.4.0
+ * @since v0.6.0
+ * @history v0.4.0: Originally named `ne`
  */
 @unsafe
-export let ne = (x: Int64, y: Int64) => {
+provide let (!=) = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  WasmI64.ne(xv, yv)
+  xv != yv
 }
 
 /**
@@ -369,7 +318,7 @@ export let ne = (x: Int64, y: Int64) => {
  * @since v0.4.0
  */
 @unsafe
-export let eqz = (value: Int64) => {
+provide let eqz = (value: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(value), 8n)
   WasmI64.eqz(xv)
 }
@@ -381,29 +330,14 @@ export let eqz = (value: Int64) => {
  * @param y: The second value
  * @returns `true` if the first value is less than the second value or `false` otherwise
  *
- * @since v0.2.0
- */
-@unsafe
-export let lt = (x: Int64, y: Int64) => {
-  let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  WasmI64.ltS(xv, yv)
-}
-
-/**
- * Checks if the first unsigned value is less than the second unsigned value.
- *
- * @param x: The first value
- * @param y: The second value
- * @returns `true` if the first value is less than the second value or `false` otherwise
- *
- * @since v0.5.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `lt`
  */
 @unsafe
-export let ltU = (x: Int64, y: Int64) => {
+provide let (<) = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  WasmI64.ltU(xv, yv)
+  xv < yv
 }
 
 /**
@@ -413,29 +347,14 @@ export let ltU = (x: Int64, y: Int64) => {
  * @param y: The second value
  * @returns `true` if the first value is greater than the second value or `false` otherwise
  *
- * @since v0.2.0
- */
-@unsafe
-export let gt = (x: Int64, y: Int64) => {
-  let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  WasmI64.gtS(xv, yv)
-}
-
-/**
- * Checks if the first unsigned value is greater than the second unsigned value.
- *
- * @param x: The first value
- * @param y: The second value
- * @returns `true` if the first value is greater than the second value or `false` otherwise
- *
- * @since v0.5.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `gt`
  */
 @unsafe
-export let gtU = (x: Int64, y: Int64) => {
+provide let (>) = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  WasmI64.gtU(xv, yv)
+  xv > yv
 }
 
 /**
@@ -445,29 +364,14 @@ export let gtU = (x: Int64, y: Int64) => {
  * @param y: The second value
  * @returns `true` if the first value is less than or equal to the second value or `false` otherwise
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `lte`
  */
 @unsafe
-export let lte = (x: Int64, y: Int64) => {
+provide let (<=) = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  WasmI64.leS(xv, yv)
-}
-
-/**
- * Checks if the first unsigned value is less than or equal to the second unsigned value.
- *
- * @param x: The first value
- * @param y: The second value
- * @returns `true` if the first value is less than or equal to the second value or `false` otherwise
- *
- * @since v0.5.0
- */
-@unsafe
-export let lteU = (x: Int64, y: Int64) => {
-  let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  WasmI64.leU(xv, yv)
+  xv <= yv
 }
 
 /**
@@ -477,35 +381,16 @@ export let lteU = (x: Int64, y: Int64) => {
  * @param y: The second value
  * @returns `true` if the first value is greater than or equal to the second value or `false` otherwise
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `gte`
  */
 @unsafe
-export let gte = (x: Int64, y: Int64) => {
+provide let (>=) = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  WasmI64.geS(xv, yv)
+  xv >= yv
 }
 
-/**
- * Checks if the first unsigned value is greater than or equal to the second unsigned value.
- *
- * @param x: The first value
- * @param y: The second value
- * @returns `true` if the first value is greater than or equal to the second value or `false` otherwise
- *
- * @since v0.5.0
- */
-@unsafe
-export let gteU = (x: Int64, y: Int64) => {
-  let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  WasmI64.geU(xv, yv)
-}
-
-/**
- * @section Bitwise logic: Boolean operations on the bits of Int64 values.
- */
-
 /**
  * Computes the bitwise NOT of the given value.
  *
@@ -515,9 +400,9 @@ export let gteU = (x: Int64, y: Int64) => {
  * @since v0.2.0
  */
 @unsafe
-export let lnot = (value: Int64) => {
+provide let lnot = (value: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(value), 8n)
-  let ptr = newInt64(WasmI64.xor(xv, 0xffffffffffffffffN))
+  let ptr = newInt64(xv ^ 0xffffffffffffffffN)
   WasmI32.toGrain(ptr): Int64
 }
 
@@ -528,13 +413,14 @@ export let lnot = (value: Int64) => {
  * @param y: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of both operands are `1`
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `land`
  */
 @unsafe
-export let land = (x: Int64, y: Int64) => {
+provide let (&) = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt64(WasmI64.and(xv, yv))
+  let ptr = newInt64(xv & yv)
   WasmI32.toGrain(ptr): Int64
 }
 
@@ -545,13 +431,14 @@ export let land = (x: Int64, y: Int64) => {
  * @param y: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of either or both operands are `1`
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `lor`
  */
 @unsafe
-export let lor = (x: Int64, y: Int64) => {
+provide let (|) = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt64(WasmI64.or(xv, yv))
+  let ptr = newInt64(xv | yv)
   WasmI32.toGrain(ptr): Int64
 }
 
@@ -562,13 +449,14 @@ export let lor = (x: Int64, y: Int64) => {
  * @param y: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of either but not both operands are `1`
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `lxor`
  */
 @unsafe
-export let lxor = (x: Int64, y: Int64) => {
+provide let (^) = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt64(WasmI64.xor(xv, yv))
+  let ptr = newInt64(xv ^ yv)
   WasmI32.toGrain(ptr): Int64
 }
 
@@ -581,7 +469,7 @@ export let lxor = (x: Int64, y: Int64) => {
  * @since v0.4.0
  */
 @unsafe
-export let clz = (value: Int64) => {
+provide let clz = (value: Int64) => {
   let nv = WasmI64.load(WasmI32.fromGrain(value), 8n)
   let ptr = newInt64(WasmI64.clz(nv))
   WasmI32.toGrain(ptr): Int64
@@ -596,7 +484,7 @@ export let clz = (value: Int64) => {
  * @since v0.4.0
  */
 @unsafe
-export let ctz = (value: Int64) => {
+provide let ctz = (value: Int64) => {
   let nv = WasmI64.load(WasmI32.fromGrain(value), 8n)
   let ptr = newInt64(WasmI64.ctz(nv))
   WasmI32.toGrain(ptr): Int64
@@ -611,8 +499,37 @@ export let ctz = (value: Int64) => {
  * @since v0.4.0
  */
 @unsafe
-export let popcnt = (value: Int64) => {
+provide let popcnt = (value: Int64) => {
   let nv = WasmI64.load(WasmI32.fromGrain(value), 8n)
   let ptr = newInt64(WasmI64.popcnt(nv))
   WasmI32.toGrain(ptr): Int64
 }
+
+// Exponentiation by squaring https://en.wikipedia.org/wiki/Exponentiation_by_squaring special path for int^int
+let rec expBySquaring = (y, x, n) => {
+  if (n == 0L) {
+    1L
+  } else if (n == 1L) {
+    x * y
+  } else if (n % 2L == 0L) {
+    expBySquaring(y, x * x, n / 2L)
+  } else {
+    expBySquaring(x * y, x * x, (n - 1L) / 2L)
+  }
+}
+
+/**
+ * Computes the exponentiation of the given base and power.
+ *
+ * @param base: The base number
+ * @param power: The exponent number
+ * @returns The base raised to the given power
+ *
+ * @since v0.6.0
+ */
+provide let (**) = (base, power) => {
+  if (power < 0L)
+    return expBySquaring(1L, 1L / base, power * -1L)
+  else
+    return expBySquaring(1L, base, power)
+}