@grain/stdlib 0.4.1 → 0.4.5

package/char.gr

@@ -1,35 +1,68 @@
+/**
+ * @module Char: Utilities for working with the Char type.
+ *
+ * The Char type represents a single [Unicode scalar value](https://www.unicode.org/glossary/#unicode_scalar_value).
+ *
+ * @example import Char from "char"
+ * 
+ * @since 0.3.0
+ */
+
 import WasmI32 from "runtime/unsafe/wasmi32"
 import Memory from "runtime/unsafe/memory"
 import Errors from "runtime/unsafe/errors"
-import { tagSimpleNumber, allocateChar, allocateString } from "runtime/dataStructures"
-
-export *
+import {
+  tagSimpleNumber,
+  allocateChar,
+  allocateString,
+} from "runtime/dataStructures"
 
 exception MalformedUtf8
 
-// The minimum value of Unicode characters
-// Number
-let min = 0x0000
+/**
+ * @section Values: Functions and constants included in the Char module.
+ */
 
-// The maximum value of Unicode characters
-// Number
-let max = 0x10FFFF
+/**
+ * The minimum valid Unicode scalar value.
+ * 
+ * @since 0.3.0
+ */
+export let min = 0x0000
+/**
+ * The maximum valid Unicode scalar value.
+ * 
+ * @since 0.3.0
+ */
+export let max = 0x10FFFF
 
