@grain/stdlib 0.6.6 → 0.7.1

package/exception.gr

@@ -12,8 +12,6 @@
  */
 module Exception
 
-from "runtime/unsafe/wasmi32" include WasmI32
-from "runtime/unsafe/memory" include Memory
 from "runtime/exception" include Exception
 
 /**
@@ -39,13 +37,15 @@ from "runtime/exception" include Exception
  *
  * @since v0.3.0
  */
-@disableGC
-provide let rec registerPrinter = (printer: Exception => Option<String>) => {
-  // This function _must_ be @disableGC because the printer list uses
-  // unsafe types. Not really a memory leak as this list is never collected
+provide let registerPrinter = Exception.registerPrinter
 
-  // no need to increment refcount on f; we just don't decRef it at the end of the function
-  Exception.printers = WasmI32.fromGrain((printer, Exception.printers))
-  Memory.decRef(WasmI32.fromGrain(registerPrinter))
-  void
-}
+/**
+ * Gets the string representation of the given exception.
+ *
+ * @param e: The exception to stringify
+ *
+ * @returns The string representation of the exception
+ *
+ * @since v0.7.0
+ */
+provide let toString = Exception.toString

package/exception.md

@@ -35,7 +35,7 @@ No other changes yet.
 </details>
 
 ```grain
-registerPrinter : (printer: (Exception => Option<String>)) => Void
+registerPrinter: (printer: (Exception => Option<String>)) => Void
 ```
 
 Registers an exception printer. When an exception is thrown, all registered
@@ -45,9 +45,9 @@ used as the exception's string value.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`printer`|`Exception => Option<String>`|The exception printer to register|
+| param     | type                          | description                       |
+| --------- | ----------------------------- | --------------------------------- |
+| `printer` | `Exception => Option<String>` | The exception printer to register |
 
 Examples:
 
