@grain/stdlib 0.5.13 → 0.6.0

package/bigint.gr

@@ -1,45 +1,28 @@
 /**
- * @module BigInt: Utilities for working with the BigInt type.
- * @example import BigInt from "bigint"
+ * Utilities for working with the BigInt type.
+ *
+ * @example from "bigint" include Bigint
+ *
+ * @example 9223372036854775809t
+ * @example 0t
+ * @example -9223372036854775809t
  *
  * @since v0.5.0
  */
-import WasmI32 from "runtime/unsafe/wasmi32"
-import Memory from "runtime/unsafe/memory"
-import BI from "runtime/bigint"
-import DS from "runtime/dataStructures"
+module BigInt
+
+from "runtime/unsafe/wasmi32" include WasmI32
+from "runtime/unsafe/memory" include Memory
+from "runtime/bigint" include Bigint as BI
+from "runtime/dataStructures" include DataStructures as DS
 
-import {
+from "runtime/numbers" include Numbers
+use Numbers.{
   coerceNumberToBigInt as fromNumber,
   coerceBigIntToNumber as toNumber,
-} from "runtime/numbers"
-
-/**
- * @section Conversions: Functions for converting between Numbers and the BigInt type.
- */
-
-/**
- * Converts a Number to a BigInt.
- *
- * @param number: The value to convert
- * @returns The Number represented as a BigInt
- *
- * @since v0.5.0
- */
-export fromNumber
-/**
- * Converts a BigInt to a Number.
- *
- * @param num: The value to convert
- * @returns The BigInt represented as a Number
- *
- * @since v0.5.0
- */
-export toNumber
+}
 
-/**
- * @section Operations: Mathematical operations for BigInt values.
- */
+provide { fromNumber, toNumber }
 
 /**
  * Increments the value by one.
@@ -47,10 +30,13 @@ export toNumber
  * @param num: The value to increment
  * @returns The incremented value
  *
+ * @example BigInt.incr(1t) == 2t
+ * @example BigInt.incr(-2t) == -1t
+ *
  * @since v0.5.0
  */
 @unsafe
