@grain/stdlib 0.4.4 → 0.5.0

package/int32.gr

@@ -1,131 +1,214 @@
+/**
+ * @module Int32: Utilities for working with the Int32 type.
+ * @example import Int32 from "int32"
+ * 
+ * @since v0.2.0
+ */
 import WasmI32 from "runtime/unsafe/wasmi32"
-import Memory from "runtime/unsafe/memory"
 import Exception from "runtime/exception"
 
-import {
-  newInt32
-} from "runtime/dataStructures"
+import { newInt32 } from "runtime/dataStructures"
 
 import {
   coerceNumberToInt32 as fromNumber,
-  coerceInt32ToNumber as toNumber
+  coerceInt32ToNumber as toNumber,
 } from "runtime/numbers"
 
+/**
+ * @section Conversions: Functions for converting between Numbers and the Int32 type.
+ */
+
+/**
+ * Converts a Number to an Int32.
+ *
+ * @param number: The value to convert
+ * @returns The Number represented as an Int32
+ * 
+ * @since v0.2.0
+ */
 export fromNumber
+
+/**
+ * Converts an Int32 to a Number.
+ *
+ * @param value: The value to convert
+ * @returns The Int32 represented as a Number
+ * 
+ * @since v0.2.0
+ */
 export toNumber
 