@@ -65,3 +65,28 @@ Exception.registerPrinter(e => {
 throw ExampleError(1) // Error found on line: 1
 ```
 
+### Exception.**toString**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toString: (e: Exception) => String
+```
+
+Gets the string representation of the given exception.
+
+Parameters:
+
+| param | type        | description                |
+| ----- | ----------- | -------------------------- |
+| `e`   | `Exception` | The exception to stringify |
+
+Returns:
+
+| type     | description                                |
+| -------- | ------------------------------------------ |
+| `String` | The string representation of the exception |
+

package/float32.gr

@@ -12,8 +12,15 @@
  */
 module Float32
 
+from "runtime/unsafe/offsets" include Offsets
+use Offsets.{
+  _FLOAT32_VALUE_OFFSET as _VALUE_OFFSET,
+  _INT32_VALUE_OFFSET,
+  _UINT32_VALUE_OFFSET,
+}
 from "runtime/unsafe/wasmi32" include WasmI32
 from "runtime/unsafe/wasmf32" include WasmF32
+from "runtime/unsafe/wasmf64" include WasmF64
 use WasmF32.{ (+), (-), (*), (/), (<), (<=), (>), (>=) }
 from "runtime/dataStructures" include DataStructures
 use DataStructures.{ newFloat32 }
@@ -23,9 +30,8 @@ use Numbers.{
   coerceNumberToFloat32 as fromNumber,
   coerceFloat32ToNumber as toNumber,
 }
-
-@unsafe
-let _VALUE_OFFSET = 4n
+from "runtime/math/trig" include Trig
+use Trig.{ sin, cos, tan }
 
 /**
  * Infinity represented as a Float32 value.
@@ -68,6 +74,41 @@ provide let e = 2.7182817f
 
 provide { fromNumber, toNumber }
 
+/**
+ * Interprets an Int32 as a Float32.
+ *
+ * @param value: The value to convert
+ * @returns The Int32 interpreted as an Float32
+ *
+ * @example assert Float32.reinterpretInt32(1065353216l) == 1.0f
+ * @example assert Float32.reinterpretInt32(-1082130432l) == -1.0f
+ * @since v0.7.0
+ */
+@unsafe
+provide let reinterpretInt32 = (value: Int32) => {
+  let x = WasmF32.load(WasmI32.fromGrain(value), _INT32_VALUE_OFFSET)
+  let result = newFloat32(x)
+  WasmI32.toGrain(result): Float32
+}
+
+/**
+ * Interprets an Uint32 as a Float32.
+ *
+ * @param value: The value to convert
+ * @returns The Uint32 interpreted as an Float32
+ *
+ * @example assert Float32.reinterpretUint32(1065353216ul) == 1.0f
+ * @example assert Float32.reinterpretUint32(3212836864ul) == -1.0f
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let reinterpretUint32 = (value: Uint32) => {
+  let x = WasmF32.load(WasmI32.fromGrain(value), _UINT32_VALUE_OFFSET)
+  let result = newFloat32(x)
+  WasmI32.toGrain(result): Float32
+}
+
 /**
  * Computes the sum of its operands.
  *
@@ -156,6 +197,31 @@ provide let (/) = (x: Float32, y: Float32) => {
   WasmI32.toGrain(ptr): Float32
 }
 
+/**
+ * Computes the exponentiation of the given base and power.
+ *
+ * @param base: The base float
+ * @param power: The exponent float
+ * @returns The base raised to the given power
+ *
+ * @example
+ * use Float64.{ (**) }
+ * assert 2.0f ** 2.0f == 4.0f
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let (**) = (base: Float32, power: Float32) => {
+  let basev = WasmF32.load(WasmI32.fromGrain(base), _VALUE_OFFSET)
+  let powerv = WasmF32.load(WasmI32.fromGrain(power), _VALUE_OFFSET)
+  let value = Numbers.powf(
+    WasmF64.promoteF32(basev),
+    WasmF64.promoteF32(powerv)
+  )
+  let ptr = newFloat32(WasmF32.demoteF64(value))
+  WasmI32.toGrain(ptr): Float32
+}
+
 /**
  * Checks if the first value is less than the second value.
  *
@@ -248,6 +314,29 @@ provide let (>=) = (x: Float32, y: Float32) => {
   xv >= yv
 }
 
+/**
+ * Checks if a float is finite.
+ * All values are finite exept for NaN, infinity or negative infinity.
+ *
+ * @param x: The number to check
+ * @returns `true` if the value is finite or `false` otherwise
+ *
+ * @example Float32.isFinite(0.5f)
+ * @example Float32.isFinite(1.0f)
+ * @example Float32.isFinite(Infinityf) == false
+ * @example Float32.isFinite(-Infinityf) == false
+ * @example Float32.isFinite(NaNf) == false
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let isFinite = (x: Float32) => {
+  // uses the fact that all finite floats minus themselves are zero
+  // (NaN - NaN == NaN, inf - inf == NaN,
+  //  -inf - -inf == NaN, inf - -inf == inf, -inf - inf == -inf)
+  x - x == 0.0f
+}
+
 /**
  * Checks if the value is a float NaN value (Not A Number).
  *
@@ -280,6 +369,44 @@ provide let isNaN = (x: Float32) => x != x
  */
 provide let isInfinite = (x: Float32) => x == Infinityf || x == -Infinityf
 
+/**
+ * Returns the smaller of its operands.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The smaller of the two operands
+ *
+ * @example Float32.min(5.0f, 2.0f) == 2.0f
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let min = (x: Float32, y: Float32) => {
+  let xv = WasmF32.load(WasmI32.fromGrain(x), _VALUE_OFFSET)
+  let yv = WasmF32.load(WasmI32.fromGrain(y), _VALUE_OFFSET)
+  let ptr = newFloat32(WasmF32.min(xv, yv))
+  WasmI32.toGrain(ptr): Float32
+}
+
+/**
+ * Returns the larger of its operands.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The larger of the two operands
+ *
+ * @example Float32.max(5.0f, 2.0f) == 5.0f
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let max = (x: Float32, y: Float32) => {
+  let xv = WasmF32.load(WasmI32.fromGrain(x), _VALUE_OFFSET)
+  let yv = WasmF32.load(WasmI32.fromGrain(y), _VALUE_OFFSET)
+  let ptr = newFloat32(WasmF32.max(xv, yv))
+  WasmI32.toGrain(ptr): Float32
+}
+
 /**
  * Returns the absolute value. That is, it returns `x` if `x` is positive or zero and the negation of `x` if `x` is negative.
  *
@@ -315,3 +442,200 @@ provide let neg = (x: Float32) => {
   let ptr = newFloat32(WasmF32.neg(xv))
   WasmI32.toGrain(ptr): Float32
 }
+
+/**
+ * Rounds its operand up to the next largest whole value.
+ *
+ * @param x: The operand to ceil
+ * @returns The next largest whole value of the operand
+ *
+ * @example Float32.ceil(5.5f) == 6.0f
+ * @example Float32.ceil(-5.5f) == -5.0f
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let ceil = (x: Float32) => {
+  let xv = WasmF32.load(WasmI32.fromGrain(x), _VALUE_OFFSET)
+  let ptr = newFloat32(WasmF32.ceil(xv))
+  WasmI32.toGrain(ptr): Float32
+}
+
+/**
+ * Rounds its operand down to the largest whole value less than the operand.
+ *
+ * @param x: The operand to floor
+ * @returns The previous whole value of the operand
+ *
+ * @example Float32.floor(5.5f) == 5.0f
+ * @example Float32.floor(-5.5f) == -6.0f
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let floor = (x: Float32) => {
+  let xv = WasmF32.load(WasmI32.fromGrain(x), _VALUE_OFFSET)
+  let ptr = newFloat32(WasmF32.floor(xv))
+  WasmI32.toGrain(ptr): Float32
+}
+
+/**
+ * Returns the whole value part of its operand, removing any fractional value.
+ *
+ * @param x: The operand to truncate
+ * @returns The whole value part of the operand
+ *
+ * @example Float32.trunc(5.5f) == 5.0f
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let trunc = (x: Float32) => {
+  let xv = WasmF32.load(WasmI32.fromGrain(x), _VALUE_OFFSET)
+  let ptr = newFloat32(WasmF32.trunc(xv))
+  WasmI32.toGrain(ptr): Float32
+}
+
+/**
+ * Returns its operand rounded to its nearest integer.
+ *
+ * @param x: The operand to round
+ * @returns The nearest integer to the operand
+ *
+ * @example Float32.round(5.5f) == 6.0f
+ * @example Float32.round(5.4f) == 5.0f
+ * @example Float32.round(-5.5f) == -6.0f
+ * @example Float32.round(-5.4f) == -5.0f
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let round = (x: Float32) => {
+  let xv = WasmF32.load(WasmI32.fromGrain(x), _VALUE_OFFSET)
+  let ptr = newFloat32(WasmF32.nearest(xv))
+  WasmI32.toGrain(ptr): Float32
+}
+
+/**
+ * Computes the square root of its operand.
+ *
+ * @param x: The operand to square root
+ * @returns The square root of the operand
+ *
+ * @example Float32.sqrt(25.0f) == 5.0f
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let sqrt = (x: Float32) => {
+  let xv = WasmF32.load(WasmI32.fromGrain(x), _VALUE_OFFSET)
+  let ptr = newFloat32(WasmF32.sqrt(xv))
+  WasmI32.toGrain(ptr): Float32
+}
+
+/**
+ * Copys the sign of the second operand to the first operand.
+ *
+ * @param x: The operand to modify
+ * @param y: The operand to copy the sign from
+ * @returns The first operand with the sign of the second operand
+ *
+ * @example Float32.copySign(2.0f, 1.0f) == 2.0f
+ * @example Float32.copySign(3.0f, -1.0f) == -3.0f
+ * @example Float32.copySign(-5.0f, 1.0f) == 5.0f
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let copySign = (x: Float32, y: Float32) => {
+  let xv = WasmF32.load(WasmI32.fromGrain(x), _VALUE_OFFSET)
+  let yv = WasmF32.load(WasmI32.fromGrain(y), _VALUE_OFFSET)
+  let ptr = newFloat32(WasmF32.copySign(xv, yv))
+  WasmI32.toGrain(ptr): Float32
+}
+
+/**
+ * Determines whether two values are considered close to each other using a relative and absolute tolerance.
+ *
+ * @param a: The first value
+ * @param b: The second value
+ * @param relativeTolerance: The maximum tolerance to use relative to the larger absolute value `a` or `b`
+ * @param absoluteTolerance: The absolute tolerance to use, regardless of the values of `a` or `b`
+ * @returns `true` if the values are considered close to each other or `false` otherwise
+ *
+ * @example Float32.isClose(1.233f, 1.233f)
+ * @example Float32.isClose(1.233f, 1.233000001f)
+ * @example Float32.isClose(8.005f, 8.450f, absoluteTolerance=0.5f)
+ * @example Float32.isClose(4.0f, 4.1f, relativeTolerance=0.025f)
+ * @example Float32.isClose(1.233f, 1.24f) == false
+ * @example Float32.isClose(1.233f, 1.4566f) == false
+ * @example Float32.isClose(8.005f, 8.450f, absoluteTolerance=0.4f) == false
+ * @example Float32.isClose(4.0f, 4.1f, relativeTolerance=0.024f) == false
+ *
+ * @since v0.7.0
+ */
+provide let isClose = (a, b, relativeTolerance=1e-9f, absoluteTolerance=0.0f) => {
+  if (a == b) {
+    true
+  } else if (isFinite(a) && isFinite(b)) {
+    abs(a - b)
+      <= max(relativeTolerance * max(abs(a), abs(b)), absoluteTolerance)
+  } else {
+    // NaN and infinities which were not equal
+    false
+  }
+}
+
+/**
+ * Computes the sine of a float (in radians).
+ *
+ * @param radians: The input in radians
+ * @returns The computed sine
+ *
+ * @example Float32.sin(0.0f) == 0.0f
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let sin = (radians: Float32) => {
+  // TODO(#2167): Implement Float32 optimized trig functions
+  let xval = WasmF32.load(WasmI32.fromGrain(radians), _VALUE_OFFSET)
+  let value = sin(WasmF64.promoteF32(xval))
+  WasmI32.toGrain(newFloat32(WasmF32.demoteF64(value))): Float32
+}
+
+/**
+ * Computes the cosine of a float (in radians).
+ *
+ * @param radians: The input in radians
+ * @returns The computed cosine
+ *
+ * @example Float32.cos(0.0f) == 1.0f
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let cos = (radians: Float32) => {
+  // TODO(#2167): Implement Float32 optimized trig functions
+  let xval = WasmF32.load(WasmI32.fromGrain(radians), _VALUE_OFFSET)
+  let value = cos(WasmF64.promoteF32(xval))
+  WasmI32.toGrain(newFloat32(WasmF32.demoteF64(value))): Float32
+}
+
+/**
+ * Computes the tangent of a number (in radians).
+ *
+ * @param radians: The input in radians
+ * @returns The computed tangent
+ *
+ * @example Float32.tan(0.0f) == 0.0f
+ *
+ * @since v0.7.0
+ */
+@unsafe
+provide let tan = (radians: Float32) => {
+  // TODO(#2167): Implement Float32 optimized trig functions
+  let xval = WasmF32.load(WasmI32.fromGrain(radians), _VALUE_OFFSET)
+  let value = tan(WasmF64.promoteF32(xval))
+  WasmI32.toGrain(newFloat32(WasmF32.demoteF64(value))): Float32
+}