@grain/stdlib 0.4.2 → 0.4.6

package/float64.md

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

package/hash.gr

@@ -1,5 +1,12 @@
 /* grainc-flags --no-gc */
 
+/**
+ * @module Hash: Utilities for hashing any value.
+ * @example import Hash from "hash"
+ *
+ * @since v0.1.0
+ */
+
 /**
   This module implements MurmurHash3 for Grain data types.
   https://en.wikipedia.org/wiki/MurmurHash
@@ -18,7 +25,7 @@ import WasmI32, {
   eq as (==),
   ne as (!=),
   gtU as (>),
-  ltU as (<)
+  ltU as (<),
 } from "runtime/unsafe/wasmi32"
 import Tags from "runtime/unsafe/tags"
 import Memory from "runtime/unsafe/memory"
@@ -48,17 +55,17 @@ let n = 0xe6546b64n
 
 let mut h = seed
 
-let hash32 = (k) => {
+let hash32 = k => {
   let mut k = k * c1
   k = WasmI32.rotl(k, r1)
   k *= c2
 
   h = h ^ k
   h = WasmI32.rotl(h, r2)
-  h = (h * m) + n
+  h = h * m + n
 }
 
-let hashRemaining = (r) => {
+let hashRemaining = r => {
   // Note: wasm is little-endian so no swap is necessary
 
   let mut r = r * c1
@@ -68,14 +75,14 @@ let hashRemaining = (r) => {
   h = h ^ r
 }
 
-let finalize = (len) => {
+let finalize = len => {
   h = h ^ len
 
-  h = h ^ (h >>> 16n)
+  h = h ^ h >>> 16n
   h *= 0x85ebca6bn
-  h = h ^ (h >>> 13n)
+  h = h ^ h >>> 13n
   h *= 0xc2b2ae35n
-  h = h ^ (h >>> 16n)
+  h = h ^ h >>> 16n
 }
 
 let rec hashOne = (val, depth) => {
@@ -83,10 +90,14 @@ let rec hashOne = (val, depth) => {
     void
   } else if ((val & Tags._GRAIN_NUMBER_TAG_MASK) != 0n) {
     hash32(val)
-  } else if ((val & Tags._GRAIN_GENERIC_TAG_MASK) == Tags._GRAIN_GENERIC_HEAP_TAG_TYPE) {
+  } else if (
+    (val & Tags._GRAIN_GENERIC_TAG_MASK) == Tags._GRAIN_GENERIC_HEAP_TAG_TYPE
+  ) {
     let heapPtr = val
     match (WasmI32.load(heapPtr, 0n)) {
-      t when t == Tags._GRAIN_STRING_HEAP_TAG || t == Tags._GRAIN_BYTES_HEAP_TAG => {
+      t when (
+        t == Tags._GRAIN_STRING_HEAP_TAG || t == Tags._GRAIN_BYTES_HEAP_TAG
+      ) => {
         let length = WasmI32.load(heapPtr, 4n)
         let extra = length % 4n
         let l = length - extra
@@ -191,12 +202,12 @@ let rec hashOne = (val, depth) => {
           },
           _ => {
             hash32(heapPtr)
-          }
+          },
         }
       },
       _ => {
         hash32(heapPtr)
-      }
+      },
     }
   } else if (val == WasmI32.fromGrain(true)) {
     hash32(val)
@@ -208,14 +219,30 @@ let rec hashOne = (val, depth) => {
     hash32(val)
   }
 }
+/**
+ * @section Values: Functions for hashing.
+ */
 
-export let hash = (a) => {
+/**
+ * A generic hash function that produces an integer from any value. If `a == b` then `Hash.hash(a) == Hash.hash(b)`.
+ *
+ * @param anything: The value to hash
+ * @returns A hash for the given value
+ *
+ * @since v0.1.0
+ */
+export let rec hash = anything => {
   h = seed
 
-  hashOne(WasmI32.fromGrain(a), 0n)
+  hashOne(WasmI32.fromGrain(anything), 0n)
   finalize(0n)
 
   // Tag the number on the way out.
   // Since Grain has proper modulus, negative numbers are okay.
-  tagSimpleNumber(h)
+  let result = tagSimpleNumber(h)
+
+  Memory.decRef(WasmI32.fromGrain(hash))
+  Memory.decRef(WasmI32.fromGrain(anything))
+
+  result
 }

package/hash.md

@@ -0,0 +1,44 @@
+---
+title: Hash
+---
+
+Utilities for hashing any value.
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.1.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+import Hash from "hash"
+```
+
+## Values
+
+Functions for hashing.
+
+### Hash.**hash**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.1.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+hash : a -> Number
+```
+
+A generic hash function that produces an integer from any value. If `a == b` then `Hash.hash(a) == Hash.hash(b)`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`anything`|`a`|The value to hash|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|A hash for the given value|
+