-export let incr = (num: BigInt) => {
+provide let incr = (num: BigInt) => {
   WasmI32.toGrain(BI.incr(WasmI32.fromGrain(num))): BigInt
 }
 
@@ -60,10 +46,13 @@ export let incr = (num: BigInt) => {
  * @param num: The value to decrement
  * @returns The decremented value
  *
+ * @example BigInt.decr(2t) == 1t
+ * @example BigInt.decr(-2t) == -3t
+ *
  * @since v0.5.0
  */
 @unsafe
-export let decr = (num: BigInt) => {
+provide let decr = (num: BigInt) => {
   WasmI32.toGrain(BI.decr(WasmI32.fromGrain(num))): BigInt
 }
 
@@ -73,10 +62,13 @@ export let decr = (num: BigInt) => {
  * @param num: The operand
  * @returns The negated operand
  *
+ * @example BigInt.neg(1t) == -1t
+ * @example BigInt.neg(-1t) == 1t
+ *
  * @since v0.5.0
  */
 @unsafe
-export let neg = (num: BigInt) => {
+provide let neg = (num: BigInt) => {
   WasmI32.toGrain(BI.negate(WasmI32.fromGrain(num))): BigInt
 }
 
@@ -86,10 +78,13 @@ export let neg = (num: BigInt) => {
  * @param num: The operand
  * @returns The operand's absolute value
  *
+ * @example BigInt.abs(1t) == 1t
+ * @example BigInt.abs(-1t) == 1t
+ *
  * @since v0.5.0
  */
 @unsafe
-export let abs = (num: BigInt) => {
+provide let abs = (num: BigInt) => {
   WasmI32.toGrain(BI.abs(WasmI32.fromGrain(num))): BigInt
 }
 
@@ -100,13 +95,17 @@ export let abs = (num: BigInt) => {
  * @param num2: The second operand
  * @returns The sum of the two operands
  *
- * @since v0.5.0
+ * @example
+ * use BigInt.{ (+) }
+ * assert 1t + 1t == 2t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `add`
  */
 @unsafe
-export let add = (num1: BigInt, num2: BigInt) => {
-  WasmI32.toGrain(
-    BI.add(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
-  ): BigInt
+provide let (+) = (num1: BigInt, num2: BigInt) => {
+  WasmI32.toGrain(BI.add(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))):
+    BigInt
 }
 
 /**
@@ -116,13 +115,17 @@ export let add = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns The difference of the two operands
  *
- * @since v0.5.0
+ * @example
+ * use BigInt.{ (-) }
+ * assert 3t - 1t == 2t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `sub`
  */
 @unsafe
-export let sub = (num1: BigInt, num2: BigInt) => {
-  WasmI32.toGrain(
-    BI.sub(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
-  ): BigInt
+provide let (-) = (num1: BigInt, num2: BigInt) => {
+  WasmI32.toGrain(BI.sub(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))):
+    BigInt
 }
 
 /**
@@ -132,13 +135,17 @@ export let sub = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns The product of the two operands
  *
- * @since v0.5.0
+ * @example
+ * use BigInt.{ (*) }
+ * assert 3t * 3t == 9t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `mul`
  */
 @unsafe
-export let mul = (num1: BigInt, num2: BigInt) => {
-  WasmI32.toGrain(
-    BI.mul(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
-  ): BigInt
+provide let (*) = (num1: BigInt, num2: BigInt) => {
+  WasmI32.toGrain(BI.mul(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))):
+    BigInt
 }
 
 // For further reading on Truncated vs. Floored division: https://en.wikipedia.org/wiki/Modulo_operation
@@ -151,13 +158,17 @@ export let mul = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns The quotient of its operands
  *
- * @since v0.5.0
+ * @example
+ * use BigInt.{ (/) }
+ * assert 9t / 3t == 3t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `div`
  */
 @unsafe
-export let div = (num1: BigInt, num2: BigInt) => {
-  WasmI32.toGrain(
-    BI.quot(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
-  ): BigInt
+provide let (/) = (num1: BigInt, num2: BigInt) => {
+  WasmI32.toGrain(BI.quot(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))):
+    BigInt
 }
 
 /**
@@ -168,13 +179,14 @@ export let div = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns The remainder of its operands
  *
+ * @example BigInt.rem(3t, 2t) == 1t
+ *
  * @since v0.5.0
  */
 @unsafe
-export let rem = (num1: BigInt, num2: BigInt) => {
-  WasmI32.toGrain(
-    BI.rem(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
-  ): BigInt
+provide let rem = (num1: BigInt, num2: BigInt) => {
+  WasmI32.toGrain(BI.rem(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))):
+    BigInt
 }
 
 /**
@@ -184,10 +196,12 @@ export let rem = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns The quotient and remainder of its operands
  *
+ * @example BigInt.quotRem(7t, 2t) == (3t, 1t))
+ *
  * @since v0.5.0
  */
 @unsafe
-export let quotRem = (num1: BigInt, num2: BigInt) => {
+provide let quotRem = (num1: BigInt, num2: BigInt) => {
   let dest = Memory.malloc(8n)
   BI.quotRem(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2), dest)
   let q = WasmI32.toGrain(WasmI32.load(dest, 0n)): BigInt
@@ -203,19 +217,16 @@ export let quotRem = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second operand
  * @returns The greatest common divisor of its operands
  *
+ * @example BigInt.gcd(36t, 24t) == 12t
+ *
  * @since v0.5.0
  */
 @unsafe
-export let gcd = (num1: BigInt, num2: BigInt) => {
-  WasmI32.toGrain(
-    BI.gcd(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
-  ): BigInt
+provide let gcd = (num1: BigInt, num2: BigInt) => {
+  WasmI32.toGrain(BI.gcd(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))):
+    BigInt
 }
 
-/**
- * @section Bitwise operations: Functions for operating on bits of BigInt values.
- */
-
 /**
  * Shifts the bits of the value left by the given number of bits.
  *
@@ -223,12 +234,17 @@ export let gcd = (num1: BigInt, num2: BigInt) => {
  * @param places: The number of bits to shift by
  * @returns The shifted value
  *
- * @since v0.5.0
+ * @example
+ * use BigInt.{ (<<) }
+ * assert (10t << 2l) == 40t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `shl`
  */
 @unsafe
-export let shl = (num: BigInt, places: Int32) => {
+provide let (<<) = (num: BigInt, places: Int32) => {
   let num = WasmI32.fromGrain(num)
-  let places = WasmI32.load(WasmI32.fromGrain(places), 8n)
+  let places = WasmI32.load(WasmI32.fromGrain(places), 4n)
   WasmI32.toGrain(BI.shl(num, places)): BigInt
 }
 
@@ -239,31 +255,36 @@ export let shl = (num: BigInt, places: Int32) => {
  * @param places: The amount to shift by
  * @returns The shifted value
  *
- * @since v0.5.0
+ * @example
+ * use BigInt.{ (>>) }
+ * assert (9999t >> 2l) == 2499t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `shr`
  */
 @unsafe
-export let shr = (num: BigInt, places: Int32) => {
+provide let (>>) = (num: BigInt, places: Int32) => {
   let num = WasmI32.fromGrain(num)
-  let places = WasmI32.load(WasmI32.fromGrain(places), 8n)
+  let places = WasmI32.load(WasmI32.fromGrain(places), 4n)
   WasmI32.toGrain(BI.shrS(num, places)): BigInt
 }
 
-/**
- * @section Comparisons: Functions for comparing BigInt values.
- */
-
 /**
  * Checks if the given value is equal to zero.
  *
  * @param num: The value to inspect
  * @returns `true` if the first value is equal to zero or `false` otherwise
  *
+ * @example assert BigInt.eqz(0t) == true
+ * @example assert BigInt.eqz(1t) == false
+ *
  * @since v0.5.0
  */
 @unsafe
-export let eqz = (num: BigInt) => {
-  let num = WasmI32.fromGrain(num)
-  BI.eqz(num)
+provide let eqz = (num: BigInt) => {
+  let result = BI.eqz(WasmI32.fromGrain(num))
+  ignore(num)
+  result
 }
 
 /**
@@ -273,13 +294,22 @@ export let eqz = (num: BigInt) => {
  * @param num2: The second value
  * @returns `true` if the first value is equal to the second value or `false` otherwise
  *
- * @since v0.5.0
+ * @example
+ * use BigInt.{ (==) }
+ * assert 1t == 1t
+ * @example
+ * use BigInt.{ (==) }
+ * assert -10t == -10t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `eq`
  */
 @unsafe
-export let eq = (num1: BigInt, num2: BigInt) => {
-  let num1 = WasmI32.fromGrain(num1)
-  let num2 = WasmI32.fromGrain(num2)
-  BI.eq(num1, num2)
+provide let (==) = (num1: BigInt, num2: BigInt) => {
+  let result = BI.eq(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
+  ignore(num1)
+  ignore(num2)
+  result
 }
 
 /**
@@ -289,13 +319,22 @@ export let eq = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second value
  * @returns `true` if the first value is not equal to the second value or `false` otherwise
  *
- * @since v0.5.0
+ * @example
+ * use BigInt.{ (!=) }
+ * assert 1t != 2t
+ * @example
+ * use BigInt.{ (!=) }
+ * assert -10t != -20t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `ne`
  */
 @unsafe
-export let ne = (num1: BigInt, num2: BigInt) => {
-  let num1 = WasmI32.fromGrain(num1)
-  let num2 = WasmI32.fromGrain(num2)
-  BI.ne(num1, num2)
+provide let (!=) = (num1: BigInt, num2: BigInt) => {
+  let result = BI.ne(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
+  ignore(num1)
+  ignore(num2)
+  result
 }
 
 /**
@@ -305,13 +344,22 @@ export let ne = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second value
  * @returns `true` if the first value is less than the second value or `false` otherwise
  *
- * @since v0.5.0
+ * @example
+ * use BigInt.{ (<) }
+ * assert 1t < 2t
+ * @example
+ * use BigInt.{ (<) }
+ * assert -10t < 0t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `lt`
  */
 @unsafe
-export let lt = (num1: BigInt, num2: BigInt) => {
-  let num1 = WasmI32.fromGrain(num1)
-  let num2 = WasmI32.fromGrain(num2)
-  BI.lt(num1, num2)
+provide let (<) = (num1: BigInt, num2: BigInt) => {
+  let result = BI.lt(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
+  ignore(num1)
+  ignore(num2)
+  result
 }
 
 /**
@@ -321,13 +369,25 @@ export let lt = (num1: BigInt, num2: BigInt) => {
  * @param num2: 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
+ * @example
+ * use BigInt.{ (<=) }
+ * assert 1t <= 1t
+ * @example
+ * use BigInt.{ (<=) }
+ * assert -10t <= 0t
+ * @example
+ * use BigInt.{ (<=) }
+ * assert 2t <= 3t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `lte`
  */
 @unsafe
-export let lte = (num1: BigInt, num2: BigInt) => {
-  let num1 = WasmI32.fromGrain(num1)
-  let num2 = WasmI32.fromGrain(num2)
-  BI.lte(num1, num2)
+provide let (<=) = (num1: BigInt, num2: BigInt) => {
+  let result = BI.lte(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
+  ignore(num1)
+  ignore(num2)
+  result
 }
 
 /**
@@ -337,13 +397,22 @@ export let lte = (num1: BigInt, num2: BigInt) => {
  * @param num2: The second value
  * @returns `true` if the first value is greater than the second value or `false` otherwise
  *
- * @since v0.5.0
+ * @example
+ * use BigInt.{ (>) }
+ * assert 2t > 1t
+ * @example
+ * use BigInt.{ (>) }
+ * assert 0t > -10t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `gt`
  */
 @unsafe
-export let gt = (num1: BigInt, num2: BigInt) => {
-  let num1 = WasmI32.fromGrain(num1)
-  let num2 = WasmI32.fromGrain(num2)
-  BI.gt(num1, num2)
+provide let (>) = (num1: BigInt, num2: BigInt) => {
+  let result = BI.gt(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
+  ignore(num1)
+  ignore(num2)
+  result
 }
 
 /**
@@ -353,29 +422,39 @@ export let gt = (num1: BigInt, num2: BigInt) => {
  * @param num2: 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
+ * @example
+ * use BigInt.{ (>=) }
+ * assert 1t >= 1t
+ * @example
+ * use BigInt.{ (>=) }
+ * assert 0t >= -10t
+ * @example
+ * use BigInt.{ (>=) }
+ * assert 3t >= 2t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `gte`
  */
 @unsafe
-export let gte = (num1: BigInt, num2: BigInt) => {
-  let num1 = WasmI32.fromGrain(num1)
-  let num2 = WasmI32.fromGrain(num2)
-  BI.gte(num1, num2)
+provide let (>=) = (num1: BigInt, num2: BigInt) => {
+  let result = BI.gte(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
+  ignore(num1)
+  ignore(num2)
+  result
 }
 
-/**
- * @section Bitwise logic: Boolean operations on the bits of BigInt values.
- */
-
 /**
  * Computes the bitwise NOT of the given value.
  *
  * @param num: The given value
  * @returns Containing the inverted bits of the given value
  *
+ * @example BigInt.lnot(91234t) == -91235t
+ *
  * @since v0.5.0
  */
 @unsafe
-export let lnot = (num: BigInt) => {
+provide let lnot = (num: BigInt) => {
   WasmI32.toGrain(BI.bitwiseNot(WasmI32.fromGrain(num))): BigInt
 }
 
@@ -386,10 +465,15 @@ export let lnot = (num: BigInt) => {
  * @param num2: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of both operands are `1`
  *
- * @since v0.5.0
+ * @example
+ * use BigInt.{ (&) }
+ * assert (4t & 3t) == 0t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `land`
  */
 @unsafe
-export let land = (num1: BigInt, num2: BigInt) => {
+provide let (&) = (num1: BigInt, num2: BigInt) => {
   WasmI32.toGrain(
     BI.bitwiseAnd(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
   ): BigInt
@@ -402,10 +486,15 @@ export let land = (num1: BigInt, num2: BigInt) => {
  * @param num2: 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.5.0
+ * @example
+ * use BigInt.{ (|) }
+ * assert (5t | 3t) == 7t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `lor`
  */
 @unsafe
-export let lor = (num1: BigInt, num2: BigInt) => {
+provide let (|) = (num1: BigInt, num2: BigInt) => {
   WasmI32.toGrain(
     BI.bitwiseOr(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
   ): BigInt
@@ -418,10 +507,15 @@ export let lor = (num1: BigInt, num2: BigInt) => {
  * @param num2: 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.5.0
+ * @example
+ * use BigInt.{ (^) }
+ * assert (5t ^ 3t) == 6t
+ *
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `lxor`
  */
 @unsafe
-export let lxor = (num1: BigInt, num2: BigInt) => {
+provide let (^) = (num1: BigInt, num2: BigInt) => {
   WasmI32.toGrain(
     BI.bitwiseXor(WasmI32.fromGrain(num1), WasmI32.fromGrain(num2))
   ): BigInt
@@ -434,13 +528,14 @@ export let lxor = (num1: BigInt, num2: BigInt) => {
  * @param num: The value to inspect
  * @returns The amount of leading zeros
  *
+ * @example BigInt.clz(5t) == 2147483647t
+ *
  * @since v0.5.0
  */
 @unsafe
-export let clz = (num: BigInt) => {
-  WasmI32.toGrain(
-    DS.newInt32(BI.countLeadingZeros(WasmI32.fromGrain(num)))
-  ): Int32
+provide let clz = (num: BigInt) => {
+  WasmI32.toGrain(DS.newInt32(BI.countLeadingZeros(WasmI32.fromGrain(num)))):
+    Int32
 }
 
 /**
@@ -449,13 +544,14 @@ export let clz = (num: BigInt) => {
  * @param num: The value to inspect
  * @returns The amount of trailing zeros
  *
+ * @example BigInt.ctz(14t) == 1t
+ *
  * @since v0.5.0
  */
 @unsafe
-export let ctz = (num: BigInt) => {
-  WasmI32.toGrain(
-    DS.newInt64(BI.countTrailingZeros(WasmI32.fromGrain(num)))
-  ): Int64
+provide let ctz = (num: BigInt) => {
+  WasmI32.toGrain(DS.newInt64(BI.countTrailingZeros(WasmI32.fromGrain(num)))):
+    Int64
 }
 
 /**
@@ -465,10 +561,12 @@ export let ctz = (num: BigInt) => {
  * @param num: The value to inspect
  * @returns The amount of 1-bits in its operand
  *
+ * @example BigInt.popcnt(14t) == 1t
+ *
  * @since v0.5.0
  */
 @unsafe
-export let popcnt = (num: BigInt) => {
+provide let popcnt = (num: BigInt) => {
   let flagDest = Memory.malloc(4n)
   WasmI32.store(flagDest, 0n, 0n)
   let res = BI.popcnt(WasmI32.fromGrain(num), flagDest)
@@ -479,19 +577,20 @@ export let popcnt = (num: BigInt) => {
   }
 }
 
-/**
- * @section Other: Other functions on BigInts.
- */
-
 /**
  * Converts the given operand to a string.
  *
  * @param num: The operand
  * @returns The operand, as a string
  *
+ * @example BigInt.toString(1t) == "1"
+ * @example BigInt.toString(-1t) == "-1"
+ *
  * @since v0.5.0
  */
 @unsafe
-export let toString = (num: BigInt) => {
-  BI.bigIntToString10(WasmI32.fromGrain(num))
+provide let toString = (num: BigInt) => {
+  let string = BI.bigIntToString10(WasmI32.fromGrain(num))
+  ignore(num)
+  string
 }