@grain/stdlib 0.5.4 → 0.5.5

package/int64.gr

@@ -1,7 +1,7 @@
 /**
  * @module Int64: Utilities for working with the Int64 type.
  * @example import Int64 from "int64"
- * 
+ *
  * @since v0.2.0
  */
 import WasmI32 from "runtime/unsafe/wasmi32"
@@ -24,7 +24,7 @@ import {
  *
  * @param number: The value to convert
  * @returns The Number represented as an Int64
- * 
+ *
  * @since v0.2.0
  */
 export fromNumber
@@ -34,7 +34,7 @@ export fromNumber
  *
  * @param value: The value to convert
  * @returns The Int64 represented as a Number
- * 
+ *
  * @since v0.2.0
  */
 export toNumber
@@ -48,7 +48,7 @@ export toNumber
  *
  * @param value: The value to increment
  * @returns The incremented value
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -63,7 +63,7 @@ export let incr = (value: Int64) => {
  *
  * @param value: The value to decrement
  * @returns The decremented value
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -79,7 +79,7 @@ export let decr = (value: Int64) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The sum of the two operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -96,7 +96,7 @@ export let add = (x: Int64, y: Int64) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The difference of the two operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -113,7 +113,7 @@ export let sub = (x: Int64, y: Int64) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The product of the two operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -130,7 +130,7 @@ export let mul = (x: Int64, y: Int64) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The quotient of its operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -147,7 +147,7 @@ export let div = (x: Int64, y: Int64) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The quotient of its operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -164,7 +164,7 @@ export let divU = (x: Int64, y: Int64) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The remainder of its operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -181,7 +181,7 @@ export let rem = (x: Int64, y: Int64) => {
  * @param x: The first operand
  * @param y: The second operand
  * @returns The remainder of its operands
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -199,13 +199,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
@@ -243,7 +245,7 @@ export let mod = (x: Int64, y: Int64) => {
  * @param value: The value to rotate
  * @param amount: The number of bits to rotate by
  * @returns The rotated value
- * 
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -260,7 +262,7 @@ export let rotl = (value: Int64, amount: Int64) => {
  * @param value: The value to rotate
  * @param amount: The number of bits to rotate by
  * @returns The rotated value
- * 
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -277,7 +279,7 @@ export let rotr = (value: Int64, amount: Int64) => {
  * @param value: The value to shift
  * @param amount: The number of bits to shift by
  * @returns The shifted value
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -294,7 +296,7 @@ export let shl = (value: Int64, amount: Int64) => {
  * @param value: The value to shift
  * @param amount: The amount to shift by
  * @returns The shifted value
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -311,7 +313,7 @@ export let shr = (value: Int64, amount: Int64) => {
  * @param value: The value to shift
  * @param amount: The amount to shift by
  * @returns The shifted value
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -332,7 +334,7 @@ export let shrU = (value: Int64, amount: Int64) => {
  * @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
@@ -348,7 +350,7 @@ export let eq = (x: Int64, y: Int64) => {
  * @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
@@ -363,7 +365,7 @@ export let ne = (x: Int64, y: Int64) => {
  *
  * @param value: The value to inspect
  * @returns `true` if the first value is equal to zero or `false` otherwise
- * 
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -378,7 +380,7 @@ export let eqz = (value: Int64) => {
  * @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
@@ -398,7 +400,7 @@ export let lt = (x: Int64, y: Int64) => {
  * @since v0.5.0
  */
 @unsafe
-export let rec ltU = (x: Int64, y: Int64) => {
+export let ltU = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
   WasmI64.ltU(xv, yv)
@@ -410,7 +412,7 @@ export let rec ltU = (x: Int64, y: Int64) => {
  * @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
@@ -430,7 +432,7 @@ export let gt = (x: Int64, y: Int64) => {
  * @since v0.5.0
  */
 @unsafe
-export let rec gtU = (x: Int64, y: Int64) => {
+export let gtU = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
   WasmI64.gtU(xv, yv)
@@ -442,7 +444,7 @@ export let rec gtU = (x: Int64, y: Int64) => {
  * @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
@@ -462,7 +464,7 @@ export let lte = (x: Int64, y: Int64) => {
  * @since v0.5.0
  */
 @unsafe
-export let rec lteU = (x: Int64, y: Int64) => {
+export let lteU = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
   WasmI64.leU(xv, yv)
@@ -474,7 +476,7 @@ export let rec lteU = (x: Int64, y: Int64) => {
  * @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
@@ -494,7 +496,7 @@ export let gte = (x: Int64, y: Int64) => {
  * @since v0.5.0
  */
 @unsafe
-export let rec gteU = (x: Int64, y: Int64) => {
+export let gteU = (x: Int64, y: Int64) => {
   let xv = WasmI64.load(WasmI32.fromGrain(x), 8n)
   let yv = WasmI64.load(WasmI32.fromGrain(y), 8n)
   WasmI64.geU(xv, yv)
@@ -509,7 +511,7 @@ export let rec gteU = (x: Int64, y: Int64) => {
  *
  * @param value: The given value
  * @returns Containing the inverted bits of the given value
- * 
+ *
  * @since v0.2.0
  */
 @unsafe
@@ -525,7 +527,7 @@ export let lnot = (value: Int64) => {
  * @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
@@ -542,7 +544,7 @@ export let land = (x: Int64, y: Int64) => {
  * @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
@@ -559,7 +561,7 @@ export let lor = (x: Int64, y: Int64) => {
  * @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
@@ -575,7 +577,7 @@ export let lxor = (x: Int64, y: Int64) => {
  *
  * @param value: The value to inspect
  * @returns The amount of leading zeros
- * 
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -590,7 +592,7 @@ export let clz = (value: Int64) => {
  *
  * @param value: The value to inspect
  * @returns The amount of trailing zeros
- * 
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -605,7 +607,7 @@ export let ctz = (value: Int64) => {
  *
  * @param value: The value to inspect
  * @returns The amount of 1-bits in its operand
- * 
+ *
  * @since v0.4.0
  */
 @unsafe

package/int64.md

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

package/list.gr

@@ -230,10 +230,12 @@ export let rec flatMap = (fn, list) => {
  *
  * @since v0.1.0
  */
-export let every = (fn, list) => {
-  reduce((acc, value) => {
-    acc && fn(value)
-  }, true, list)
+export let rec every = (fn, list) => {
+  match (list) {
+    [] => true,
+    // The short-circuiting of `&&` makes this tail-recursive
+    [first, ...rest] => fn(first) && every(fn, rest),
+  }
 }
 
 /**
@@ -246,10 +248,12 @@ export let every = (fn, list) => {
  *
  * @since v0.1.0
  */
-export let some = (fn, list) => {
-  reduce((acc, value) => {
-    acc || fn(value)
-  }, false, list)
+export let rec some = (fn, list) => {
+  match (list) {
+    [] => false,
+    // The short-circuiting of `||` makes this tail-recursive
+    [first, ...rest] => fn(first) || some(fn, rest),
+  }
 }
 
 /**
@@ -433,13 +437,15 @@ export let rec flatten = list => {
 
 /**
  * Inserts a new value into a list at the specified index.
- * Fails if the index is out-of-bounds.
  *
  * @param value: The value to insert
  * @param index: The index to update
  * @param list: The list to update
  * @returns The new list
  *
+ * @throws Failure(String): When `index` is negative
+ * @throws Failure(String): When `index` is more than 0 and greater than the list size
+ *
  * @since v0.1.0
  */
 export let rec insert = (value, index, list) => {
@@ -477,12 +483,14 @@ export let count = (fn, list) => {
 
 /**
  * Split a list into two, with the first list containing the required number of elements.
- * Fails if the input list doesn't contain at least the required amount of elements.
  *
  * @param count: The number of elements required
  * @param list: The list to split
  * @returns Two lists where the first contains exactly the required amount of elements and the second contains any remaining elements
  *
+ * @throws Failure(String): When `count` is negative
+ * @throws Failure(String): When the list doesn't contain at least the required amount of elements
+ *
  * @since v0.1.0
  */
 export let part = (count, list) => {
@@ -509,14 +517,14 @@ export let part = (count, list) => {
  * If value is negative, list elements will be rotated by the
  * specified amount to the right. See examples.
  *
- * Fails if the input list doesn't contain at least the required amount of elements.
- *
  * @param count: The number of elements to rotate by
  * @param list: The list to be rotated
  *
  * @example List.rotate(2, [1, 2, 3, 4, 5]) // [3, 4, 5, 1, 2]
  * @example List.rotate(-1, [1, 2, 3, 4, 5]) // [5, 1, 2, 3, 4]
  *
+ * @throws Failure(String): When the list doesn't contain at least the required amount of elements
+ *
  * @since v0.1.0
  */
 export let rotate = (count, list) => {
@@ -552,7 +560,7 @@ export let unique = list => {
  * Produces a new list filled with tuples of elements from both given lists.
  * The first tuple will contain the first item of each list, the second tuple
  * will contain the second item of each list, and so on.
- * 
+ *
  * Calling this function with lists of different sizes will cause the returned
  * list to have the length of the smaller list.
  *
@@ -562,7 +570,7 @@ export let unique = list => {
  *
  * @example List.zip([1, 2, 3], [4, 5, 6]) // [(1, 4), (2, 5), (3, 6)]
  * @example List.zip([1, 2, 3], [4, 5]) // [(1, 4), (2, 5)]
- * 
+ *
  * @since v0.5.3
  */
 export let zip = (list1, list2) => {
@@ -582,7 +590,7 @@ export let zip = (list1, list2) => {
  * applying the function to the first elements of each list, the second element
  * will contain the result of applying the function to the second elements of
  * each list, and so on.
- * 
+ *
  * Calling this function with lists of different sizes will cause the returned
  * list to have the length of the smaller list.
  *
@@ -593,7 +601,7 @@ export let zip = (list1, list2) => {
  *
  * @example List.zipWith((a, b) => a + b, [1, 2, 3], [4, 5, 6]) // [5, 7, 9]
  * @example List.zipWith((a, b) => a * b, [1, 2, 3], [4, 5]) // [4, 10]
- * 
+ *
  * @since v0.5.3
  */
 export let zipWith = (fn, list1, list2) => {
@@ -625,12 +633,12 @@ export let unzip = list => {
  * Produces a new list with the specified number of elements removed from
  * the beginning of the input list.
  *
- * Fails if the specified amount is a negative number.
- *
  * @param count: The amount of elements to remove
  * @param list: The input list
  * @returns The new list without the dropped elements
  *
+ * @throws Failure(String): When `count` is negative
+ *
  * @since v0.2.0
  */
 export let rec drop = (count, list) => {
@@ -667,12 +675,12 @@ export let rec dropWhile = (fn, list) => {
  * Produces a new list with–at most—the specified amount elements from
  * the beginning of the input list.
  *
- * Fails if the specified amount is a negative number.
- *
  * @param count: The amount of elements to keep
  * @param list: The input list
  * @returns The new list containing the taken elements
  *
+ * @throws Failure(String): When `count` is negative
+ *
  * @since v0.2.0
  */
 export let rec take = (count, list) => {
@@ -769,13 +777,14 @@ export let product = (list1, list2) => {
  * Provides the subset of a list given zero-based start index and amount of elements
  * to include.
  *
- * Fails if the start index or amount of elements are negative numbers.
- *
  * @param start: The index of the list where the subset will begin (inclusive)
  * @param length: The amount of elements to be included in the subset
  * @param list: The input list
  * @returns The subset of the list
  *
+ * @throws Failure(String): When `start` is negative
+ * @throws Failure(String): When `length` is negative
+ *
  * @since v0.2.0
  */
 export let sub = (start, length, list) => {

package/list.md

@@ -674,7 +674,6 @@ insert : (a, Number, List<a>) -> List<a>
 ```
 
 Inserts a new value into a list at the specified index.
-Fails if the index is out-of-bounds.
 
 Parameters:
 
@@ -690,6 +689,13 @@ Returns:
 |----|-----------|
 |`List<a>`|The new list|
 
+Throws:
+
+`Failure(String)`
+
+* When `index` is negative
+* When `index` is more than 0 and greater than the list size
+
 ### List.**count**
 
 <details>
@@ -735,7 +741,6 @@ part : (Number, List<a>) -> (List<a>, List<a>)
 ```
 
 Split a list into two, with the first list containing the required number of elements.
-Fails if the input list doesn't contain at least the required amount of elements.
 
 Parameters:
 
@@ -750,6 +755,13 @@ Returns:
 |----|-----------|
 |`(List<a>, List<a>)`|Two lists where the first contains exactly the required amount of elements and the second contains any remaining elements|
 
+Throws:
+
+`Failure(String)`
+
+* When `count` is negative
+* When the list doesn't contain at least the required amount of elements
+
 ### List.**rotate**
 
 <details disabled>
@@ -766,8 +778,6 @@ Rotates list elements by the specified amount to the left.
 If value is negative, list elements will be rotated by the
 specified amount to the right. See examples.
 
-Fails if the input list doesn't contain at least the required amount of elements.
-
 Parameters:
 
 |param|type|description|
@@ -775,6 +785,12 @@ Parameters:
 |`count`|`Number`|The number of elements to rotate by|
 |`list`|`List<a>`|The list to be rotated|
 
+Throws:
+
+`Failure(String)`
+
+* When the list doesn't contain at least the required amount of elements
+
 Examples:
 
 ```grain
@@ -943,8 +959,6 @@ drop : (Number, List<a>) -> List<a>
 Produces a new list with the specified number of elements removed from
 the beginning of the input list.
 
-Fails if the specified amount is a negative number.
-
 Parameters:
 
 |param|type|description|
@@ -958,6 +972,12 @@ Returns:
 |----|-----------|
 |`List<a>`|The new list without the dropped elements|
 
+Throws:
+
+`Failure(String)`
+
+* When `count` is negative
+
 ### List.**dropWhile**
 
 <details disabled>
@@ -1000,8 +1020,6 @@ take : (Number, List<a>) -> List<a>
 Produces a new list with–at most—the specified amount elements from
 the beginning of the input list.
 
-Fails if the specified amount is a negative number.
-
 Parameters:
 
 |param|type|description|
@@ -1015,6 +1033,12 @@ Returns:
 |----|-----------|
 |`List<a>`|The new list containing the taken elements|
 
+Throws:
+
+`Failure(String)`
+
+* When `count` is negative
+
 ### List.**takeWhile**
 
 <details disabled>
@@ -1152,8 +1176,6 @@ sub : (Number, Number, List<a>) -> List<a>
 Provides the subset of a list given zero-based start index and amount of elements
 to include.
 
-Fails if the start index or amount of elements are negative numbers.
-
 Parameters:
 
 |param|type|description|
@@ -1168,6 +1190,13 @@ Returns:
 |----|-----------|
 |`List<a>`|The subset of the list|
 
+Throws:
+
+`Failure(String)`
+
+* When `start` is negative
+* When `length` is negative
+
 ### List.**join**
 
 <details disabled>

package/map.gr

@@ -9,7 +9,7 @@ import Array from "array"
 import { hash } from "hash"
 import Memory from "runtime/unsafe/memory"
 import WasmI32 from "runtime/unsafe/wasmi32"
-import { allocateArray } from "runtime/dataStructures"
+import { allocateArray, untagSimpleNumber } from "runtime/dataStructures"
 
 // TODO: Consider implementing this as List<(Box<k>, Box<v>)>
 record Bucket<k, v> {
@@ -418,19 +418,6 @@ export let fromList = list => {
   map
 }
 
-let setInArray = array => {
-  @disableGC
-  let rec iter = (i, key, value) => {
-    array[i] = (key, value)
-    // no decRef on key and value, since they are stored in array
-    Memory.decRef(WasmI32.fromGrain(iter))
-    Memory.incRef(WasmI32.fromGrain((+)))
-    Memory.incRef(WasmI32.fromGrain(i))
-    i + 1
-  }
-  iter
-}
-
 /**
  * Converts a map into an array of its key-value pairs.
  *
@@ -439,20 +426,24 @@ let setInArray = array => {
  *
  * @since v0.2.0
  */
-@disableGC
-export let rec toArray = map => {
-  let length = WasmI32.shrS(WasmI32.fromGrain(map.size), 1n)
-  let array = WasmI32.toGrain(allocateArray(length)): Array<a>
-  Memory.incRef(WasmI32.fromGrain(setInArray))
-  Memory.incRef(WasmI32.fromGrain(array))
-  let setInArray = setInArray(array)
-  Memory.incRef(WasmI32.fromGrain(reduce))
-  Memory.incRef(WasmI32.fromGrain(setInArray))
-  Memory.incRef(WasmI32.fromGrain(map))
-  reduce(setInArray, 0, map)
-  Memory.decRef(WasmI32.fromGrain(setInArray))
-  Memory.decRef(WasmI32.fromGrain(map))
-  Memory.decRef(WasmI32.fromGrain(toArray))
+@unsafe
+export let toArray: Map<a, b> -> Array<(a, b)> = map => {
+  let length = untagSimpleNumber(map.size)
+  let array = WasmI32.toGrain(allocateArray(length))
+  @unsafe
+  let reducer = (i, key, value) => {
+    // Assign the values into the array.
+    // We store them directly to prevent GC on uninitialized array data.
+    let array = WasmI32.fromGrain(array)
+    let item = (key, value)
+    WasmI32.store(
+      WasmI32.add(array, WasmI32.mul(untagSimpleNumber(i), 4n)),
+      Memory.incRef(WasmI32.fromGrain(item)),
+      8n
+    )
+    i + 1
+  }
+  reduce(reducer, 0, map)
   array
 }