@grain/stdlib 0.5.13 → 0.6.0

package/float32.gr

@@ -1,95 +1,72 @@
 /**
- * @module Float32: Utilities for working with the Float32 type.
- * @example import Float32 from "float32"
- * 
+ * Utilities for working with the Float32 type.
+ *
+ * @example from "float32" include Float32
+ *
+ * @example 4.0f
+ * @example -4.0f
+ * @example Infinityf
+ * @example NaNf
+ *
  * @since v0.2.0
  */
-import WasmI32 from "runtime/unsafe/wasmi32"
-import WasmF32 from "runtime/unsafe/wasmf32"
-import { newFloat32 } from "runtime/dataStructures"
+module Float32
+
+from "runtime/unsafe/wasmi32" include WasmI32
+from "runtime/unsafe/wasmf32" include WasmF32
+use WasmF32.{ (+), (-), (*), (/), (<), (<=), (>), (>=) }
+from "runtime/dataStructures" include DataStructures
+use DataStructures.{ newFloat32 }
 
-import {
+from "runtime/numbers" include Numbers
+use Numbers.{
   coerceNumberToFloat32 as fromNumber,
   coerceFloat32ToNumber as toNumber,
-} from "runtime/numbers"
+}
 
-/**
- * @section Constants: Float32 constant values.
- */
+@unsafe
+let _VALUE_OFFSET = 4n
 
 /**
  * Infinity represented as a Float32 value.
- * 
+ * This is an alternative to the `Infinityf` literal.
+ *
  * @since v0.4.0
  */
 @unsafe
-export let infinity = {
-  let ptr = newFloat32(
-    WasmF32.reinterpretI32(0b01111111100000000000000000000000n)
-  )
-  WasmI32.toGrain(ptr): Float32
-}
+provide let infinity = Infinityf
 
 /**
  * NaN (Not a Number) represented as a Float32 value.
- * 
+ * This is an alternative to the `NaNf` literal.
+ *
  * @since v0.4.0
  */
 @unsafe
-export let nan = {
-  let ptr = newFloat32(
-    WasmF32.reinterpretI32(0b01111111100000000000000000000001n)
-  )
-  WasmI32.toGrain(ptr): Float32
-}
+provide let nan = NaNf
 
 /**
  * Pi represented as a Float32 value.
- * 
+ *
  * @since v0.5.2
  */
-export let pi = 3.1415927f
+provide let pi = 3.1415927f
 
 /**
  * Tau represented as a Float32 value.
- * 
+ *
  * @since v0.5.2
  */
-export let tau = 6.2831853f
+provide let tau = 6.2831853f
 
 /**
  * Euler's number represented as a Float32 value.
- * 
- * @since v0.5.2
- */
-export let e = 2.7182817f
-/**
- * @section Conversions: Functions for converting between Numbers and the Float32 type.
- */
-
-/**
- * Converts a Number to a Float32.
  *
- * @param number: The value to convert
- * @returns The Number represented as a Float32
- * 
- * @since v0.2.0
- */
-export fromNumber
-
-/**
- * Converts a Float32 to a Number.
- *
- * @param float: The value to convert
- * @returns The Float32 represented as a Number
- * 
- * @since v0.2.0
+ * @since v0.5.2
  */
-export toNumber
+provide let e = 2.7182817f
 
-/**
- * @section Operations: Mathematical operations for Float32 values.
- */
+provide { fromNumber, toNumber }
 
 /**
  * Computes the sum of its operands.
@@ -97,14 +74,19 @@ export toNumber
  * @param x: The first operand
  * @param y: The second operand
  * @returns The sum of the two operands
- * 
- * @since v0.2.0
+ *
+ * @example
+ * use Float32.{ (+) }
+ * assert 1.0f + 1.0f == 2.0f
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `add`
  */
 @unsafe