-// Returns true if the given number is a valid Unicode scalar value.
-// @param n: Number - the value to check
-// @returns Bool
-let isValid = (n) => {
-  n >= min && (n <= 0xD7FF || n >= 0xE000) && n <= max
+/**
+ * Determines whether the given character code is a valid Unicode scalar value.
+ * 
+ * @param charCode: The number to check
+ * @returns `true` if the number refers to a valid Unicode scalar value or `false` otherwise
+ * 
+ * @since 0.3.0
+ */
+export let isValid = charCode => {
+  charCode >= min &&
+  (charCode <= 0xD7FF || charCode >= 0xE000) &&
+  charCode <= max
 }
 
-// Returns the Unicode code point for the character
-// @param char: Char - the input character
-// @returns Number
+/**
+ * Determines the Unicode scalar value for a character.
+ * 
+ * @param char: The character
+ * @returns The Unicode scalar value for the given character
+ * 
+ * @since 0.3.0
+ */
 @disableGC
-let code = (c: Char) => {
+export let rec code = (char: Char) => {
   // Algorithm from https://encoding.spec.whatwg.org/#utf-8-decoder
 
-  let c = WasmI32.fromGrain(c)
+  let char = WasmI32.fromGrain(char)
 
   let (+) = WasmI32.add
   let (==) = WasmI32.eq
@@ -50,7 +83,7 @@ let code = (c: Char) => {
   let mut result = 0n
 
   while (true) {
-    let byte = WasmI32.load8U(c + offset, 4n)
+    let byte = WasmI32.load8U(char + offset, 4n)
     offset += 1n
     if (bytesNeeded == 0n) {
       if (byte >= 0x00n && byte <= 0x7Fn) {
@@ -79,21 +112,30 @@ let code = (c: Char) => {
     }
     lowerBoundary = 0x80n
     upperBoundary = 0xBFn
-    codePoint = (codePoint << 6n) | (byte & 0x3Fn)
+    codePoint = codePoint << 6n | byte & 0x3Fn
     bytesSeen += 1n
     if (bytesSeen == bytesNeeded) {
       result = codePoint
       break
     }
   }
+
+  Memory.decRef(char)
+  Memory.decRef(WasmI32.fromGrain(code))
   tagSimpleNumber(result)
 }
 
-// Returns the Char for the given code point. Fails if the code point is invalid.
-// @param codePoint: Number - the Unicode code point
-// @returns Char
+/**
+ * Creates a character from the given Unicode scalar value.
+ * Throws an exception if the Unicode scalar value is invalid.
+ * 
+ * @param usv: The Unicode scalar value
+ * @returns The character for the given Unicode scalar value
+ * 
+ * @since 0.3.0
+ */
 @disableGC
-let fromCode = (code: Number) => {
+export let rec fromCode = (usv: Number) => {
   // Algorithm from https://encoding.spec.whatwg.org/#utf-8-encoder
 
   let (+) = WasmI32.add
@@ -107,23 +149,23 @@ let fromCode = (code: Number) => {
   let (&) = WasmI32.and
   let (|) = WasmI32.or
 
-  let code = WasmI32.fromGrain(code)
-  if ((code & 1n) == 0n) {
+  let usv = WasmI32.fromGrain(usv)
+  if ((usv & 1n) == 0n) {
     throw InvalidArgument("Invalid character code")
   }
 
-  let code = code >>> 1n
-  if (code < 0x80n) {
+  let usv = usv >>> 1n
+  let result = if (usv < 0x80n) {
     let char = allocateChar()
-    WasmI32.store8(char, code, 4n)
+    WasmI32.store8(char, usv, 4n)
     WasmI32.toGrain(char): Char
   } else {
     let mut count = 0n
     let mut offset = 0n
-    if (code <= 0x07FFn) {
+    if (usv <= 0x07FFn) {
       count = 1n
       offset = 0xC0n
-    } else if (code <= 0xFFFFn) {
+    } else if (usv <= 0xFFFFn) {
       count = 2n
       offset = 0xE0n
     } else {
@@ -131,27 +173,38 @@ let fromCode = (code: Number) => {
       offset = 0xF0n
     }
     let char = allocateChar()
-    WasmI32.store8(char, (code >>> (6n * count)) + offset, 4n)
+    WasmI32.store8(char, (usv >>> 6n * count) + offset, 4n)
 
     let mut n = 0n
     while (count > 0n) {
       n += 1n
-      let temp = code >>> (6n * (count - 1n))
-      WasmI32.store8(char + n, 0x80n | (temp & 0x3Fn), 4n)
+      let temp = usv >>> 6n * (count - 1n)
+      WasmI32.store8(char + n, 0x80n | temp & 0x3Fn, 4n)
       count -= 1n
     }
 
     WasmI32.toGrain(char): Char
   }
+
+  // We've asserted that the original `code` was a stack allocated number so
+  // no need to decRef it
+  Memory.decRef(WasmI32.fromGrain(fromCode))
+  result
 }
 
-// Returns the next valid Unicode character by code point. Fails if the input character is U+10FFFF.
-// @param char: Char - the input character
-// @returns Char
-let succ = (c) => {
-  let codePoint = code(c)
+/**
+ * Returns the next valid character by Unicode scalar value.
+ * Throws if the input character is the max valid Unicode scalar value.
+ * 
+ * @param char: The character
+ * @returns The next valid character by Unicode scalar value
+ * 
+ * @since 0.3.0
+ */
+export let succ = char => {
+  let codePoint = code(char)
   if (codePoint == max) {
-    fail "no valid Unicode code point past U+10FFF"
+    fail "no valid Unicode scalar value past U+10FFF"
   } else if (codePoint == 0xD7FF) {
     fromCode(0xE000)
   } else {
@@ -159,13 +212,19 @@ let succ = (c) => {
   }
 }
 
-// Returns the previous valid Unicode character by code point. Fails if the input character is U+0000.
-// @param char: Char - the input character
-// @returns Char
-let pred = (c) => {
-  let codePoint = code(c)
+/**
+ * Returns the previous valid character by Unicode scalar value.
+ * Throws if the input character is the min valid Unicode scalar value.
+ * 
+ * @param char: The character
+ * @returns The previous valid character by Unicode scalar value
+ * 
+ * @since 0.3.0
+ */
+export let pred = char => {
+  let codePoint = code(char)
   if (codePoint == min) {
-    fail "no valid Unicode code point below U+0000"
+    fail "no valid Unicode scalar value below U+0000"
   } else if (codePoint == 0xE000) {
     fromCode(0xD7FF)
   } else {
@@ -173,17 +232,22 @@ let pred = (c) => {
   }
 }
 
-// Creates a new string containing the character.
-// @param char: Char - the character to convert
-// @returns String
+/**
+ * Converts the given character to a string.
+ * 
+ * @param char: The character to convert
+ * @returns A string containing the given character
+ * 
+ * @since 0.3.0
+ */
 @disableGC
-export let rec toString = (c: Char) => {
+export let rec toString = (char: Char) => {
   let (+) = WasmI32.add
   let (&) = WasmI32.and
   let (==) = WasmI32.eq
 
-  let c = WasmI32.fromGrain(c)
-  let byte = WasmI32.load8U(c, 4n)
+  let char = WasmI32.fromGrain(char)
+  let byte = WasmI32.load8U(char, 4n)
   let n = if ((byte & 0x80n) == 0x00n) {
     1n
   } else if ((byte & 0xF0n) == 0xF0n) {
@@ -194,9 +258,9 @@ export let rec toString = (c: Char) => {
     2n
   }
   let str = allocateString(n)
-  Memory.copy(str + 8n, c + 4n, n)
+  Memory.copy(str + 8n, char + 4n, n)
   let ret = WasmI32.toGrain(str): String
-  Memory.decRef(WasmI32.fromGrain(c))
+  Memory.decRef(WasmI32.fromGrain(char))
   Memory.decRef(WasmI32.fromGrain(toString))
   ret
 }

package/char.md

@@ -0,0 +1,200 @@
+---
+title: Char
+---
+
+Utilities for working with the Char type.
+
+The Char type represents a single [Unicode scalar value](https://www.unicode.org/glossary/#unicode_scalar_value).
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+import Char from "char"
+```
+
+## Values
+
+Functions and constants included in the Char module.
+
+### Char.**min**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+min : Number
+```
+
+The minimum valid Unicode scalar value.
+
+### Char.**max**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+max : Number
+```
+
+The maximum valid Unicode scalar value.
+
+### Char.**isValid**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isValid : Number -> Bool
+```
+
+Determines whether the given character code is a valid Unicode scalar value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`charCode`|`Number`|The number to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the number refers to a valid Unicode scalar value or `false` otherwise|
+
+### Char.**code**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+code : Char -> Number
+```
+
+Determines the Unicode scalar value for a character.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`char`|`Char`|The character|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The Unicode scalar value for the given character|
+
+### Char.**fromCode**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromCode : Number -> Char
+```
+
+Creates a character from the given Unicode scalar value.
+Throws an exception if the Unicode scalar value is invalid.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`usv`|`Number`|The Unicode scalar value|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Char`|The character for the given Unicode scalar value|
+
+### Char.**succ**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+succ : Char -> Char
+```
+
+Returns the next valid character by Unicode scalar value.
+Throws if the input character is the max valid Unicode scalar value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`char`|`Char`|The character|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Char`|The next valid character by Unicode scalar value|
+
+### Char.**pred**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+pred : Char -> Char
+```
+
+Returns the previous valid character by Unicode scalar value.
+Throws if the input character is the min valid Unicode scalar value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`char`|`Char`|The character|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Char`|The previous valid character by Unicode scalar value|
+
+### Char.**toString**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toString : Char -> String
+```
+
+Converts the given character to a string.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`char`|`Char`|The character to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`String`|A string containing the given character|
+

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|
+