@grain/stdlib 0.5.13 → 0.6.0

package/float64.md

@@ -10,12 +10,28 @@ No other changes yet.
 </details>
 
 ```grain
-import Float64 from "float64"
+from "float64" include Float64
 ```
 
-## Constants
+```grain
+5.0d
+```
+
+```grain
+-5.0d
+```
+
+```grain
+Infinityd
+```
+
+```grain
+NaNd
+```
+
+## Values
 
-Float64 constant values.
+Functions and constants included in the Float64 module.
 
 ### Float64.**infinity**
 
@@ -29,6 +45,7 @@ infinity : Float64
 ```
 
 Infinity represented as a Float64 value.
+This is an alternative to the `Infinityd` literal.
 
 ### Float64.**nan**
 
@@ -42,6 +59,7 @@ nan : Float64
 ```
 
 NaN (Not a Number) represented as a Float64 value.
+This is an alternative to the `NaNd` literal.
 
 ### Float64.**pi**
 
@@ -82,10 +100,6 @@ e : Float64
 
 Euler's number represented as a Float64 value.
 
-## Conversions
-
-Functions for converting between Numbers and the Float64 type.
-
 ### Float64.**fromNumber**
 
 <details disabled>
@@ -94,7 +108,7 @@ No other changes yet.
 </details>
 
 ```grain
-fromNumber : Number -> Float64
+fromNumber : (number: Number) => Float64
 ```
 
 Converts a Number to a Float64.
@@ -119,7 +133,7 @@ No other changes yet.
 </details>
 
 ```grain
-toNumber : Float64 -> Number
+toNumber : (float: Float64) => Number
 ```
 
 Converts a Float64 to a Number.
@@ -136,19 +150,22 @@ Returns:
 |----|-----------|
 |`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.
+### Float64.**(+)**
+
+<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 : (Float64, Float64) -> Float64
+(+) : (x: Float64, y: Float64) => Float64
 ```
 
 Computes the sum of its operands.
@@ -166,15 +183,29 @@ Returns:
 |----|-----------|
 |`Float64`|The sum of the two operands|
 
-### Float64.**sub**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+```grain
+use Float64.{ (+) }
+assert 1.0d + 1.0d == 2.0d
+```
+
+### Float64.**(-)**
+
+<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 : (Float64, Float64) -> Float64
+(-) : (x: Float64, y: Float64) => Float64
 ```
 
 Computes the difference of its operands.
@@ -192,15 +223,29 @@ Returns:
 |----|-----------|
 |`Float64`|The difference of the two operands|
 
-### Float64.**mul**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+```grain
+use Float64.{ (-) }
+assert 5.0d - 4.0d == 1.0d
+```
+
+### Float64.**(*)**
+
+<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 : (Float64, Float64) -> Float64
+(*) : (x: Float64, y: Float64) => Float64
 ```
 
 Computes the product of its operands.
@@ -218,15 +263,29 @@ Returns:
 |----|-----------|
 |`Float64`|The product of the two operands|
 
-### Float64.**div**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+```grain
+use Float64.{ (*) }
+assert -5.0d * 4.0d == -20.0d
+```
+
+### Float64.**(/)**
+
+<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 : (Float64, Float64) -> Float64
+(/) : (x: Float64, y: Float64) => Float64
 ```
 
 Computes the quotient of its operands.
@@ -244,19 +303,29 @@ Returns:
 |----|-----------|
 |`Float64`|The quotient of the two operands|
 
-## Comparisons
-
-Functions for comparing Float64 values.
+Examples:
 
-### Float64.**lt**
+```grain
+use Float64.{ (/) }
+assert 25.0d / 4.0d == 6.25d
+```
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+### Float64.**(<)**
+
+<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 : (Float64, Float64) -> Bool
+(<) : (x: Float64, y: Float64) => 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|
 
-### Float64.**gt**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+```grain
+use Float64.{ (<) }
+assert -5.0d < 5.0d
+```
+
+### Float64.**(>)**
+
+<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 : (Float64, Float64) -> Bool
+(>) : (x: Float64, y: Float64) => 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|
 
-### Float64.**lte**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+```grain
+use Float64.{ (>) }
+assert 6.0d > 5.0d
+```
+
+### Float64.**(<=)**
+
+<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 : (Float64, Float64) -> Bool
+(<=) : (x: Float64, y: Float64) => 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|
 
-### Float64.**gte**
+Examples:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+```grain
+use Float64.{ (<=) }
+assert 1.0d <= 2.0d
+```
+
+```grain
+use Float64.{ (<=) }
+assert 2.0d <= 2.0d
+```
+
+### Float64.**(>=)**
+
+<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 : (Float64, Float64) -> Bool
+(>=) : (x: Float64, y: Float64) => 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 Float64.{ (>=) }
+assert 5.0d >= 2.0d
+```
+
+```grain
+use Float64.{ (>=) }
+assert -1.0d >= -1.0d
+```
+

package/hash.gr

@@ -1,39 +1,46 @@
 /**
- * @module Hash: Utilities for hashing any value.
- * @example import Hash from "hash"
+ * Utilities for hashing any value.
+ *
+ * @example from "hash" include Hash
+ *
+ * @example Hash.hash(1)
+ * @example Hash.hash("Hello World")
  *
  * @since v0.1.0
  */
+module Hash
 
 /**
   This module implements MurmurHash3 for Grain data types.
   https://en.wikipedia.org/wiki/MurmurHash
 */
