@grain/stdlib 0.5.13 → 0.6.0

package/float32.md

@@ -10,12 +10,28 @@ No other changes yet.
 </details>
 
 ```grain
-import Float32 from "float32"
+from "float32" include Float32
 ```
 
-## Constants
+```grain
+4.0f
+```
+
+```grain
+-4.0f
+```
+
+```grain
+Infinityf
+```
+
+```grain
+NaNf
+```
+
+## Values
 
-Float32 constant values.
+Functions and constants included in the Float32 module.
 
 ### Float32.**infinity**
 
@@ -29,6 +45,7 @@ infinity : Float32
 ```
 
 Infinity represented as a Float32 value.
+This is an alternative to the `Infinityf` literal.
 
 ### Float32.**nan**
 
@@ -42,6 +59,7 @@ nan : Float32
 ```
 
 NaN (Not a Number) represented as a Float32 value.
+This is an alternative to the `NaNf` literal.
 
 ### Float32.**pi**
 
@@ -82,10 +100,6 @@ e : Float32
 
 Euler's number represented as a Float32 value.
 
-## Conversions
-
-Functions for converting between Numbers and the Float32 type.
-
 ### Float32.**fromNumber**
 
 <details disabled>
@@ -94,7 +108,7 @@ No other changes yet.
 </details>
 
 ```grain
-fromNumber : Number -> Float32
+fromNumber : (number: Number) => Float32
 ```
 
 Converts a Number to a Float32.
@@ -119,7 +133,7 @@ No other changes yet.
 </details>
 
 ```grain
-toNumber : Float32 -> Number
+toNumber : (float: Float32) => Number
 ```
 
 Converts a Float32 to a Number.
@@ -136,19 +150,22 @@ Returns:
 |----|-----------|
 |`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.
+### Float32.**(+)**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `add`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-add : (Float32, Float32) -> Float32
+(+) : (x: Float32, y: Float32) => Float32
 ```
 
 Computes the sum of its operands.
@@ -166,15 +183,29 @@ Returns:
 |----|-----------|
 |`Float32`|The sum of the two operands|
 
-### Float32.**sub**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+```grain
+use Float32.{ (+) }
+assert 1.0f + 1.0f == 2.0f
+```
+
+### Float32.**(-)**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `sub`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-sub : (Float32, Float32) -> Float32
+(-) : (x: Float32, y: Float32) => Float32
 ```
 
 Computes the difference of its operands.
@@ -192,15 +223,29 @@ Returns:
 |----|-----------|
 |`Float32`|The difference of the two operands|
 
-### Float32.**mul**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+```grain
+use Float32.{ (-) }
+assert 1.0f - 1.0f == 0.0f
+```
+
+### Float32.**(*)**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `mul`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-mul : (Float32, Float32) -> Float32
+(*) : (x: Float32, y: Float32) => Float32
 ```
 
 Computes the product of its operands.
@@ -218,15 +263,29 @@ Returns:
 |----|-----------|
 |`Float32`|The product of the two operands|
 
-### Float32.**div**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+```grain
+use Float32.{ (*) }
+assert 2.0f * 2.0f == 4.0f
+```
+
+### Float32.**(/)**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `div`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-div : (Float32, Float32) -> Float32
+(/) : (x: Float32, y: Float32) => Float32
 ```
 
 Computes the quotient of its operands.
@@ -244,19 +303,29 @@ Returns:
 |----|-----------|
 |`Float32`|The quotient of the two operands|
 
-## Comparisons
-
-Functions for comparing Float32 values.
+Examples:
 
-### Float32.**lt**
+```grain
+use Float32.{ (/) }
+assert 10.0f / 4.0f == 2.5f
+```
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+### Float32.**(<)**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `lt`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-lt : (Float32, Float32) -> Bool
+(<) : (x: Float32, y: Float32) => Bool
 ```
 
 Checks if the first value is less than the second value.
@@ -274,15 +343,29 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than the second value or `false` otherwise|
 
-### Float32.**gt**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+```grain
+use Float32.{ (<) }
+assert 1.0f < 2.0f
+```
+
+### Float32.**(>)**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `gt`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-gt : (Float32, Float32) -> Bool
+(>) : (x: Float32, y: Float32) => Bool
 ```
 
 Checks if the first value is greater than the second value.
@@ -300,15 +383,29 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than the second value or `false` otherwise|
 
-### Float32.**lte**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+```grain
+use Float32.{ (>) }
+assert 2.0f > 1.0f
+```
+
+### Float32.**(<=)**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `lte`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-lte : (Float32, Float32) -> Bool
+(<=) : (x: Float32, y: Float32) => Bool
 ```
 
 Checks if the first value is less than or equal to the second value.
