@grain/stdlib 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+### [0.5.5](https://github.com/grain-lang/grain/compare/stdlib-v0.5.4...stdlib-v0.5.5) (2022-12-05)
+
+
+### Features
+
+* **graindoc:** Add attribute for exceptions that may be thrown ([#1492](https://github.com/grain-lang/grain/issues/1492)) ([b2e75c7](https://github.com/grain-lang/grain/commit/b2e75c7452ef2544c768729c7a45e21ff31616d0))
+* **graindoc:** Support deprecations on module docblocks ([#1498](https://github.com/grain-lang/grain/issues/1498)) ([b3dc85c](https://github.com/grain-lang/grain/commit/b3dc85c0fc311479de4e57774a075c3a922216ba))
+* **stdlib:** Add `parse` function to Number module ([#1517](https://github.com/grain-lang/grain/issues/1517)) ([59e89d1](https://github.com/grain-lang/grain/commit/59e89d12b7fcf2626c8adb45c742a787171b7024))
+* **stdlib:** Add `parseFloat` function to Number module ([#1288](https://github.com/grain-lang/grain/issues/1288)) ([e21f2b1](https://github.com/grain-lang/grain/commit/e21f2b137f7dcd67cccf9debf695db852dc2afc5))
+* **stdlib:** Add `split` function to Regex module ([#1469](https://github.com/grain-lang/grain/issues/1469)) ([0c1eb73](https://github.com/grain-lang/grain/commit/0c1eb73d01e30f457138c6e3b603a9faddcf8e9b))
+* **stdlib:** Add `splitAll` function to Regex module ([0c1eb73](https://github.com/grain-lang/grain/commit/0c1eb73d01e30f457138c6e3b603a9faddcf8e9b))
+* **stdlib:** Add Path module for working with system paths ([#1452](https://github.com/grain-lang/grain/issues/1452)) ([900e976](https://github.com/grain-lang/grain/commit/900e976654565b3618e2215e9b7cefbda873d9a8))
+* **stdlib:** Improve performance in Array & List modules ([#1487](https://github.com/grain-lang/grain/issues/1487)) ([2168f6a](https://github.com/grain-lang/grain/commit/2168f6ade151548bc655debeb8a1bc09ce87cb77))
+* **stdlib:** Improve performance of `flatMap`, `some`, and `every` functions in Array module ([2168f6a](https://github.com/grain-lang/grain/commit/2168f6ade151548bc655debeb8a1bc09ce87cb77))
+* **stdlib:** Improve performance of `some` and `every` functions in List module ([2168f6a](https://github.com/grain-lang/grain/commit/2168f6ade151548bc655debeb8a1bc09ce87cb77))
+
+
+### Bug Fixes
+
+* **grainfmt:** Add parentheses around some binops for precedence clarity ([#1514](https://github.com/grain-lang/grain/issues/1514)) ([3ac27cc](https://github.com/grain-lang/grain/commit/3ac27cc6e17b896dae0ef2cb5f5de510c7c2dd60))
+* **grainfmt:** Handle multiple line items and comments better ([#1460](https://github.com/grain-lang/grain/issues/1460)) ([5395fd4](https://github.com/grain-lang/grain/commit/5395fd45b79fb3bcf3dd1ec52a1d5973a23a4bdc))
+* **runtime:** Properly divide bigints in the number type ([59e89d1](https://github.com/grain-lang/grain/commit/59e89d12b7fcf2626c8adb45c742a787171b7024))
+
 ### [0.5.4](https://github.com/grain-lang/grain/compare/stdlib-v0.5.3...stdlib-v0.5.4) (2022-11-12)
 
 

package/array.gr

@@ -12,34 +12,27 @@ import WasmI32 from "runtime/unsafe/wasmi32"
 import Memory from "runtime/unsafe/memory"
 import { allocateArray, tagSimpleNumber } from "runtime/dataStructures"
 import Exception from "runtime/exception"
+import { coerceNumberToWasmI32 } from "runtime/numbers"
 
 /**
  * @section Values: Functions for working with the Array data type.
  */
 
-@disableGC
-let mut _ARRAY_LENGTH_OFFSET = 1n
-@disableGC
-let mut _ARRAY_START_OFFSET = 1n
+@unsafe
+let mut _ARRAY_LENGTH_OFFSET = 4n
+@unsafe
+let mut _ARRAY_START_OFFSET = 8n
 
-@disableGC
-let initPtr = () => {
-  _ARRAY_LENGTH_OFFSET = 4n
-  _ARRAY_START_OFFSET = 8n
-}
-initPtr()
-
-@disableGC
-let initLength = length => {
-  let length = WasmI32.fromGrain(length)
-  if (WasmI32.eqz(WasmI32.and(length, 1n))) {
+@unsafe
+let checkLength = length => {
+  let ptr = WasmI32.fromGrain(length)
+  if (WasmI32.eqz(WasmI32.and(ptr, 1n))) {
     throw Exception.InvalidArgument("Length argument must be an integer")
   }
-  let length = WasmI32.shrS(length, 1n)
-  if (WasmI32.ltS(length, 0n)) {
+  let len = WasmI32.shrS(ptr, 1n)
+  if (WasmI32.ltS(len, 0n)) {
     throw Exception.InvalidArgument("Length argument must be non-negative")
   }
-  length
 }
 
 /**
@@ -51,16 +44,12 @@ let initLength = length => {
  * @example Array.length([> 1, 2, 3, 4, 5]) == 5
  * @since v0.1.0
  */
-@disableGC
-export let rec length = array => {
+@unsafe
+export let length = array => {
   let ptr = WasmI32.fromGrain(array: Array<a>)
-  let ret = tagSimpleNumber(WasmI32.load(ptr, _ARRAY_LENGTH_OFFSET))
-  Memory.decRef(ptr)
-  Memory.decRef(WasmI32.fromGrain(length))
-  ret
+  tagSimpleNumber(WasmI32.load(ptr, _ARRAY_LENGTH_OFFSET))
 }
 
-// [FIXME] (#793) Type annotation breaks compiler
 /**
  * Creates a new array of the specified length with each element being
  * initialized with the given value.
@@ -69,18 +58,18 @@ export let rec length = array => {
  * @param item: The value to store at each index
  * @returns The new array
  *
+ * @throws InvalidArgument(String): When `length` is not an integer
+ * @throws InvalidArgument(String): When `length` is negative
+ *
  * @example Array.make(5, "foo") // [> "foo", "foo", "foo", "foo", "foo"]
  *
  * @since v0.1.0
  */
-@disableGC
-export let rec make /*: (Number, a) -> Array<a>*/ =
-  (
-    length: Number,
-    item: a,
-  ) => {
+@unsafe
+export let make: (Number, a) -> Array<a> = (length: Number, item: a) => {
   let lengthArg = length
-  let length = initLength(length)
+  checkLength(length)
+  let length = coerceNumberToWasmI32(length)
   let byteLength = WasmI32.mul(length, 4n)
   let array = allocateArray(length)
   for (let mut i = 0n; WasmI32.ltS(i, byteLength); i = WasmI32.add(i, 4n)) {
@@ -90,11 +79,7 @@ export let rec make /*: (Number, a) -> Array<a>*/ =
       _ARRAY_START_OFFSET
     )
   }
-  let ret = WasmI32.toGrain(array): Array<a>
-  Memory.decRef(WasmI32.fromGrain(lengthArg))
-  Memory.decRef(WasmI32.fromGrain(item))
-  Memory.decRef(WasmI32.fromGrain(make))
-  ret
+  WasmI32.toGrain(array): Array<a>
 }
 
 /**
@@ -106,34 +91,34 @@ export let rec make /*: (Number, a) -> Array<a>*/ =
  * @param fn: The initializer function to call with each index, where the value returned will be used to initialize the element
  * @returns The new array
  *
+ * @throws InvalidArgument(String): When `length` is not an integer
+ * @throws InvalidArgument(String): When `length` is negative
+ *
  * @example Array.init(5, n => n + 3) // [> 3, 4, 5, 6, 7]
  *
  * @since v0.1.0
  */
-@disableGC
-export let rec init /*: (Number, Number -> a) -> Array<a>*/ =
+@unsafe
+export let init: (Number, Number -> a) -> Array<a> =
   (
     length: Number,
     fn: Number -> a,
   ) => {
-  let length = initLength(length)
+  checkLength(length)
+  let length = coerceNumberToWasmI32(length)
   let byteLength = WasmI32.mul(length, 4n)
   let array = allocateArray(length)
   let mut index = 0n
   for (let mut i = 0n; WasmI32.ltS(i, byteLength); i = WasmI32.add(i, 4n)) {
-    Memory.incRef(WasmI32.fromGrain(fn))
     // [FIXME] This line fails the array/map test suite (#815)
-    //assert !WasmI32.eqz(WasmI32.and(WasmI32.fromGrain(index), 1n)) // must be a simple int for next line to be correct
+    // assert !WasmI32.eqz(WasmI32.and(WasmI32.fromGrain(index), 1n)) // must be a simple int for next line to be correct
     WasmI32.store(
       WasmI32.add(array, i),
-      WasmI32.fromGrain(fn(tagSimpleNumber(index))),
+      Memory.incRef(WasmI32.fromGrain(fn(tagSimpleNumber(index)))),
       _ARRAY_START_OFFSET
     )
-    //WasmI32.store(WasmI32.add(array, i), WasmI32.fromGrain(4), _ARRAY_START_OFFSET)
     index = WasmI32.add(index, 1n)
   }
-  Memory.decRef(WasmI32.fromGrain(fn))
-  Memory.decRef(WasmI32.fromGrain(init))
   WasmI32.toGrain(array): Array<a>
 }
 
@@ -425,7 +410,19 @@ export let reducei = (fn, initial, array) => {
  * @since v0.3.0
  */
 export let flatMap = (fn, array) => {
-  reduce((result, value) => append(result, fn(value)), [>], array)
+  let nested = map(fn, array)
+  let arrLen = reduce((acc, arr) => acc + length(arr), 0, nested)
+  let mut outerI = 0
+  let mut innerI = 0
+  init(arrLen, i => {
+    if (innerI >= length(nested[outerI])) {
+      innerI = 0
+      outerI += 1
+    }
+    let res = nested[outerI][innerI]
+    innerI += 1
+    res
+  })
 }
 
 /**
@@ -439,9 +436,12 @@ export let flatMap = (fn, array) => {
  * @since v0.3.0
  */
 export let every = (fn, array) => {
-  reduce((acc, value) => {
-    acc && fn(value)
-  }, true, array)
+  let len = length(array)
+  let mut all = true
+  for (let mut index = 0; all && index < len; index += 1) {
+    all = fn(array[index])
+  }
+  all
 }
 
 /**
@@ -455,9 +455,12 @@ export let every = (fn, array) => {
  * @since v0.3.0
  */
 export let some = (fn, array) => {
-  reduce((acc, value) => {
-    acc || fn(value)
-  }, false, array)
+  let len = length(array)
+  let mut found = false
+  for (let mut index = 0; !found && index < len; index += 1) {
+    found = fn(array[index])
+  }
+  found
 }
 
 /**
@@ -799,12 +802,12 @@ export let unique = array => {
  * The first tuple will contain the first item of each array, the second tuple
  * will contain the second item of each array, and so on.
  *
- * Calling this function with arrays of different sizes will throw an error.
- *
  * @param array1: The array to provide values for the first tuple element
  * @param array2: The array to provide values for the second tuple element
  * @returns The new array containing indexed pairs of `(a, b)`
  *
+ * @throws Failure(String): When the arrays have different sizes
+ *
  * @since v0.4.0
  */
 export let zip = (array1: Array<a>, array2: Array<b>) => {
@@ -824,7 +827,7 @@ export let zip = (array1: Array<a>, array2: Array<b>) => {
  * applying the function to the first elements of each array, the second element
  * will contain the result of applying the function to the second elements of
  * each array, and so on.
- * 
+ *
  * Calling this function with arrays of different sizes will cause the returned
  * array to have the length of the smaller array.
  *
@@ -835,7 +838,7 @@ export let zip = (array1: Array<a>, array2: Array<b>) => {
  *
  * @example Array.zipWith((a, b) => a + b, [> 1, 2, 3], [> 4, 5, 6]) // [> 5, 7, 9]
  * @example Array.zipWith((a, b) => a * b, [> 1, 2, 3], [> 4, 5]) // [> 4, 10]
- * 
+ *
  * @since v0.5.3
  */
 export let zipWith = (fn, array1: Array<a>, array2: Array<b>) => {

package/array.md

@@ -83,6 +83,13 @@ Returns:
 |----|-----------|
 |`Array<a>`|The new array|
 
+Throws:
+
+`InvalidArgument(String)`
+
+* When `length` is not an integer
+* When `length` is negative
+
 Examples:
 
 ```grain
@@ -117,6 +124,13 @@ Returns:
 |----|-----------|
 |`Array<a>`|The new array|
 
+Throws:
+
+`InvalidArgument(String)`
+
+* When `length` is not an integer
+* When `length` is negative
+
 Examples:
 
 ```grain
@@ -550,7 +564,7 @@ No other changes yet.
 </details>
 
 ```grain
-flatMap : ((a -> Array<b>), Array<a>) -> Array<b>
+flatMap : ((b -> Array<a>), Array<b>) -> Array<a>
 ```
 
 Produces a new array by calling a function on each element
@@ -562,14 +576,14 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Array<b>`|The function to be called on each element, where the value returned will be an array that gets appended to the new array|
-|`array`|`Array<a>`|The array to iterate|
+|`fn`|`b -> Array<a>`|The function to be called on each element, where the value returned will be an array that gets appended to the new array|
+|`array`|`Array<b>`|The array to iterate|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Array<b>`|The new array|
+|`Array<a>`|The new array|
 
 ### Array.**every**
 
@@ -999,8 +1013,6 @@ Produces a new array filled with tuples of elements from both given arrays.
 The first tuple will contain the first item of each array, the second tuple
 will contain the second item of each array, and so on.
 
-Calling this function with arrays of different sizes will throw an error.
-
 Parameters:
 
 |param|type|description|
@@ -1014,6 +1026,12 @@ Returns:
 |----|-----------|
 |`Array<(a, b)>`|The new array containing indexed pairs of `(a, b)`|
 
+Throws:
+
+`Failure(String)`
+
+* When the arrays have different sizes
+
 ### Array.**zipWith**
 
 <details disabled>

package/buffer.gr

@@ -66,7 +66,7 @@ let autogrow = (len, buf) => {
 
 /* Memcopies bytes from a source byte sequence to a destination byte sequence via pointers */
 @unsafe
-let rec appendBytes = (srcOff, dstOff, len, src, dst) => {
+let appendBytes = (srcOff, dstOff, len, src, dst) => {
   let (+) = WasmI32.add
   Memory.copy(dst + _VALUE_OFFSET + dstOff, src + _VALUE_OFFSET + srcOff, len)
 }
@@ -114,6 +114,8 @@ let addInt32help = (value, buffer) => {
  * @param initialSize: The initial size of the buffer
  * @returns The new buffer
  *
+ * @throws InvalidArgument(String): When the `initialSize` is a negative number
+ *
  * @since v0.4.0
  */
 export let make = initialSize => {
@@ -168,6 +170,9 @@ export let reset = buffer => {
  * @param length: The number of bytes to truncate the buffer to
  * @param buffer: The buffer to truncate
  *
+ * @throws IndexOutOfBounds: When the `length` is negative
+ * @throws IndexOutOfBounds: When the `length` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -202,6 +207,10 @@ export let toBytes = buffer => {
  * @param buffer: The buffer to copy from
  * @returns A byte sequence with bytes copied from the buffer
  *
+ * @throws IndexOutOfBounds: When `start` is negative
+ * @throws IndexOutOfBounds: When `start` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `start + length` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let toBytesSlice = (start, length, buffer) => {
@@ -329,6 +338,11 @@ export let addStringSlice = (start: Number, end, string, buffer) => {
  * @param bytes: The byte sequence to append
  * @param buffer: The buffer to mutate
  *
+ * @throws IndexOutOfBounds: When the `start` is negative
+ * @throws IndexOutOfBounds: When the `start` is greater than or equal to the `bytes` size
+ * @throws IndexOutOfBounds: When the `length` is negative
+ * @throws IndexOutOfBounds: When the `length` is greater than the `bytes` length minus `start`
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -410,6 +424,10 @@ export let addBufferSlice = (start, length, srcBuffer, dstBuffer) => {
  * @param buffer: The buffer to access
  * @returns A 32-bit integer representing a signed 8-bit integer that starts at the given index
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 1` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let getInt8S = (index, buffer) => {
@@ -424,6 +442,10 @@ export let getInt8S = (index, buffer) => {
  * @param buffer: The buffer to access
  * @returns A 32-bit integer representing an unsigned 8-bit integer that starts at the given index
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 1` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let getInt8U = (index, buffer) => {
@@ -438,6 +460,10 @@ export let getInt8U = (index, buffer) => {
  * @param value: The value to set
  * @param buffer: The buffer to mutate
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 1` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let setInt8 = (index, value, buffer) => {
@@ -464,6 +490,10 @@ export let addInt8 = (value, buffer) => {
  * @param buffer: The buffer to access
  * @returns A 32-bit integer representing a signed 16-bit integer that starts at the given index
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 2` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let getInt16S = (index, buffer) => {
@@ -478,6 +508,10 @@ export let getInt16S = (index, buffer) => {
  * @param buffer: The buffer to access
  * @returns A 32-bit integer representing an unsigned 16-bit integer that starts at the given index
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 2` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let getInt16U = (index, buffer) => {
@@ -492,6 +526,10 @@ export let getInt16U = (index, buffer) => {
  * @param value: The value to set
  * @param buffer: The buffer to mutate
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 2` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let setInt16 = (index, value, buffer) => {
@@ -518,6 +556,10 @@ export let addInt16 = (value, buffer) => {
  * @param buffer: The buffer to access
  * @returns A signed 32-bit integer that starts at the given index
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 4` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let getInt32 = (index, buffer) => {
@@ -532,6 +574,10 @@ export let getInt32 = (index, buffer) => {
  * @param value: The value to set
  * @param buffer: The buffer to mutate
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 4` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let setInt32 = (index, value, buffer) => {
@@ -558,6 +604,10 @@ export let addInt32 = (value, buffer) => {
  * @param buffer: The buffer to access
  * @returns A 32-bit float that starts at the given index
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 4` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let getFloat32 = (index, buffer) => {
@@ -572,6 +622,10 @@ export let getFloat32 = (index, buffer) => {
  * @param value: The value to set
  * @param buffer: The buffer to mutate
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 4` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let setFloat32 = (index, value, buffer) => {
@@ -601,6 +655,10 @@ export let addFloat32 = (value, buffer) => {
  * @param buffer: The buffer to access
  * @returns A signed 64-bit integer that starts at the given index
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 8` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let getInt64 = (index, buffer) => {
@@ -615,6 +673,10 @@ export let getInt64 = (index, buffer) => {
  * @param value: The value to set
  * @param buffer: The buffer to mutate
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 8` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let setInt64 = (index, value, buffer) => {
@@ -644,6 +706,10 @@ export let addInt64 = (value, buffer) => {
  * @param buffer: The buffer to access
  * @returns A 64-bit float that starts at the given index
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 8` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let getFloat64 = (index, buffer) => {
@@ -658,6 +724,10 @@ export let getFloat64 = (index, buffer) => {
  * @param value: The value to set
  * @param buffer: The buffer to mutate
  *
+ * @throws IndexOutOfBounds: When `index` is negative
+ * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
+ * @throws IndexOutOfBounds: When `index + 8` is greater than the buffer size
+ *
  * @since v0.4.0
  */
 export let setFloat64 = (index, value, buffer) => {