@grain/stdlib 0.5.4 → 0.5.5

package/char.gr

@@ -4,7 +4,7 @@
  * 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
  */
 
@@ -26,23 +26,23 @@ exception MalformedUtf8
 
 /**
  * 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
 
 /**
  * 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 => {
@@ -53,10 +53,10 @@ export let isValid = charCode => {
 
 /**
  * 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
  */
 @unsafe
@@ -70,11 +70,12 @@ export let code = (char: 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
- * 
+ *
+ * @throws InvalidArgument(String): When the Unicode scalar value is invalid
+ *
  * @since 0.3.0
  */
 @unsafe
@@ -101,11 +102,12 @@ export let fromCode = (usv: Number) => {
 
 /**
  * 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
- * 
+ *
+ * @throws Failure(String): When the input character is the maximum valid Unicode scalar value
+ *
  * @since 0.3.0
  */
 export let succ = char => {
@@ -121,11 +123,12 @@ export let succ = char => {
 
 /**
  * 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
- * 
+ *
+ * @throws Failure(String): When the input character is the minimum valid Unicode scalar value
+ *
  * @since 0.3.0
  */
 export let pred = char => {
@@ -141,10 +144,10 @@ export let pred = char => {
 
 /**
  * Converts the given character to a string.
- * 
+ *
  * @param char: The character to convert
  * @returns A string containing the given character
- * 
+ *
  * @since 0.3.0
  */
 @unsafe

package/char.md

@@ -107,7 +107,6 @@ fromCode : Number -> Char
 ```
 
 Creates a character from the given Unicode scalar value.
-Throws an exception if the Unicode scalar value is invalid.
 
 Parameters:
 
@@ -121,6 +120,12 @@ Returns:
 |----|-----------|
 |`Char`|The character for the given Unicode scalar value|
 
+Throws:
+
+`InvalidArgument(String)`
+
+* When the Unicode scalar value is invalid
+
 ### Char.**succ**
 
 <details disabled>
@@ -133,7 +138,6 @@ 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:
 
@@ -147,6 +151,12 @@ Returns:
 |----|-----------|
 |`Char`|The next valid character by Unicode scalar value|
 
+Throws:
+
+`Failure(String)`
+
+* When the input character is the maximum valid Unicode scalar value
+
 ### Char.**pred**
 
 <details disabled>
@@ -159,7 +169,6 @@ 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:
 
@@ -173,6 +182,12 @@ Returns:
 |----|-----------|
 |`Char`|The previous valid character by Unicode scalar value|
 
+Throws:
+
+`Failure(String)`
+
+* When the input character is the minimum valid Unicode scalar value
+
 ### Char.**toString**
 
 <details disabled>

package/immutablepriorityqueue.gr

@@ -46,7 +46,7 @@ record ImmutablePriorityQueue<a> {
 
 /**
  * An empty priority queue with the default `compare` comparator.
- * 
+ *
  * @since v0.5.4
  */
 export let empty = {
@@ -59,10 +59,10 @@ export let empty = {
  * determine priority of elements. The comparator function takes two elements
  * and must return 0 if both share priority, a positive number if the first
  * has greater priority, and a negative number if the first has less priority.
- * 
+ *
  * @param comp: The comparator function used to indicate priority order
  * @returns An empty priority queue
- * 
+ *
  * @example ImmutablePriorityQueue.make(compare) // creates a min priority queue of numbers using the compare pervasive
  * @example ImmutablePriorityQueue.make((a, b) => String.length(b) - String.length(a)) // creates a priority queue by string length (longest to shortest)
  *
@@ -74,7 +74,7 @@ export let make = comp => {
 
 /**
  * Gets the number of elements in a priority queue.
- * 
+ *
  * @param pq: The priority queue to inspect
  * @returns The number of elements in the priority queue
  *
@@ -86,7 +86,7 @@ export let size = pq => {
 
 /**
  * Determines if the priority queue contains no elements.
- * 
+ *
  * @param pq: The priority queue to check
  * @returns `true` if the priority queue is empty and `false` otherwise
  *
@@ -131,7 +131,7 @@ let skewInsert = (comp, val, pq) => {
 
 /**
  * Produces a new priority queue by inserting the given element into the given priority queue.
- * 
+ *
  * @param val: The value to add into the priority queue
  * @param pq: The priority queue
  * @returns A new priority queue with the given element inserted
@@ -156,7 +156,7 @@ export let push = (val, pq) => {
 /**
  * Retrieves the highest priority element in the priority queue. It is not
  * removed from the queue.
- * 
+ *
  * @param pq: The priority queue to inspect
  * @returns `Some(value)` containing the highest priority element or `None` if the priority queue is empty
  *
@@ -227,7 +227,7 @@ let merge = (comp, pq1, pq2) =>
 let rec separateHighestPriority = (comp, pq) => {
   match (pq) {
     // empty list case should never happen; this is here just to satisfy the compiler
-    [] => fail "getHighestPriority called with empty PQ",
+    [] => fail "Impossible: getHighestPriority called with empty PQ",
     [node] => (node, []),
     [node, ...rest] => {
       let (currMinNode, currNonMinNodes) = separateHighestPriority(comp, rest)
@@ -267,7 +267,7 @@ let withoutHighestPriority = (comp, pq) => {
 let rec findHighestPriority = (comp, pq) => {
   match (pq) {
     // empty list case should never happen; this is here just to satisfy the compiler
-    [] => fail "findHighestPriority with empty PQ",
+    [] => fail "Impossible: findHighestPriority with empty PQ",
     [node] => node.val,
     [node, ...rest] => {
       let currMin = findHighestPriority(comp, rest)
@@ -280,7 +280,7 @@ let rec findHighestPriority = (comp, pq) => {
  * Produces a new priority queue without the highest priority element in the
  * given priority queue. If the input priority queue is empty, this function will
  * return it.
- * 
+ *
  * @param pq: The priority queue
  * @returns A new priority queue without the highest priority element
  *
@@ -309,7 +309,7 @@ export let pop = pq => {
 
 /**
  * Produces a list of all elements in the priority queue in priority order.
- * 
+ *
  * @param pq: The priority queue to drain
  * @returns A list of all elements in the priority in priority order
  *
@@ -331,7 +331,7 @@ export let drain = pq => {
  * elements. The comparator function takes two elements and must return 0 if
  * both share priority, a positive number if the first has greater priority,
  * and a negative number if the first has less priority.
- * 
+ *
  * @param list: A list of values used to initialize the priority queue
  * @param comp: A comparator function used to assign priority to elements
  * @returns A priority queue containing the elements from the list
@@ -348,7 +348,7 @@ export let fromList = (list, comp) => {
  * elements. The comparator function takes two elements and must return 0 if
  * both share priority, a positive number if the first has greater priority,
  * and a negative number if the first has less priority.
- * 
+ *
  * @param array: An array of values used to initialize the priority queue
  * @param comp: A comparator function used to assign priority to elements
  * @returns A priority queue containing the elements from the array

package/int32.gr

@@ -1,7 +1,7 @@
 /**
  * @module Int32: Utilities for working with the Int32 type.
  * @example import Int32 from "int32"
- * 
+ *
  * @since v0.2.0
  */
 import WasmI32 from "runtime/unsafe/wasmi32"
@@ -23,7 +23,7 @@ import {
  *
  * @param number: The value to convert
  * @returns The Number represented as an Int32
- * 
+ *
  * @since v0.2.0
  */
 export fromNumber
@@ -33,7 +33,7 @@ export fromNumber
  *
  * @param value: The value to convert
  * @returns The Int32 represented as a Number
- * 
+ *
  * @since v0.2.0
  */
 export toNumber
@@ -47,7 +47,7 @@ export toNumber
  *
  * @param value: The value to increment
  * @returns The incremented value
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -62,7 +62,7 @@ export let incr = (value: Int32) => {
  *
  * @param value: The value to decrement
  * @returns The decremented value
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -78,7 +78,7 @@ export let decr = (value: Int32) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The sum of the two operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -95,7 +95,7 @@ export let add = (x: Int32, y: Int32) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The difference of the two operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -112,7 +112,7 @@ export let sub = (x: Int32, y: Int32) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The product of the two operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -129,7 +129,7 @@ export let mul = (x: Int32, y: Int32) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The quotient of its operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -146,7 +146,7 @@ export let div = (x: Int32, y: Int32) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The quotient of its operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -163,7 +163,7 @@ export let divU = (x: Int32, y: Int32) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The remainder of its operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -180,7 +180,7 @@ export let rem = (x: Int32, y: Int32) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The remainder of its operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -198,13 +198,15 @@ let abs = n => {
 }
 
 /**
- * Computes the remainder of the division of the first operand by the second. 
+ * Computes the remainder of the division of the first operand by the second.
  * The result will have the sign of the second operand.
  *
  * @param x: The first operand
  * @param y: The second operand
  * @returns The modulus of its operands
- * 
+ *
+ * @throws ModuloByZero: When `y` is zero
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -242,7 +244,7 @@ export let mod = (x: Int32, y: Int32) => {
  * @param value: The value to rotate
  * @param amount: The number of bits to rotate by
  * @returns The rotated value
- * 
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -259,7 +261,7 @@ export let rotl = (value: Int32, amount: Int32) => {
  * @param value: The value to rotate
  * @param amount: The number of bits to rotate by
  * @returns The rotated value
- * 
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -276,7 +278,7 @@ export let rotr = (value: Int32, amount: Int32) => {
  * @param value: The value to shift
  * @param amount: The number of bits to shift by
  * @returns The shifted value
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -293,7 +295,7 @@ export let shl = (value: Int32, amount: Int32) => {
  * @param value: The value to shift
  * @param amount: The amount to shift by
  * @returns The shifted value
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -310,7 +312,7 @@ export let shr = (value: Int32, amount: Int32) => {
  * @param value: The value to shift
  * @param amount: The amount to shift by
  * @returns The shifted value
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -331,7 +333,7 @@ export let shrU = (value: Int32, amount: Int32) => {
  * @param x: The first value
  * @param y: The second value
  * @returns `true` if the first value is equal to the second value or `false` otherwise
- * 
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -347,7 +349,7 @@ export let eq = (x: Int32, y: Int32) => {
  * @param x: The first value
  * @param y: The second value
  * @returns `true` if the first value is not equal to the second value or `false` otherwise
- * 
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -362,7 +364,7 @@ export let ne = (x: Int32, y: Int32) => {
  *
  * @param value: The value to inspect
  * @returns `true` if the first value is equal to zero or `false` otherwise
- * 
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -377,7 +379,7 @@ export let eqz = (value: Int32) => {
  * @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
  */
 @unsafe
@@ -397,7 +399,7 @@ export let lt = (x: Int32, y: Int32) => {
  * @since v0.5.0
  */
 @unsafe
-export let rec ltU = (x: Int32, y: Int32) => {
+export let ltU = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   WasmI32.ltU(xv, yv)
@@ -409,7 +411,7 @@ export let rec ltU = (x: Int32, y: Int32) => {
  * @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
  */
 @unsafe
@@ -429,7 +431,7 @@ export let gt = (x: Int32, y: Int32) => {
  * @since v0.5.0
  */
 @unsafe
-export let rec gtU = (x: Int32, y: Int32) => {
+export let gtU = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   WasmI32.gtU(xv, yv)
@@ -441,7 +443,7 @@ export let rec gtU = (x: Int32, y: Int32) => {
  * @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
  */
 @unsafe
@@ -461,7 +463,7 @@ export let lte = (x: Int32, y: Int32) => {
  * @since v0.5.0
  */
 @unsafe
-export let rec lteU = (x: Int32, y: Int32) => {
+export let lteU = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   WasmI32.leU(xv, yv)
@@ -473,7 +475,7 @@ export let rec lteU = (x: Int32, y: Int32) => {
  * @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
  */
 @unsafe
@@ -493,7 +495,7 @@ export let gte = (x: Int32, y: Int32) => {
  * @since v0.5.0
  */
 @unsafe
-export let rec gteU = (x: Int32, y: Int32) => {
+export let gteU = (x: Int32, y: Int32) => {
   let xv = WasmI32.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI32.load(WasmI32.fromGrain(y), 8n)
   WasmI32.geU(xv, yv)
@@ -508,7 +510,7 @@ export let rec gteU = (x: Int32, y: Int32) => {
  *
  * @param value: The given value
  * @returns Containing the inverted bits of the given value
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -524,7 +526,7 @@ export let lnot = (value: Int32) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of both operands are `1`
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -541,7 +543,7 @@ export let land = (x: Int32, y: Int32) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of either or both operands are `1`
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -558,7 +560,7 @@ export let lor = (x: Int32, y: Int32) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of either but not both operands are `1`
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -574,7 +576,7 @@ export let lxor = (x: Int32, y: Int32) => {
  *
  * @param value: The value to inspect
  * @returns The amount of leading zeros
- * 
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -589,7 +591,7 @@ export let clz = (value: Int32) => {
  *
  * @param value: The value to inspect
  * @returns The amount of trailing zeros
- * 
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -604,7 +606,7 @@ export let ctz = (value: Int32) => {
  *
  * @param value: The value to inspect
  * @returns The amount of 1-bits in its operand
- * 
+ *
  * @since v0.4.0
  */
 @unsafe

package/int32.md

@@ -330,6 +330,12 @@ Returns:
 |----|-----------|
 |`Int32`|The modulus of its operands|
 
+Throws:
+
+`ModuloByZero`
+
+* When `y` is zero
+
 ## Bitwise operations
 
 Functions for operating on bits of Int32 values.