-export let add = (x: Float32, y: Float32) => {
-  let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmF32.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newFloat32(WasmF32.add(xv, yv))
+provide let (+) = (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(xv + yv)
   WasmI32.toGrain(ptr): Float32
 }
 
@@ -114,14 +96,19 @@ export let add = (x: Float32, y: Float32) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The difference of the two operands
- * 
- * @since v0.2.0
+ *
+ * @example
+ * use Float32.{ (-) }
+ * assert 1.0f - 1.0f == 0.0f
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `sub`
  */
 @unsafe
-export let sub = (x: Float32, y: Float32) => {
-  let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmF32.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newFloat32(WasmF32.sub(xv, yv))
+provide let (-) = (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(xv - yv)
   WasmI32.toGrain(ptr): Float32
 }
 
@@ -131,14 +118,19 @@ export let sub = (x: Float32, y: Float32) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The product of the two operands
- * 
- * @since v0.2.0
+ *
+ * @example
+ * use Float32.{ (*) }
+ * assert 2.0f * 2.0f == 4.0f
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `mul`
  */
 @unsafe
-export let mul = (x: Float32, y: Float32) => {
-  let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmF32.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newFloat32(WasmF32.mul(xv, yv))
+provide let (*) = (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(xv * yv)
   WasmI32.toGrain(ptr): Float32
 }
 
@@ -148,35 +140,41 @@ export let mul = (x: Float32, y: Float32) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The quotient of the two operands
- * 
- * @since v0.2.0
+ *
+ * @example
+ * use Float32.{ (/) }
+ * assert 10.0f / 4.0f == 2.5f
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `div`
  */
 @unsafe
-export let div = (x: Float32, y: Float32) => {
-  let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmF32.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newFloat32(WasmF32.div(xv, yv))
+provide let (/) = (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(xv / yv)
   WasmI32.toGrain(ptr): Float32
 }
 
-/**
- * @section Comparisons: Functions for comparing Float32 values.
- */
-
 /**
  * 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
+ *
+ * @example
+ * use Float32.{ (<) }
+ * assert 1.0f < 2.0f
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `lt`
  */
 @unsafe
-export let lt = (x: Float32, y: Float32) => {
-  let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmF32.load(WasmI32.fromGrain(y), 8n)
-  WasmF32.lt(xv, yv)
+provide let (<) = (x: Float32, y: Float32) => {
+  let xv = WasmF32.load(WasmI32.fromGrain(x), _VALUE_OFFSET)
+  let yv = WasmF32.load(WasmI32.fromGrain(y), _VALUE_OFFSET)
+  xv < yv
 }
 
 /**
@@ -185,14 +183,19 @@ export let lt = (x: Float32, y: Float32) => {
  * @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
+ *
+ * @example
+ * use Float32.{ (>) }
+ * assert 2.0f > 1.0f
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `gt`
  */
 @unsafe
-export let gt = (x: Float32, y: Float32) => {
-  let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmF32.load(WasmI32.fromGrain(y), 8n)
-  WasmF32.gt(xv, yv)
+provide let (>) = (x: Float32, y: Float32) => {
+  let xv = WasmF32.load(WasmI32.fromGrain(x), _VALUE_OFFSET)
+  let yv = WasmF32.load(WasmI32.fromGrain(y), _VALUE_OFFSET)
+  xv > yv
 }
 
 /**
@@ -201,14 +204,23 @@ export let gt = (x: Float32, y: Float32) => {
  * @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
+ *
+ * @example
+ * use Float32.{ (<=) }
+ * assert -1.0f <= 1.0f
+ *
+ * @example
+ * use Float32.{ (<=) }
+ * assert -2.0f <= -2.0f
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `lte`
  */
 @unsafe
-export let lte = (x: Float32, y: Float32) => {
-  let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmF32.load(WasmI32.fromGrain(y), 8n)
-  WasmF32.le(xv, yv)
+provide let (<=) = (x: Float32, y: Float32) => {
+  let xv = WasmF32.load(WasmI32.fromGrain(x), _VALUE_OFFSET)
+  let yv = WasmF32.load(WasmI32.fromGrain(y), _VALUE_OFFSET)
+  xv <= yv
 }
 
 /**
@@ -217,12 +229,21 @@ export let lte = (x: Float32, y: Float32) => {
  * @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
+ *
+ * @example
+ * use Float32.{ (>=) }
+ * assert 4.0f >= 1.0f
+ *
+ * @example
+ * use Float32.{ (>=) }
+ * assert 3.0f >= 3.0f
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `gte`
  */
 @unsafe
-export let gte = (x: Float32, y: Float32) => {
-  let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
-  let yv = WasmF32.load(WasmI32.fromGrain(y), 8n)
-  WasmF32.ge(xv, yv)
+provide let (>=) = (x: Float32, y: Float32) => {
+  let xv = WasmF32.load(WasmI32.fromGrain(x), _VALUE_OFFSET)
+  let yv = WasmF32.load(WasmI32.fromGrain(y), _VALUE_OFFSET)
+  xv >= yv
 }