@grain/stdlib 0.5.13 → 0.6.0

package/uint8.gr

@@ -0,0 +1,369 @@
+/**
+ * Utilities for working with the Uint8 type.
+ * @example from "uint8" include Uint8
+ *
+ * @since v0.6.0
+ */
+module Uint8
+
+from "runtime/unsafe/wasmi32" include WasmI32
+use WasmI32.{ (+), (-), (*), (&), (|), (^), (<<), (>>>), (==), (!=) }
+from "runtime/numbers" include Numbers
+use Numbers.{
+  coerceNumberToUint8 as fromNumber,
+  coerceUint8ToNumber as toNumber,
+}
+from "runtime/dataStructures" include DataStructures
+use DataStructures.{ tagUint8, untagUint8 }
+
+@unsafe
+let _TAG_BYTE = 0b11010n
+@unsafe
+let _REMOVE_EXTRA_MASK = 0x0000ffffn
+@unsafe
+let _DATA_MASK = 0xff00n
+@unsafe
+let _UNTAGGED_DATA_MASK = 0xffn
+
+provide { fromNumber, toNumber }
+
+/**
+ * Converts an Int8 to a Uint8.
+ *
+ * @param number: The value to convert
+ * @returns The Int8 represented as a Uint8
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let fromInt8 = (number: Int8) => {
+  let x = WasmI32.fromGrain(number)
+  // Trick: convert from Int8 tag 1010 to Uint8 tag 11010
+  let result = x | 0b10000n
+  WasmI32.toGrain(result & _REMOVE_EXTRA_MASK): Uint8
+}
+
+/**
+ * Increments the value by one.
+ *
+ * @param value: The value to increment
+ * @returns The incremented value
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let incr = (value: Uint8) => {
+  let value = WasmI32.fromGrain(value)
+  // Trick: since the data is at offset 8, can just add 1 << 8 == 0x100
+  let result = value + 0x100n
+  WasmI32.toGrain(result & _REMOVE_EXTRA_MASK): Uint8
+}
+
+/**
+ * Decrements the value by one.
+ *
+ * @param value: The value to decrement
+ * @returns The decremented value
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let decr = (value: Uint8) => {
+  let value = WasmI32.fromGrain(value)
+  // Trick: since the data is at offset 8, can just subtract 1 << 8 == 0x100
+  let result = value - 0x100n
+  WasmI32.toGrain(result & _REMOVE_EXTRA_MASK): Uint8
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (+) = (x: Uint8, y: Uint8) => {
+  // Trick: add the values as-is without shifting right 8; this will cause
+  // the data to be added correctly but the trailing tag bits will be corrupted:
+  // 11010 + 11010 = 110100; xor with 101110 to correct to 11010
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  let val = x + y
+  let tagged = val ^ 0b101110n
+  WasmI32.toGrain(tagged & _REMOVE_EXTRA_MASK): Uint8
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (-) = (x: Uint8, y: Uint8) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  let val = x - y
+  let tagged = val | _TAG_BYTE
+  WasmI32.toGrain(tagged & _REMOVE_EXTRA_MASK): Uint8
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (*) = (x: Uint8, y: Uint8) => {
+  let x = untagUint8(x)
+  let y = untagUint8(y)
+  let val = x * y & _UNTAGGED_DATA_MASK
+  tagUint8(val)
+}
+
+/**
+ * Computes the quotient of its operands.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The quotient of its operands
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let (/) = (x: Uint8, y: Uint8) => {
+  let x = untagUint8(x)
+  let y = untagUint8(y)
+  let val = WasmI32.divU(x, y)
+  tagUint8(val)
+}
+
+/**
+ * Computes the remainder of the division of its operands.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The remainder of its operands
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let rem = (x: Uint8, y: Uint8) => {
+  let x = untagUint8(x)
+  let y = untagUint8(y)
+  let val = WasmI32.remU(x, y)
+  tagUint8(val)
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (<<) = (value: Uint8, amount: Uint8) => {
+  // Trick: do not shift `value` right, just correct tag afterwards
+  let x = WasmI32.fromGrain(value) & _DATA_MASK
+  let y = untagUint8(amount)
+  let val = x << y
+  let tagged = val | _TAG_BYTE
+  WasmI32.toGrain(tagged & _REMOVE_EXTRA_MASK): Uint8
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (>>>) = (value: Uint8, amount: Uint8) => {
+  // Trick: do not shift `value` right, just correct tag afterwards
+  let x = WasmI32.fromGrain(value)
+  let y = untagUint8(amount)
+  let val = x >>> y
+  let tagged = val & _DATA_MASK | _TAG_BYTE
+  WasmI32.toGrain(tagged): Uint8
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (==) = (x: Uint8, y: Uint8) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  x == y
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (!=) = (x: Uint8, y: Uint8) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  x != y
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (<) = (x: Uint8, y: Uint8) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  WasmI32.ltU(x, y)
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (>) = (x: Uint8, y: Uint8) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  WasmI32.gtU(x, y)
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (<=) = (x: Uint8, y: Uint8) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  WasmI32.leU(x, y)
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (>=) = (x: Uint8, y: Uint8) => {
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  WasmI32.geU(x, y)
+}
+
+/**
+ * Computes the bitwise NOT of the given value.
+ *
+ * @param value: The given value
+ * @returns Containing the inverted bits of the given value
+ *
+ * @since v0.6.0
+ */
+@unsafe
+provide let lnot = (value: Uint8) => {
+  let x = WasmI32.fromGrain(value)
+  WasmI32.toGrain(x ^ _DATA_MASK): Uint8
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (&) = (x: Uint8, y: Uint8) => {
+  // Tags getting `and`ed together is not a problem
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  let val = x & y
+  WasmI32.toGrain(val): Uint8
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (|) = (x: Uint8, y: Uint8) => {
+  // Tags getting `or`ed together is not a problem
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  let val = x | y
+  WasmI32.toGrain(val): Uint8
+}
+
+/**
+ * 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.6.0
+ */
+@unsafe
+provide let (^) = (x: Uint8, y: Uint8) => {
+  use WasmI32.{ (|) }
+  // Tags getting `xor`ed together will cancel each other out; add back tag with or
+  let x = WasmI32.fromGrain(x)
+  let y = WasmI32.fromGrain(y)
+  let val = x ^ y
+  WasmI32.toGrain(val | _TAG_BYTE): Uint8
+}