-@disableGC
-export let rec incr = (n: Int32) => {
-  let n = WasmI32.fromGrain(n)
-  let ptr = newInt32(WasmI32.add(WasmI32.load(n, 8n), 1n))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(n)
-  Memory.decRef(WasmI32.fromGrain(incr))
-  ret
+/**
+ * @section Operations: Mathematical operations for Int32 values.
+ */
+
+/**
+ * Increments the value by one.
+ *
+ * @param value: The value to increment
+ * @returns The incremented value
+ * 
+ * @since v0.2.0
+ */
+@unsafe
+export let incr = (value: Int32) => {
+  let value = WasmI32.fromGrain(value)
+  let ptr = newInt32(WasmI32.add(WasmI32.load(value, 8n), 1n))
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec decr = (n: Int32) => {
-  let n = WasmI32.fromGrain(n)
-  let ptr = newInt32(WasmI32.sub(WasmI32.load(n, 8n), 1n))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(n)
-  Memory.decRef(WasmI32.fromGrain(decr))
-  ret
+/**
+ * Decrements the value by one.
+ *
+ * @param value: The value to decrement
+ * @returns The decremented value
+ * 
+ * @since v0.2.0
+ */
+@unsafe
+export let decr = (value: Int32) => {
+  let value = WasmI32.fromGrain(value)
+  let ptr = newInt32(WasmI32.sub(WasmI32.load(value, 8n), 1n))
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec add = (x: Int32, y: Int32) => {
+/**
+ * Computes the sum of its operands.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The sum of the two operands
+ * 
+ * @since v0.2.0
+ */
+@unsafe
+export let add = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   let ptr = newInt32(WasmI32.add(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(add))
-  ret
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec sub = (x: Int32, y: Int32) => {
+/**
+ * Computes the difference of its operands.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The difference of the two operands
+ * 
+ * @since v0.2.0
+ */
+@unsafe
+export let sub = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   let ptr = newInt32(WasmI32.sub(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(sub))
-  ret
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec mul = (x: Int32, y: Int32) => {
+/**
+ * Computes the product of its operands.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The product of the two operands
+ * 
+ * @since v0.2.0
+ */
+@unsafe
+export let mul = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   let ptr = newInt32(WasmI32.mul(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(mul))
-  ret
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec div = (x: Int32, y: Int32) => {
+/**
+ * Computes the quotient of its operands using signed division.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The quotient of its operands
+ * 
+ * @since v0.2.0
+ */
+@unsafe
+export let div = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   let ptr = newInt32(WasmI32.divS(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(div))
-  ret
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec divU = (x: Int32, y: Int32) => {
+/**
+ * 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
+ */
+@unsafe
+export let divU = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   let ptr = newInt32(WasmI32.divU(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(divU))
-  ret
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec rem = (x: Int32, y: Int32) => {
+/**
+ * Computes the remainder of the division of its operands using signed division.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The remainder of its operands
+ * 
+ * @since v0.2.0
+ */
+@unsafe
+export let rem = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   let ptr = newInt32(WasmI32.remS(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(rem))
-  ret
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec remU = (x: Int32, y: Int32) => {
+/**
+ * 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: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   let ptr = newInt32(WasmI32.remU(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(remU))
-  ret
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-let abs = (n) => {
+@unsafe
+let abs = n => {
   let mask = WasmI32.shrS(n, 31n)
   WasmI32.sub(WasmI32.xor(n, mask), mask)
 }
 
-@disableGC
-export let rec mod = (x: Int32, y: Int32) => {
+/**
+ * Computes the remainder of the division of the first operand by the second. 
+ * The result will have the sign of the second operand.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The modulus of its operands
+ * 
+ * @since v0.2.0
+ */
+@unsafe
+export let mod = (x: Int32, y: Int32) => {
   let xval = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yval = WasmI32.load(WasmI32.fromGrain(y), 8n)
 
@@ -138,229 +221,395 @@ export let rec mod = (x: Int32, y: Int32) => {
     let yabs = abs(yval)
     let mval = WasmI32.remS(xabs, yabs)
     let mres = WasmI32.sub(yabs, mval)
-    newInt32(if (WasmI32.ne(mval, 0n)) (if (WasmI32.ltS(yval, 0n)) WasmI32.sub(0n, mres) else mres) else 0n)
+    newInt32(
+      if (WasmI32.ne(mval, 0n)) (
+        if (WasmI32.ltS(yval, 0n)) WasmI32.sub(0n, mres) else mres
+      ) else 0n
+    )
   } else {
     newInt32(WasmI32.remS(xval, yval))
   }
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(mod))
-  ret
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec clz = (n: Int32) => {
-  let nv = WasmI32.load(WasmI32.fromGrain(n), 8n)
-  let ptr = newInt32(WasmI32.clz(nv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(n))
-  Memory.decRef(WasmI32.fromGrain(clz))
-  ret
+/**
+ * @section Bitwise operations: Functions for operating on bits of Int32 values.
+ */
+
+/**
+ * Rotates the bits of the value left by the given number of bits.
+ *
+ * @param value: The value to rotate
+ * @param amount: The number of bits to rotate by
+ * @returns The rotated value
+ * 
+ * @since v0.4.0
+ */
+@unsafe
+export let rotl = (value: Int32, amount: Int32) => {
+  let xv = WasmI32.load(WasmI32.fromGrain(value), 8n)
+  let yv = WasmI32.load(WasmI32.fromGrain(amount), 8n)
+  let ptr = newInt32(WasmI32.rotl(xv, yv))
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec ctz = (n: Int32) => {
-  let nv = WasmI32.load(WasmI32.fromGrain(n), 8n)
-  let ptr = newInt32(WasmI32.ctz(nv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(n))
-  Memory.decRef(WasmI32.fromGrain(ctz))
-  ret
+/**
+ * Rotates the bits of the value right by the given number of bits.
+ *
+ * @param value: The value to rotate
+ * @param amount: The number of bits to rotate by
+ * @returns The rotated value
+ * 
+ * @since v0.4.0
+ */
+@unsafe
+export let rotr = (value: Int32, amount: Int32) => {
+  let xv = WasmI32.load(WasmI32.fromGrain(value), 8n)
+  let yv = WasmI32.load(WasmI32.fromGrain(amount), 8n)
+  let ptr = newInt32(WasmI32.rotr(xv, yv))
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec popcnt = (n: Int32) => {
-  let nv = WasmI32.load(WasmI32.fromGrain(n), 8n)
-  let ptr = newInt32(WasmI32.popcnt(nv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(n))
-  Memory.decRef(WasmI32.fromGrain(popcnt))
-  ret
+/**
+ * Shifts the bits of the value left by the given number of bits.
+ *
+ * @param value: The value to shift
+ * @param amount: The number of bits to shift by
+ * @returns The shifted value
+ * 
+ * @since v0.2.0
+ */
+@unsafe
+export let shl = (value: Int32, amount: Int32) => {
+  let xv = WasmI32.load(WasmI32.fromGrain(value), 8n)
+  let yv = WasmI32.load(WasmI32.fromGrain(amount), 8n)
+  let ptr = newInt32(WasmI32.shl(xv, yv))
+  WasmI32.toGrain(ptr): Int32
+}
+
+/**
+ * Shifts the bits of the value right by the given number of bits, preserving the sign bit.
+ *
+ * @param value: The value to shift
+ * @param amount: The amount to shift by
+ * @returns The shifted value
+ * 
+ * @since v0.2.0
+ */
+@unsafe
+export let shr = (value: Int32, amount: Int32) => {
+  let xv = WasmI32.load(WasmI32.fromGrain(value), 8n)
+  let yv = WasmI32.load(WasmI32.fromGrain(amount), 8n)
+  let ptr = newInt32(WasmI32.shrS(xv, yv))
+  WasmI32.toGrain(ptr): Int32
+}
+
+/**
+ * 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: Int32, amount: Int32) => {
+  let xv = WasmI32.load(WasmI32.fromGrain(value), 8n)
+  let yv = WasmI32.load(WasmI32.fromGrain(amount), 8n)
+  let ptr = newInt32(WasmI32.shrU(xv, yv))
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec rotl = (x: Int32, y: Int32) => {
+/**
+ * @section Comparisons: Functions for comparing Int32 values.
+ */
+
+/**
+ * Checks if the first value is equal to the second value.
+ *
+ * @param x: The first value
+ * @param y: The second value
+ * @returns `true` if the first value is equal to the second value or `false` otherwise
+ * 
+ * @since v0.4.0
+ */
+@unsafe
+export let eq = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt32(WasmI32.rotl(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(rotl))
-  ret
+  WasmI32.eq(xv, yv)
 }
 
-@disableGC
-export let rec rotr = (x: Int32, y: Int32) => {
+/**
+ * Checks if the first value is not equal to the second value.
+ *
+ * @param x: The first value
+ * @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
+ */
+@unsafe
+export let ne = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt32(WasmI32.rotr(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(rotr))
-  ret
+  WasmI32.ne(xv, yv)
 }
 
-// Int32 comparisons
+/**
+ * Checks if the given value is equal to zero.
+ *
+ * @param value: The value to inspect
+ * @returns `true` if the first value is equal to zero or `false` otherwise
+ * 
+ * @since v0.4.0
+ */
+@unsafe
+export let eqz = (value: Int32) => {
+  let xv = WasmI32.load(WasmI32.fromGrain(value), 8n)
+  WasmI32.eqz(xv)
+}
 
-@disableGC
-export let rec eq = (x: Int32, y: Int32) => {
+/**
+ * Checks if the first value is less than the second 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.2.0
+ */
+@unsafe
+export let lt = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
-  let ret = WasmI32.eq(xv, yv)
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(eq))
-  ret
+  WasmI32.ltS(xv, yv)
 }
 
-@disableGC
-export let rec ne = (x: Int32, y: Int32) => {
+/**
+ * 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
+ */
+@unsafe
+export let rec ltU = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
-  let ret = WasmI32.ne(xv, yv)
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(ne))
-  ret
+  WasmI32.ltU(xv, yv)
 }
 
-@disableGC
-export let rec eqz = (n: Int32) => {
-  let xv = WasmI32.load(WasmI32.fromGrain(n), 8n)
-  let ret = WasmI32.eqz(xv)
-  Memory.decRef(WasmI32.fromGrain(n))
-  Memory.decRef(WasmI32.fromGrain(eqz))
-  ret
+/**
+ * Checks if the first value is greater than the second 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.2.0
+ */
+@unsafe
+export let gt = (x: Int32, y: Int32) => {
+  let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
+  let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
+  WasmI32.gtS(xv, yv)
 }
 
-@disableGC
-export let rec lt = (x: Int32, y: Int32) => {
+/**
+ * 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
+ */
+@unsafe
+export let rec gtU = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
-  let ret = WasmI32.ltS(xv, yv)
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(lt))
-  ret
+  WasmI32.gtU(xv, yv)
 }
 
-@disableGC
-export let rec gt = (x: Int32, y: Int32) => {
+/**
+ * Checks if the first value is less than or equal to the second 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.2.0
+ */
+@unsafe
+export let lte = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
-  let ret = WasmI32.gtS(xv, yv)
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(gt))
-  ret
+  WasmI32.leS(xv, yv)
 }
 
-@disableGC
-export let rec lte = (x: Int32, y: Int32) => {
+/**
+ * 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 rec lteU = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
-  let ret = WasmI32.leS(xv, yv)
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(lte))
-  ret
+  WasmI32.leU(xv, yv)
 }
 
-@disableGC
-export let rec gte = (x: Int32, y: Int32) => {
+/**
+ * Checks if the first value is greater than or equal to the second 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.2.0
+ */
+@unsafe
+export let gte = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
-  let ret = WasmI32.geS(xv, yv)
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(gte))
-  ret
+  WasmI32.geS(xv, yv)
 }
 
-// Int32 bit/logical operations
-@disableGC
-export let rec lnot = (x: Int32) => {
+/**
+ * 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 rec gteU = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
-  let ptr = newInt32(WasmI32.xor(xv, 0xffffffffn))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(lnot))
-  ret
+  let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
+  WasmI32.geU(xv, yv)
 }
 
+/**
+ * @section Bitwise logic: Boolean operations on the bits of Int32 values.
+ */
+
+/**
+ * Computes the bitwise NOT of the given value.
+ *
+ * @param value: The given value
+ * @returns Containing the inverted bits of the given value
+ * 
+ * @since v0.2.0
+ */
+@unsafe
+export let lnot = (value: Int32) => {
+  let xv = WasmI32.load(WasmI32.fromGrain(value), 8n)
+  let ptr = newInt32(WasmI32.xor(xv, 0xffffffffn))
+  WasmI32.toGrain(ptr): Int32
+}
 
-@disableGC
-export let rec land = (x: Int32, y: Int32) => {
+/**
+ * Computes the bitwise AND (`&`) on the given operands.
+ *
+ * @param x: The first operand
+ * @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
+ */
+@unsafe
+export let land = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   let ptr = newInt32(WasmI32.and(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(land))
-  ret
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec lor = (x: Int32, y: Int32) => {
+/**
+ * Computes the bitwise OR (`|`) on the given operands.
+ *
+ * @param x: The first operand
+ * @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
+ */
+@unsafe
+export let lor = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   let ptr = newInt32(WasmI32.or(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(lor))
-  ret
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec lxor = (x: Int32, y: Int32) => {
+/**
+ * Computes the bitwise XOR (`^`) on the given operands.
+ *
+ * @param x: The first operand
+ * @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
+ */
+@unsafe
+export let lxor = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   let ptr = newInt32(WasmI32.xor(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(lxor))
-  ret
+  WasmI32.toGrain(ptr): Int32
 }
 
-
-@disableGC
-export let rec shl = (x: Int32, y: Int32) => {
-  let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt32(WasmI32.shl(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(shl))
-  ret
+/**
+ * Counts the number of leading zero bits in the value.
+ *
+ * @param value: The value to inspect
+ * @returns The amount of leading zeros
+ * 
+ * @since v0.4.0
+ */
+@unsafe
+export let clz = (value: Int32) => {
+  let nv = WasmI32.load(WasmI32.fromGrain(value), 8n)
+  let ptr = newInt32(WasmI32.clz(nv))
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec shr = (x: Int32, y: Int32) => {
-  let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt32(WasmI32.shrS(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(shr))
-  ret
+/**
+ * Counts the number of trailing zero bits in the value.
+ *
+ * @param value: The value to inspect
+ * @returns The amount of trailing zeros
+ * 
+ * @since v0.4.0
+ */
+@unsafe
+export let ctz = (value: Int32) => {
+  let nv = WasmI32.load(WasmI32.fromGrain(value), 8n)
+  let ptr = newInt32(WasmI32.ctz(nv))
+  WasmI32.toGrain(ptr): Int32
 }
 
-@disableGC
-export let rec shrU = (x: Int32, y: Int32) => {
-  let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newInt32(WasmI32.shrU(xv, yv))
-  let ret = WasmI32.toGrain(ptr): Int32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(shrU))
-  ret
+/**
+ * Counts the number of bits set to `1` in the value, also known as a population count.
+ *
+ * @param value: The value to inspect
+ * @returns The amount of 1-bits in its operand
+ * 
+ * @since v0.4.0
+ */
+@unsafe
+export let popcnt = (value: Int32) => {
+  let nv = WasmI32.load(WasmI32.fromGrain(value), 8n)
+  let ptr = newInt32(WasmI32.popcnt(nv))
+  WasmI32.toGrain(ptr): Int32
 }