@grain/stdlib 0.4.4 → 0.5.0

package/float32.gr

@@ -1,131 +1,208 @@
+/**
+ * @module Float32: Utilities for working with the Float32 type.
+ * @example import Float32 from "float32"
+ * 
+ * @since v0.2.0
+ */
 import WasmI32 from "runtime/unsafe/wasmi32"
 import WasmF32 from "runtime/unsafe/wasmf32"
-import Memory from "runtime/unsafe/memory"
-import {
-  newFloat32
-} from "runtime/dataStructures"
+import { newFloat32 } from "runtime/dataStructures"
 
 import {
   coerceNumberToFloat32 as fromNumber,
-  coerceFloat32ToNumber as toNumber
+  coerceFloat32ToNumber as toNumber,
 } from "runtime/numbers"
 
+/**
+ * @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
-export toNumber
 
+/**
+ * Converts a Float32 to a Number.
+ *
+ * @param float: The value to convert
+ * @returns The Float32 represented as a Number
+ * 
+ * @since v0.2.0
+ */
+export toNumber
 
-@disableGC
-export let rec add = (x: Float32, y: Float32) => {
+/**
+ * @section Operations: Mathematical operations for Float32 values.
+ */
+
+/**
+ * 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: 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))
-  let ret = WasmI32.toGrain(ptr) : Float32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(add))
-  ret
+  WasmI32.toGrain(ptr): Float32
 }
 
-@disableGC
-export let rec sub = (x: Float32, y: Float32) => {
+/**
+ * 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: 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))
-  let ret = WasmI32.toGrain(ptr) : Float32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(sub))
-  ret
+  WasmI32.toGrain(ptr): Float32
 }
 
-@disableGC
-export let rec mul = (x: Float32, y: Float32) => {
+/**
+ * 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: 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))
-  let ret = WasmI32.toGrain(ptr) : Float32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(mul))
-  ret
+  WasmI32.toGrain(ptr): Float32
 }
 
-@disableGC
-export let rec div = (x: Float32, y: Float32) => {
+/**
+ * Computes the quotient of its operands.
+ *
+ * @param x: The first operand
+ * @param y: The second operand
+ * @returns The quotient of the two operands
+ * 
+ * @since v0.2.0
+ */
+@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))
-  let ret = WasmI32.toGrain(ptr) : Float32
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(div))
-  ret
+  WasmI32.toGrain(ptr): Float32
 }
 
-
-// Float32 comparisons
-@disableGC
-export let rec lt = (x: Float32, y: 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
+ */
+@unsafe
+export let lt = (x: Float32, y: Float32) => {
   let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmF32.load(WasmI32.fromGrain(y), 8n)
-  let ret = WasmF32.lt(xv, yv)
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(lt))
-  ret
+  WasmF32.lt(xv, yv)
 }
 
