@grain/stdlib 0.4.2 → 0.4.6

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 rec 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 rec 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,7 +112,7 @@ let rec code = (c: Char) => {
     }
     lowerBoundary = 0x80n
     upperBoundary = 0xBFn
-    codePoint = (codePoint << 6n) | (byte & 0x3Fn)
+    codePoint = codePoint << 6n | byte & 0x3Fn
     bytesSeen += 1n
     if (bytesSeen == bytesNeeded) {
       result = codePoint
@@ -87,16 +120,22 @@ let rec code = (c: Char) => {
     }
   }
 
-  Memory.decRef(c)
+  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 rec fromCode = (code: Number) => {
+export let rec fromCode = (usv: Number) => {
   // Algorithm from https://encoding.spec.whatwg.org/#utf-8-encoder
 
   let (+) = WasmI32.add
@@ -110,23 +149,23 @@ let rec 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
-  let result = 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 {
@@ -134,13 +173,13 @@ let rec 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
     }
 
@@ -153,13 +192,19 @@ let rec fromCode = (code: Number) => {
   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 {
@@ -167,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 {
@@ -181,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) {
@@ -202,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/float32.gr

@@ -1,3 +1,9 @@
+/**
+ * @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"
@@ -10,10 +16,43 @@ import {
   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
 
+/**
+ * @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
+ */
 @disableGC
 export let rec add = (x: Float32, y: Float32) => {
   let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
@@ -26,6 +65,15 @@ export let rec add = (x: Float32, y: Float32) => {
   ret
 }
 
+/**
+ * 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
+ */
 @disableGC
 export let rec sub = (x: Float32, y: Float32) => {
   let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
@@ -38,6 +86,15 @@ export let rec sub = (x: Float32, y: Float32) => {
   ret
 }
 
+/**
+ * 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
+ */
 @disableGC
 export let rec mul = (x: Float32, y: Float32) => {
   let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
@@ -50,6 +107,15 @@ export let rec mul = (x: Float32, y: Float32) => {
   ret
 }
 
+/**
+ * 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
+ */
 @disableGC
 export let rec div = (x: Float32, y: Float32) => {
   let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
@@ -62,8 +128,19 @@ export let rec div = (x: Float32, y: Float32) => {
   ret
 }
 
-
-// Float32 comparisons
+/**
+ * @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
+ */
 @disableGC
 export let rec lt = (x: Float32, y: Float32) => {
   let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
@@ -75,6 +152,15 @@ export let rec lt = (x: Float32, y: Float32) => {
   ret
 }
 
+/**
+ * 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
+ */
 @disableGC
 export let rec gt = (x: Float32, y: Float32) => {
   let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
@@ -86,6 +172,15 @@ export let rec gt = (x: Float32, y: Float32) => {
   ret
 }
 
+/**
+ * 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
+ */
 @disableGC
 export let rec lte = (x: Float32, y: Float32) => {
   let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
@@ -97,6 +192,15 @@ export let rec lte = (x: Float32, y: Float32) => {
   ret
 }
 
+/**
+ * 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
+ */
 @disableGC
 export let rec gte = (x: Float32, y: Float32) => {
   let xv = WasmF32.load(WasmI32.fromGrain(x), 8n)
@@ -108,7 +212,9 @@ export let rec gte = (x: Float32, y: Float32) => {
   ret
 }
 
-// floating-point constants:
+/**
+ * @section Constants: Float32 constant values.
+ */
 
 @disableGC
 let rec makeInfinity = () => {
@@ -118,6 +224,11 @@ let rec makeInfinity = () => {
   ret
 }
 
+/**
+ * Infinity represented as a Float32 value.
+ * 
+ * @since v0.4.0
+ */
 export let infinity = makeInfinity()
 
 @disableGC
@@ -128,4 +239,9 @@ let rec makeNaN = () => {
   ret
 }
 
+/**
+ * NaN (Not a Number) represented as a Float32 value.
+ * 
+ * @since v0.4.0
+ */
 export let nan = makeNaN()