-
-import WasmI32, {
-  add as (+),
-  sub as (-),
-  mul as (*),
+from "runtime/unsafe/wasmi32" include WasmI32
+use WasmI32.{
+  (+),
+  (-),
+  (*),
   remU as (%),
-  xor as (^),
-  shrU as (>>>),
-  shl as (<<),
-  and as (&),
-  or as (|),
-  eq as (==),
-  ne as (!=),
+  (^),
+  (>>>),
+  (<<),
+  (&),
+  (|),
+  (==),
+  (!=),
   gtU as (>),
   ltU as (<),
-} from "runtime/unsafe/wasmi32"
-import WasmI64 from "runtime/unsafe/wasmi64"
-import Tags from "runtime/unsafe/tags"
+}
+from "runtime/unsafe/wasmi64" include WasmI64
+from "runtime/unsafe/tags" include Tags
 
-import { tagSimpleNumber } from "runtime/dataStructures"
-import { coerceNumberToWasmI32 } from "runtime/numbers"
-import BI from "runtime/bigint"
+from "runtime/dataStructures" include DataStructures
+use DataStructures.{ tagSimpleNumber }
+from "runtime/numbers" include Numbers
+use Numbers.{ coerceNumberToWasmI32 }
+from "runtime/bigint" include Bigint as BI
 
-import Random from "sys/random"
-import Result from "result"
+from "wasi/random" include Random
+from "result" include Result
 
 @unsafe
 let seed = {
@@ -73,9 +80,10 @@ let hash32 = k => {
 
 @unsafe
 let hash64 = k => {
+  use WasmI64.{ (>>>) }
   // convenience function for hashing 64-bit values
   hash32(WasmI32.wrapI64(k))
-  hash32(WasmI32.wrapI64(WasmI64.shrU(k, 32N)))
+  hash32(WasmI32.wrapI64(k >>> 32N))
 }
 
 @unsafe
@@ -107,13 +115,12 @@ let rec hashOne = (val, depth) => {
   } 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
+    (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
@@ -182,9 +189,6 @@ let rec hashOne = (val, depth) => {
       t when t == Tags._GRAIN_BOXED_NUM_HEAP_TAG => {
         let tag = WasmI32.load(heapPtr, 4n)
         match (tag) {
-          t when t == Tags._GRAIN_INT32_BOXED_NUM_TAG => {
-            hash32(WasmI32.load(heapPtr, 8n))
-          },
           t when t == Tags._GRAIN_INT64_BOXED_NUM_TAG => {
             hash32(WasmI32.load(heapPtr, 8n))
             hash32(WasmI32.load(heapPtr, 12n))
@@ -198,9 +202,6 @@ let rec hashOne = (val, depth) => {
               hash64(BI.getLimb(heapPtr, i))
             }
           },
-          t when t == Tags._GRAIN_FLOAT32_BOXED_NUM_TAG => {
-            hash32(WasmI32.load(heapPtr, 8n))
-          },
           t when t == Tags._GRAIN_FLOAT64_BOXED_NUM_TAG => {
             hash32(WasmI32.load(heapPtr, 8n))
             hash32(WasmI32.load(heapPtr, 12n))
@@ -214,6 +215,15 @@ let rec hashOne = (val, depth) => {
           },
         }
       },
+      t when t == Tags._GRAIN_INT32_HEAP_TAG ||
+        t == Tags._GRAIN_FLOAT32_HEAP_TAG ||
+        t == Tags._GRAIN_UINT32_HEAP_TAG => {
+        hash32(WasmI32.load(heapPtr, 4n))
+      },
+      t when t == Tags._GRAIN_UINT64_HEAP_TAG => {
+        hash32(WasmI32.load(heapPtr, 8n))
+        hash32(WasmI32.load(heapPtr, 12n))
+      },
       _ => {
         hash32(heapPtr)
       },
@@ -223,9 +233,6 @@ let rec hashOne = (val, depth) => {
     hash32(val)
   }
 }
-/**
- * @section Values: Functions for hashing.
- */
 
 /**
  * A generic hash function that produces an integer from any value. If `a == b` then `Hash.hash(a) == Hash.hash(b)`.
@@ -233,10 +240,13 @@ let rec hashOne = (val, depth) => {
  * @param anything: The value to hash
  * @returns A hash for the given value
  *
+ * @example assert Hash.hash(1) == Hash.hash(1)
+ * @example assert Hash.hash("Hello World") == Hash.hash("Hello World")
+ *
  * @since v0.1.0
  */
 @unsafe
-export let hash = anything => {
+provide let hash = anything => {
   h = seed
 
   hashOne(WasmI32.fromGrain(anything), 0n)

package/hash.md

@@ -10,12 +10,20 @@ No other changes yet.
 </details>
 
 ```grain
-import Hash from "hash"
+from "hash" include Hash
+```
+
+```grain
+Hash.hash(1)
+```
+
+```grain
+Hash.hash("Hello World")
 ```
 
 ## Values
 
-Functions for hashing.
+Functions and constants included in the Hash module.
 
 ### Hash.**hash**
 
@@ -25,7 +33,7 @@ No other changes yet.
 </details>
 
 ```grain
-hash : a -> Number
+hash : (anything: a) => Number
 ```
 
 A generic hash function that produces an integer from any value. If `a == b` then `Hash.hash(a) == Hash.hash(b)`.
@@ -42,3 +50,13 @@ Returns:
 |----|-----------|
 |`Number`|A hash for the given value|
 
+Examples:
+
+```grain
+assert Hash.hash(1) == Hash.hash(1)
+```
+
+```grain
+assert Hash.hash("Hello World") == Hash.hash("Hello World")
+```
+