@grain/stdlib 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+### [0.5.3](https://github.com/grain-lang/grain/compare/stdlib-v0.5.2...stdlib-v0.5.3) (2022-08-05)
+
+
+### Features
+
+* Implement Pervasives.compare ([#1399](https://github.com/grain-lang/grain/issues/1399)) ([ebd87e4](https://github.com/grain-lang/grain/commit/ebd87e4308a8950fd95f060ebc446833b064237c))
+* **stdlib:** Add `charCodeAt` function to String module ([#1376](https://github.com/grain-lang/grain/issues/1376)) ([c3abbc9](https://github.com/grain-lang/grain/commit/c3abbc991c8b05e3de20e670d2bc3e491feebf8a))
+* **stdlib:** Add `lastIndexOf` function to String module ([#1372](https://github.com/grain-lang/grain/issues/1372)) ([b73d9bf](https://github.com/grain-lang/grain/commit/b73d9bf9ff3291b83e6f4263e392395d04dc9995))
+* **stdlib:** Implement `isFloat`, `isInteger` & `isRational` in Number module ([#1393](https://github.com/grain-lang/grain/issues/1393)) ([0af0669](https://github.com/grain-lang/grain/commit/0af066993a2b80e417d2c625b27fd11cb1f1f55f))
+* **stdlib:** Implement List.zip, List.unzip, List.zipWith, Array.reduceRight, Array.zipWith ([#1363](https://github.com/grain-lang/grain/issues/1363)) ([3e7c147](https://github.com/grain-lang/grain/commit/3e7c147fea2d2fb8b7c5a3d6b3eb1453f2861e36))
+* **stdlib:** Implement mutable/immutable priority queues ([#1397](https://github.com/grain-lang/grain/issues/1397)) ([244be1b](https://github.com/grain-lang/grain/commit/244be1b7254caf0b451902ac56413382eb196747))
+* **stdlib:** Marshal ([#1352](https://github.com/grain-lang/grain/issues/1352)) ([d659de2](https://github.com/grain-lang/grain/commit/d659de2d92260f7726164876827c639bfd9d0590))
+
+
+### Bug Fixes
+
+* **compiler:** Correctly handle underscores in bigint literals ([0af0669](https://github.com/grain-lang/grain/commit/0af066993a2b80e417d2c625b27fd11cb1f1f55f))
+* **graindoc:** Use defined module name throughout generated doc ([#1406](https://github.com/grain-lang/grain/issues/1406)) ([c33a777](https://github.com/grain-lang/grain/commit/c33a777a93d5e40a081991db5e6ea61ade4fbabc))
+* **stdlib:** Correctly promote numbers to bigints when left-shifting ([#1354](https://github.com/grain-lang/grain/issues/1354)) ([5280e98](https://github.com/grain-lang/grain/commit/5280e98a91a57fae074299fc7bad3c41f69fa2a3))
+* **stdlib:** Prevent addBytesSlice throwing error on empty buffer ([#1394](https://github.com/grain-lang/grain/issues/1394)) ([bdd4be4](https://github.com/grain-lang/grain/commit/bdd4be46730290908b7b939f41679acce7834167))
+
 ### [0.5.2](https://github.com/grain-lang/grain/compare/stdlib-v0.5.1...stdlib-v0.5.2) (2022-06-29)
 
 

package/array.gr

@@ -358,6 +358,32 @@ export let reduce = (fn, initial, array) => {
   acc
 }
 
+/**
+ * Combines all elements of an array using a reducer function,
+ * starting from the "end", or right side, of the array.
+ *
+ * In `Array.reduceRight(fn, initial, array)`, `fn` is called with
+ * each element of the array and an accumulator, and returns
+ * a new accumulator. The final value is the last accumulator
+ * returned. The accumulator starts with value `initial`.
+ *
+ * @param fn: The reducer function to call on each element, where the value returned will be the next accumulator value
+ * @param initial: The initial value to use for the accumulator on the first iteration
+ * @param array: The array to iterate
+ * @returns The final accumulator returned from `fn`
+ *
+ * @example Array.reduceRight((a, b) => b ++ a, "", [> "baz", "bar", "foo"]) // "foobarbaz"
+ *
+ * @since v0.5.3
+ */
+export let reduceRight = (fn, initial, array) => {
+  let mut acc = initial
+  for (let mut i = length(array) - 1; i >= 0; i -= 1) {
+    acc = fn(array[i], acc)
+  }
+  acc
+}
+
 /**
  * Combines all elements of an array using a reducer function,
  * starting from the "head", or left side, of the array.
@@ -555,7 +581,7 @@ export let fromList = list => {
  * @since v0.2.0
  */
 export let contains = (search, array) => {
-  // TODO: This should use recursion when we can pattern match arrays
+  // TODO(#189): This should be rewritten to use recursion and pattern matching
   let len = length(array)
   let mut found = false
   for (let mut index = 0; !found && index < len; index += 1) {
@@ -787,6 +813,35 @@ export let zip = (array1: Array<a>, array2: Array<b>) => {
   }
 }
 
+/**
+ * Produces a new array filled with elements defined by applying a function on
+ * pairs from both given arrays. The first element will contain the result of
+ * 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.
+ *
+ * @param fn: The function to apply to pairs of elements
+ * @param array1: The array whose elements will each be passed to the function as the first argument
+ * @param array2: The array whose elements will each be passed to the function as the second argument
+ * @returns The new array containing elements derived from applying the function to pairs of input array elements
+ *
+ * @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>) => {
+  let len1 = length(array1)
+  let len2 = length(array2)
+  let minLen = if (len1 > len2) len2 else len1
+  init(minLen, index => {
+    fn(array1[index], array2[index])
+  })
+}
+
 /**
  * Produces two arrays by splitting apart an array of tuples.
  *

package/array.md

@@ -439,6 +439,45 @@ Examples:
 Array.reduce((a, b) => a + b, 0, [> 1, 2, 3]) // 6
 ```
 
+### Array.**reduceRight**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+reduceRight : (((a, b) -> b), b, Array<a>) -> b
+```
+
+Combines all elements of an array using a reducer function,
+starting from the "end", or right side, of the array.
+
+In `Array.reduceRight(fn, initial, array)`, `fn` is called with
+each element of the array and an accumulator, and returns
+a new accumulator. The final value is the last accumulator
+returned. The accumulator starts with value `initial`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`(a, b) -> b`|The reducer function to call on each element, where the value returned will be the next accumulator value|
+|`initial`|`b`|The initial value to use for the accumulator on the first iteration|
+|`array`|`Array<a>`|The array to iterate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`b`|The final accumulator returned from `fn`|
+
+Examples:
+
+```grain
+Array.reduceRight((a, b) => b ++ a, "", [> "baz", "bar", "foo"]) // "foobarbaz"
+```
+
 ### Array.**reducei**
 
 <details disabled>
@@ -945,6 +984,50 @@ Returns:
 |----|-----------|
 |`Array<(a, b)>`|The new array containing indexed pairs of `(a, b)`|
 
+### Array.**zipWith**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+zipWith : (((a, b) -> c), Array<a>, Array<b>) -> Array<c>
+```
+
+Produces a new array filled with elements defined by applying a function on
+pairs from both given arrays. The first element will contain the result of
+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.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`(a, b) -> c`|The function to apply to pairs of elements|
+|`array1`|`Array<a>`|The array whose elements will each be passed to the function as the first argument|
+|`array2`|`Array<b>`|The array whose elements will each be passed to the function as the second argument|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Array<c>`|The new array containing elements derived from applying the function to pairs of input array elements|
+
+Examples:
+
+```grain
+Array.zipWith((a, b) => a + b, [> 1, 2, 3], [> 4, 5, 6]) // [> 5, 7, 9]
+```
+
+```grain
+Array.zipWith((a, b) => a * b, [> 1, 2, 3], [> 4, 5]) // [> 4, 10]
+```
+
 ### Array.**unzip**
 
 <details disabled>

package/bigint.md

@@ -17,7 +17,7 @@ import BigInt from "bigint"
 
 Functions for converting between Numbers and the BigInt type.
 
-### Bigint.**fromNumber**
+### BigInt.**fromNumber**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -42,7 +42,7 @@ Returns:
 |----|-----------|
 |`BigInt`|The Number represented as a BigInt|
 
-### Bigint.**toNumber**
+### BigInt.**toNumber**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -71,7 +71,7 @@ Returns:
 
 Mathematical operations for BigInt values.
 
-### Bigint.**incr**
+### BigInt.**incr**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -96,7 +96,7 @@ Returns:
 |----|-----------|
 |`BigInt`|The incremented value|
 
-### Bigint.**decr**
+### BigInt.**decr**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -121,7 +121,7 @@ Returns:
 |----|-----------|
 |`BigInt`|The decremented value|
 
-### Bigint.**neg**
+### BigInt.**neg**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -146,7 +146,7 @@ Returns:
 |----|-----------|
 |`BigInt`|The negated operand|
 
-### Bigint.**abs**
+### BigInt.**abs**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -171,7 +171,7 @@ Returns:
 |----|-----------|
 |`BigInt`|The operand's absolute value|
 
-### Bigint.**add**
+### BigInt.**add**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -197,7 +197,7 @@ Returns:
 |----|-----------|
 |`BigInt`|The sum of the two operands|
 
-### Bigint.**sub**
+### BigInt.**sub**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -223,7 +223,7 @@ Returns:
 |----|-----------|
 |`BigInt`|The difference of the two operands|
 
-### Bigint.**mul**
+### BigInt.**mul**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -249,7 +249,7 @@ Returns:
 |----|-----------|
 |`BigInt`|The product of the two operands|
 
-### Bigint.**div**
+### BigInt.**div**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -276,7 +276,7 @@ Returns:
 |----|-----------|
 |`BigInt`|The quotient of its operands|
 
-### Bigint.**rem**
+### BigInt.**rem**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -303,7 +303,7 @@ Returns:
 |----|-----------|
 |`BigInt`|The remainder of its operands|
 
-### Bigint.**quotRem**
+### BigInt.**quotRem**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -329,7 +329,7 @@ Returns:
 |----|-----------|
 |`(BigInt, BigInt)`|The quotient and remainder of its operands|
 
-### Bigint.**gcd**
+### BigInt.**gcd**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -359,7 +359,7 @@ Returns:
 
 Functions for operating on bits of BigInt values.
 
-### Bigint.**shl**
+### BigInt.**shl**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -385,7 +385,7 @@ Returns:
 |----|-----------|
 |`BigInt`|The shifted value|
 
-### Bigint.**shr**
+### BigInt.**shr**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -415,7 +415,7 @@ Returns:
 
 Functions for comparing BigInt values.
 
-### Bigint.**eqz**
+### BigInt.**eqz**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -440,7 +440,7 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is equal to zero or `false` otherwise|
 
-### Bigint.**eq**
+### BigInt.**eq**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -466,7 +466,7 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is equal to the second value or `false` otherwise|
 
-### Bigint.**ne**
+### BigInt.**ne**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -492,7 +492,7 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is not equal to the second value or `false` otherwise|
 
-### Bigint.**lt**
+### BigInt.**lt**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -518,7 +518,7 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than the second value or `false` otherwise|
 
-### Bigint.**lte**
+### BigInt.**lte**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -544,7 +544,7 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than or equal to the second value or `false` otherwise|
 
-### Bigint.**gt**
+### BigInt.**gt**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -570,7 +570,7 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than the second value or `false` otherwise|
 
-### Bigint.**gte**
+### BigInt.**gte**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -600,7 +600,7 @@ Returns:
 
 Boolean operations on the bits of BigInt values.
 
-### Bigint.**lnot**
+### BigInt.**lnot**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -625,7 +625,7 @@ Returns:
 |----|-----------|
 |`BigInt`|Containing the inverted bits of the given value|
 
-### Bigint.**land**
+### BigInt.**land**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -651,7 +651,7 @@ Returns:
 |----|-----------|
 |`BigInt`|Containing a `1` in each bit position for which the corresponding bits of both operands are `1`|
 
-### Bigint.**lor**
+### BigInt.**lor**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -677,7 +677,7 @@ Returns:
 |----|-----------|
 |`BigInt`|Containing a `1` in each bit position for which the corresponding bits of either or both operands are `1`|
 
-### Bigint.**lxor**
+### BigInt.**lxor**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -703,7 +703,7 @@ Returns:
 |----|-----------|
 |`BigInt`|Containing a `1` in each bit position for which the corresponding bits of either but not both operands are `1`|
 
-### Bigint.**clz**
+### BigInt.**clz**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -729,7 +729,7 @@ Returns:
 |----|-----------|
 |`Int32`|The amount of leading zeros|
 
-### Bigint.**ctz**
+### BigInt.**ctz**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -754,7 +754,7 @@ Returns:
 |----|-----------|
 |`Int64`|The amount of trailing zeros|
 
-### Bigint.**popcnt**
+### BigInt.**popcnt**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>
@@ -784,7 +784,7 @@ Returns:
 
 Other functions on BigInts.
 
-### Bigint.**toString**
+### BigInt.**toString**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.5.0</code></summary>

package/buffer.gr

@@ -339,32 +339,34 @@ export let addBytesSlice =
     bytes: Bytes,
     buffer: Buffer,
   ) => {
-  let (-) = WasmI32.sub
-  let (<) = WasmI32.ltS
-  let (>) = WasmI32.gtS
-  let (>=) = WasmI32.geS
-
-  // bounds check start
-  let bytelen = WasmI32.load(WasmI32.fromGrain(bytes), 4n)
-  let srcOff = coerceNumberToWasmI32(start)
-  if (srcOff < 0n || srcOff >= bytelen) {
-    throw Exception.IndexOutOfBounds
-  }
+  if (length != 0) {
+    let (-) = WasmI32.sub
+    let (<) = WasmI32.ltS
+    let (>) = WasmI32.gtS
+    let (>=) = WasmI32.geS
+
+    // bounds check start
+    let bytelen = WasmI32.load(WasmI32.fromGrain(bytes), 4n)
+    let srcOff = coerceNumberToWasmI32(start)
+    if (srcOff < 0n || srcOff >= bytelen) {
+      throw Exception.IndexOutOfBounds
+    }
 
-  // bounds check length
-  let len = coerceNumberToWasmI32(length)
-  if (len < 0n || len > bytelen - srcOff) {
-    throw Exception.IndexOutOfBounds
-  }
+    // bounds check length
+    let len = coerceNumberToWasmI32(length)
+    if (len < 0n || len > bytelen - srcOff) {
+      throw Exception.IndexOutOfBounds
+    }
 
-  autogrow(length, buffer)
+    autogrow(length, buffer)
 
-  let dstOff = coerceNumberToWasmI32(buffer.len)
-  let src = WasmI32.fromGrain(bytes)
-  let dst = WasmI32.fromGrain(buffer.data)
-  appendBytes(srcOff, dstOff, len, src, dst)
+    let dstOff = coerceNumberToWasmI32(buffer.len)
+    let src = WasmI32.fromGrain(bytes)
+    let dst = WasmI32.fromGrain(buffer.data)
+    appendBytes(srcOff, dstOff, len, src, dst)
 
-  buffer.len += length
+    buffer.len += length
+  }
 }
 
 /**

package/float32.md

@@ -46,7 +46,7 @@ NaN (Not a Number) represented as a Float32 value.
 ### Float32.**pi**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
 No other changes yet.
 </details>
 
@@ -59,7 +59,7 @@ Pi represented as a Float32 value.
 ### Float32.**tau**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
 No other changes yet.
 </details>
 
@@ -72,7 +72,7 @@ Tau represented as a Float32 value.
 ### Float32.**e**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
 No other changes yet.
 </details>
 

package/float64.md

@@ -46,7 +46,7 @@ NaN (Not a Number) represented as a Float64 value.
 ### Float64.**pi**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
 No other changes yet.
 </details>
 
@@ -59,7 +59,7 @@ Pi represented as a Float64 value.
 ### Float64.**tau**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
 No other changes yet.
 </details>
 
@@ -72,7 +72,7 @@ Tau represented as a Float64 value.
 ### Float64.**e**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>next</code></summary>
+<summary tabindex="-1">Added in <code>0.5.2</code></summary>
 No other changes yet.
 </details>