@@ -326,15 +423,34 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than or equal to the second value or `false` otherwise|
 
-### Float32.**gte**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+```grain
+use Float32.{ (<=) }
+assert -1.0f <= 1.0f
+```
+
+```grain
+use Float32.{ (<=) }
+assert -2.0f <= -2.0f
+```
+
+### Float32.**(>=)**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `gte`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-gte : (Float32, Float32) -> Bool
+(>=) : (x: Float32, y: Float32) => Bool
 ```
 
 Checks if the first value is greater than or equal to the second value.
@@ -352,3 +468,15 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than or equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+use Float32.{ (>=) }
+assert 4.0f >= 1.0f
+```
+
+```grain
+use Float32.{ (>=) }
+assert 3.0f >= 3.0f
+```
+

package/float64.gr

@@ -1,100 +1,69 @@
 /**
- * @module Float64: Utilities for working with the Float64 type.
- * @example import Float64 from "float64"
- * 
+ * Utilities for working with the Float64 type.
+ *
+ * @example from "float64" include Float64
+ *
+ * @example 5.0d
+ * @example -5.0d
+ * @example Infinityd
+ * @example NaNd
+ *
  * @since v0.2.0
  */
-import WasmI32 from "runtime/unsafe/wasmi32"
-import WasmF64 from "runtime/unsafe/wasmf64"
-import { newFloat64 } from "runtime/dataStructures"
+module Float64
+
+from "runtime/unsafe/wasmi32" include WasmI32
+from "runtime/unsafe/wasmf64" include WasmF64
+use WasmF64.{ (-), (+), (*), (/), (<), (<=), (>), (>=) }
+from "runtime/dataStructures" include DataStructures
+use DataStructures.{ newFloat64 }
 
-import {
+from "runtime/numbers" include Numbers
+use Numbers.{
   coerceNumberToFloat64 as fromNumber,
   coerceFloat64ToNumber as toNumber,
-} from "runtime/numbers"
-
-/**
- * @section Constants: Float64 constant values.
- */
+}
 
 /**
  * Infinity represented as a Float64 value.
- * 
+ * This is an alternative to the `Infinityd` literal.
+ *
  * @since v0.4.0
  */
 @unsafe
-export let infinity = {
-  let ptr = newFloat64(
-    WasmF64.reinterpretI64(
-      0b0111111111110000000000000000000000000000000000000000000000000000N
-    )
-  )
-  WasmI32.toGrain(ptr): Float64
-}
+provide let infinity = Infinityd
 
 /**
  * NaN (Not a Number) represented as a Float64 value.
- * 
+ * This is an alternative to the `NaNd` literal.
+ *
  * @since v0.4.0
  */
 @unsafe
-export let nan = {
-  let ptr = newFloat64(
-    WasmF64.reinterpretI64(
-      0b0111111111110000000000000000000000000000000000000000000000000001N
-    )
-  )
-  WasmI32.toGrain(ptr): Float64
-}
+provide let nan = NaNd
 
 /**
  * Pi represented as a Float64 value.
- * 
+ *
  * @since v0.5.2
  */
-export let pi = 3.141592653589793d
+provide let pi = 3.141592653589793d
 
 /**
  * Tau represented as a Float64 value.
- * 
+ *
  * @since v0.5.2
  */
-export let tau = 6.283185307179586d
+provide let tau = 6.283185307179586d
 
 /**
  * Euler's number represented as a Float64 value.
- * 
- * @since v0.5.2
- */
-export let e = 2.718281828459045d
-
-/**
- * @section Conversions: Functions for converting between Numbers and the Float64 type.
- */
-
-/**
- * Converts a Number to a Float64.
  *
- * @param number: The value to convert
- * @returns The Number represented as a Float64
- * 
- * @since v0.2.0
+ * @since v0.5.2
  */
-export fromNumber
+provide let e = 2.718281828459045d
 
-/**
- * Converts a Float64 to a Number.
- *
- * @param float: The value to convert
- * @returns The Float64 represented as a Number
- * 
- * @since v0.2.0
- */
-export toNumber
-
-/**
- * @section Operations: Mathematical operations for Float64 values.
- */
+provide { fromNumber, toNumber }
 
 /**
  * Computes the sum of its operands.
@@ -102,14 +71,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 Float64.{ (+) }
+ * assert 1.0d + 1.0d == 2.0d
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `add`
  */
 @unsafe
-export let add = (x: Float64, y: Float64) => {
+provide let (+) = (x: Float64, y: Float64) => {
   let xv = WasmF64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmF64.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newFloat64(WasmF64.add(xv, yv))
+  let ptr = newFloat64(xv + yv)
   WasmI32.toGrain(ptr): Float64
 }
 
@@ -119,14 +93,19 @@ export let add = (x: Float64, y: Float64) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The difference of the two operands
- * 
- * @since v0.2.0
+ *
+ * @example
+ * use Float64.{ (-) }
+ * assert 5.0d - 4.0d == 1.0d
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `sub`
  */
 @unsafe
-export let sub = (x: Float64, y: Float64) => {
+provide let (-) = (x: Float64, y: Float64) => {
   let xv = WasmF64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmF64.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newFloat64(WasmF64.sub(xv, yv))
+  let ptr = newFloat64(xv - yv)
   WasmI32.toGrain(ptr): Float64
 }
 
@@ -136,14 +115,19 @@ export let sub = (x: Float64, y: Float64) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The product of the two operands
- * 
- * @since v0.2.0
+ *
+ * @example
+ * use Float64.{ (*) }
+ * assert -5.0d * 4.0d == -20.0d
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `mul`
  */
 @unsafe
-export let mul = (x: Float64, y: Float64) => {
+provide let (*) = (x: Float64, y: Float64) => {
   let xv = WasmF64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmF64.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newFloat64(WasmF64.mul(xv, yv))
+  let ptr = newFloat64(xv * yv)
   WasmI32.toGrain(ptr): Float64
 }
 
@@ -153,35 +137,41 @@ export let mul = (x: Float64, y: Float64) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The quotient of the two operands
- * 
- * @since v0.2.0
+ *
+ * @example
+ * use Float64.{ (/) }
+ * assert 25.0d / 4.0d == 6.25d
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `div`
  */
 @unsafe
-export let div = (x: Float64, y: Float64) => {
+provide let (/) = (x: Float64, y: Float64) => {
   let xv = WasmF64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmF64.load(WasmI32.fromGrain(y), 8n)
-  let ptr = newFloat64(WasmF64.div(xv, yv))
+  let ptr = newFloat64(xv / yv)
   WasmI32.toGrain(ptr): Float64
 }
 
-/**
- * @section Comparisons: Functions for comparing Float64 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 Float64.{ (<) }
+ * assert -5.0d < 5.0d
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `lt`
  */
 @unsafe
-export let lt = (x: Float64, y: Float64) => {
+provide let (<) = (x: Float64, y: Float64) => {
   let xv = WasmF64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmF64.load(WasmI32.fromGrain(y), 8n)
-  WasmF64.lt(xv, yv)
+  xv < yv
 }
 
 /**
@@ -190,14 +180,19 @@ export let lt = (x: Float64, y: Float64) => {
  * @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 Float64.{ (>) }
+ * assert 6.0d > 5.0d
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `gt`
  */
 @unsafe
-export let gt = (x: Float64, y: Float64) => {
+provide let (>) = (x: Float64, y: Float64) => {
   let xv = WasmF64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmF64.load(WasmI32.fromGrain(y), 8n)
-  WasmF64.gt(xv, yv)
+  xv > yv
 }
 
 /**
@@ -206,14 +201,23 @@ export let gt = (x: Float64, y: Float64) => {
  * @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 Float64.{ (<=) }
+ * assert 1.0d <= 2.0d
+ *
+ * @example
+ * use Float64.{ (<=) }
+ * assert 2.0d <= 2.0d
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `lte`
  */
 @unsafe
-export let lte = (x: Float64, y: Float64) => {
+provide let (<=) = (x: Float64, y: Float64) => {
   let xv = WasmF64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmF64.load(WasmI32.fromGrain(y), 8n)
-  WasmF64.le(xv, yv)
+  xv <= yv
 }
 
 /**
@@ -222,12 +226,21 @@ export let lte = (x: Float64, y: Float64) => {
  * @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 Float64.{ (>=) }
+ * assert 5.0d >= 2.0d
+ *
+ * @example
+ * use Float64.{ (>=) }
+ * assert -1.0d >= -1.0d
+ *
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `gte`
  */
 @unsafe
-export let gte = (x: Float64, y: Float64) => {
+provide let (>=) = (x: Float64, y: Float64) => {
   let xv = WasmF64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmF64.load(WasmI32.fromGrain(y), 8n)
-  WasmF64.ge(xv, yv)
+  xv >= yv
 }