-@disableGC
-export let rec gt = (x: Float32, y: Float32) => {
+/**
+ * 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: Float32, y: Float32) => {
   let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmF32.load(WasmI32.fromGrain(y), 8n)
-  let ret = WasmF32.gt(xv, yv)
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(gt))
-  ret
+  WasmF32.gt(xv, yv)
 }
 
-@disableGC
-export let rec lte = (x: Float32, y: Float32) => {
+/**
+ * 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: Float32, y: Float32) => {
   let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmF32.load(WasmI32.fromGrain(y), 8n)
-  let ret = WasmF32.le(xv, yv)
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(lte))
-  ret
+  WasmF32.le(xv, yv)
 }
 
-@disableGC
-export let rec gte = (x: Float32, y: Float32) => {
+/**
+ * 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: Float32, y: Float32) => {
   let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmF32.load(WasmI32.fromGrain(y), 8n)
-  let ret = WasmF32.ge(xv, yv)
-  Memory.decRef(WasmI32.fromGrain(x))
-  Memory.decRef(WasmI32.fromGrain(y))
-  Memory.decRef(WasmI32.fromGrain(gte))
-  ret
+  WasmF32.ge(xv, yv)
 }
 
-// floating-point constants:
-
-@disableGC
-let rec makeInfinity = () => {
-  let ptr = newFloat32(WasmF32.reinterpretI32(0b01111111100000000000000000000000n))
-  let ret = WasmI32.toGrain(ptr) : Float32
-  Memory.decRef(WasmI32.fromGrain(makeInfinity))
-  ret
+/**
+ * @section Constants: Float32 constant values.
+ */
+
+/**
+ * Infinity represented as a Float32 value.
+ * 
+ * @since v0.4.0
+ */
+@unsafe
+export let infinity = {
+  let ptr = newFloat32(
+    WasmF32.reinterpretI32(0b01111111100000000000000000000000n)
+  )
+  WasmI32.toGrain(ptr): Float32
 }
 
-export let infinity = makeInfinity()
-
-@disableGC
-let rec makeNaN = () => {
-  let ptr = newFloat32(WasmF32.reinterpretI32(0b01111111100000000000000000000001n))
-  let ret = WasmI32.toGrain(ptr) : Float32
-  Memory.decRef(WasmI32.fromGrain(makeNaN))
-  ret
+/**
+ * NaN (Not a Number) represented as a Float32 value.
+ * 
+ * @since v0.4.0
+ */
+@unsafe
+export let nan = {
+  let ptr = newFloat32(
+    WasmF32.reinterpretI32(0b01111111100000000000000000000001n)
+  )
+  WasmI32.toGrain(ptr): Float32
 }
-
-export let nan = makeNaN()

package/float32.md

@@ -0,0 +1,315 @@
+---
+title: Float32
+---
+
+Utilities for working with the Float32 type.
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+import Float32 from "float32"
+```
+
+## Conversions
+
+Functions for converting between Numbers and the Float32 type.
+
+### Float32.**fromNumber**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromNumber : Number -> Float32
+```
+
+Converts a Number to a Float32.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`number`|`Number`|The value to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Float32`|The Number represented as a Float32|
+
+### Float32.**toNumber**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toNumber : Float32 -> Number
+```
+
+Converts a Float32 to a Number.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`float`|`Float32`|The value to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The Float32 represented as a Number|
+
+## Operations
+
+Mathematical operations for Float32 values.
+
+### Float32.**add**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+add : (Float32, Float32) -> Float32
+```
+
+Computes the sum of its operands.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Float32`|The first operand|
+|`y`|`Float32`|The second operand|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Float32`|The sum of the two operands|
+
+### Float32.**sub**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+sub : (Float32, Float32) -> Float32
+```
+
+Computes the difference of its operands.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Float32`|The first operand|
+|`y`|`Float32`|The second operand|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Float32`|The difference of the two operands|
+
+### Float32.**mul**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+mul : (Float32, Float32) -> Float32
+```
+
+Computes the product of its operands.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Float32`|The first operand|
+|`y`|`Float32`|The second operand|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Float32`|The product of the two operands|
+
+### Float32.**div**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+div : (Float32, Float32) -> Float32
+```
+
+Computes the quotient of its operands.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Float32`|The first operand|
+|`y`|`Float32`|The second operand|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Float32`|The quotient of the two operands|
+
+## Comparisons
+
+Functions for comparing Float32 values.
+
+### Float32.**lt**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+lt : (Float32, Float32) -> Bool
+```
+
+Checks if the first value is less than the second value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Float32`|The first value|
+|`y`|`Float32`|The second value|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the first value is less than the second value or `false` otherwise|
+
+### Float32.**gt**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+gt : (Float32, Float32) -> Bool
+```
+
+Checks if the first value is greater than the second value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Float32`|The first value|
+|`y`|`Float32`|The second value|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the first value is greater than the second value or `false` otherwise|
+
+### Float32.**lte**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+lte : (Float32, Float32) -> Bool
+```
+
+Checks if the first value is less than or equal to the second value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Float32`|The first value|
+|`y`|`Float32`|The second value|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the first value is less than or equal to the second value or `false` otherwise|
+
+### Float32.**gte**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+gte : (Float32, Float32) -> Bool
+```
+
+Checks if the first value is greater than or equal to the second value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`x`|`Float32`|The first value|
+|`y`|`Float32`|The second value|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the first value is greater than or equal to the second value or `false` otherwise|
+
+## Constants
+
+Float32 constant values.
+
+### Float32.**infinity**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.4.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+infinity : Float32
+```
+
+Infinity represented as a Float32 value.
+
+### Float32.**nan**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.4.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+nan : Float32
+```
+
+NaN (Not a Number) represented as a Float32 value.
+