@grain/stdlib 0.5.3 → 0.5.5

package/regex.md

@@ -447,3 +447,73 @@ Examples:
 assert Regex.replaceAll(Result.unwrap(Regex.make("o")), "skoot", "r") == "skrrt"
 ```
 
+### Regex.**split**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.5</code></summary>
+No other changes yet.
+</details>
+
+```grain
+split : (RegularExpression, String) -> List<String>
+```
+
+Splits the given string at the first match for the given regular expression.
+
+If the regex pattern contains capture groups, the content of the groups
+will be included in the output list.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`rx`|`RegularExpression`|The regular expression to match|
+|`str`|`String`|The string to split|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<String>`|A list of the split segments|
+
+Examples:
+
+```grain
+assert Regex.split(Result.unwrap(Regex.make(",")), "a,b,c") == [ "a", "b,c" ]
+```
+
+### Regex.**splitAll**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.5</code></summary>
+No other changes yet.
+</details>
+
+```grain
+splitAll : (RegularExpression, String) -> List<String>
+```
+
+Splits the given string at every match for the given regular expression.
+
+If the regex pattern contains capture groups, the content of the groups
+will be included in the output list.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`rx`|`RegularExpression`|The regular expression to match|
+|`str`|`String`|The string to split|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<String>`|A list of the split segments|
+
+Examples:
+
+```grain
+assert Regex.splitAll(Result.unwrap(Regex.make(",")), "a,b,c") == [ "a", "b", "c" ]
+```
+

package/result.gr

@@ -1,15 +1,15 @@
 /**
  * @module Result: Utilities for working with the Result data type.
- * 
+ *
  * The Result type is an enum that represents the possibility of a success case (with the `Ok` variant),
  * or an error case (with the `Err` variant). Use a Result as the return type of a function that may return an error.
- * 
+ *
  * @example import Result from "result"
- * 
- * 
+ *
+ *
  * @example let success = Ok((x) => 1 + x) // Creates a successful Result containing (x) => 1 + x
  * @example let failure = Err("Something bad happened") // Creates an unsuccessful Result containing "Something bad happened"
- * 
+ *
  * @since v0.2.0
  */
 
@@ -22,7 +22,7 @@
  *
  * @param result: The result to check
  * @returns `true` if the Result is the `Ok` variant or `false` otherwise
- * 
+ *
  * @since v0.2.0
  */
 export let isOk = result => {
@@ -37,7 +37,7 @@ export let isOk = result => {
  *
  * @param result: The result to check
  * @returns `true` if the Result is the `Err` variant or `false` otherwise
- * 
+ *
  * @since v0.2.0
  */
 export let isErr = result => !isOk(result)
@@ -47,7 +47,7 @@ export let isErr = result => !isOk(result)
  *
  * @param result: The result to convert
  * @returns `Some(value)` if the Result is `Ok(value)` or `None` if the Result is an `Err`
- * 
+ *
  * @since v0.2.0
  */
 export let toOption = result => {
@@ -63,7 +63,7 @@ export let toOption = result => {
  * @param fn: The function to call on the value of an `Ok` variant
  * @param result: The result to map
  * @returns A new Result produced by the mapping function if the variant was `Ok` or the unmodified `Err` otherwise
- * 
+ *
  * @since v0.2.0
  */
 export let flatMap = (fn, result) => {
@@ -79,7 +79,7 @@ export let flatMap = (fn, result) => {
  * @param fn: The function to call on the value of an `Err` variant
  * @param result: The result to map
  * @returns A new Result produced by the mapping function if the variant was `Err` or the unmodified `Ok` otherwise
- * 
+ *
  * @since v0.2.0
  */
 export let flatMapErr = (fn, result) => {
@@ -95,7 +95,7 @@ export let flatMapErr = (fn, result) => {
  * @param fn: The function to call on the value of an `Ok` variant
  * @param result: The result to map
  * @returns A new `Ok` variant produced by the mapping function if the variant was `Ok` or the unmodified `Err` otherwise
- * 
+ *
  * @since v0.2.0
  */
 export let map = (fn, result) => {
@@ -111,7 +111,7 @@ export let map = (fn, result) => {
  * @param fn: The function to call on the value of an `Err` variant
  * @param result: The result to map
  * @returns A new `Err` variant produced by the mapping function if the variant was `Err` or the unmodified `Ok` otherwise
- * 
+ *
  * @since v0.2.0
  */
 export let mapErr = (fn, result) => {
@@ -129,8 +129,8 @@ export let mapErr = (fn, result) => {
  * @param def: A fallback value for an `Err` variant
  * @param result: The result to map
  * @returns The value produced by the mapping function if the result is of the `Ok` variant or the default value otherwise
- * 
- * @since v0.2.0 
+ *
+ * @since v0.2.0
  */
 export let mapWithDefault = (fn, def, result) => {
   match (result) {
@@ -148,7 +148,7 @@ export let mapWithDefault = (fn, def, result) => {
  * @param fnErr: The function to call on the value of an `Err` variant
  * @param result: The result to map
  * @returns The value produced by one of the mapping functions
- * 
+ *
  * @since v0.2.0
  */
 export let mapWithDefaultFn = (fnOk, fnErr, result) => {
@@ -164,7 +164,7 @@ export let mapWithDefaultFn = (fnOk, fnErr, result) => {
  * @param result1: The first result
  * @param result2: The second result
  * @returns The first Result if it is the `Ok` variant or the second Result otherwise
- * 
+ *
  * @since v0.2.0
  */
 export let or = (result1, result2) => {
@@ -180,7 +180,7 @@ export let or = (result1, result2) => {
  * @param result1: The first result
  * @param result2: The second result
  * @returns The second Result if both are the `Ok` variant or the first Result otherwise
- * 
+ *
  * @since v0.2.0
  */
 export let and = (result1, result2) => {
@@ -198,7 +198,7 @@ export let and = (result1, result2) => {
  * @param fnOk: The function to call on the value of an `Ok` variant
  * @param fnErr: The function to call on the value of an `Err` variant
  * @param result: The result to inspect
- * 
+ *
  * @since v0.2.0
  */
 export let peek = (fnOk, fnErr, result) => {
@@ -213,7 +213,7 @@ export let peek = (fnOk, fnErr, result) => {
  *
  * @param fn: The function to call on the value of an `Ok` variant
  * @param result: The result to inspect
- * 
+ *
  * @since v0.2.0
  */
 export let peekOk = (fn, result) => {
@@ -225,7 +225,7 @@ export let peekOk = (fn, result) => {
  *
  * @param fn: The function to call on the value of an `Err` variant
  * @param result: The result to inspect
- * 
+ *
  * @since v0.2.0
  */
 export let peekErr = (fn, result) => {
@@ -240,6 +240,8 @@ export let peekErr = (fn, result) => {
  * @param result: The result to extract a value from
  * @returns The unwrapped value if the Result is the `Ok` variant
  *
+ * @throws Failure(String): When the `result` is `Err`
+ *
  * @example Result.expect("Unexpected error", Ok(1234)) + 42
  *
  * @since v0.4.0
@@ -258,6 +260,8 @@ export let expect = (msg, result) => {
  * @param result: The result to extract a value from
  * @returns The unwrapped value if the result is the `Ok` variant
  *
+ * @throws Failure(String): When the `result` is `Err`
+ *
  * @example Result.unwrap(Err("This will throw"))
  *
  * @since v0.4.0

package/result.md

@@ -406,6 +406,12 @@ Returns:
 |----|-----------|
 |`a`|The unwrapped value if the Result is the `Ok` variant|
 
+Throws:
+
+`Failure(String)`
+
+* When the `result` is `Err`
+
 Examples:
 
 ```grain
@@ -438,6 +444,12 @@ Returns:
 |----|-----------|
 |`a`|The unwrapped value if the result is the `Ok` variant|
 
+Throws:
+
+`Failure(String)`
+
+* When the `result` is `Err`
+
 Examples:
 
 ```grain

package/runtime/atof/common.gr

@@ -0,0 +1,198 @@
+/* grainc-flags --no-pervasives */
+
+// This module was based on Rust's dec2flt
+// https://github.com/rust-lang/rust/blob/1cbc45942d5c0f6eb5d94e3b10762ba541958035/library/core/src/num/dec2flt/common.rs
+// Rust's MIT license is provided below:
+/*
+ * Permission is hereby granted, free of charge, to any
+ * person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the
+ * Software without restriction, including without
+ * limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software
+ * is furnished to do so, subject to the following
+ * conditions:
+ * 
+ * The above copyright notice and this permission notice
+ * shall be included in all copies or substantial portions
+ * of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ * ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+ * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+ * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+ * SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+ * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+ * IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+*/
+
+import WasmI32 from "runtime/unsafe/wasmi32"
+import WasmI64 from "runtime/unsafe/wasmi64"
+import WasmF64 from "runtime/unsafe/wasmf64"
+import { newInt32, newInt64, newFloat64 } from "runtime/dataStructures"
+import { get_POWERS10 } from "runtime/numberUtils"
+import { get_F64_POWERS10_FAST_PATH, get_POWERS5 } from "./table"
+
+primitive (&&): (Bool, Bool) -> Bool = "@and"
+primitive (||): (Bool, Bool) -> Bool = "@or"
+primitive (!): Bool -> Bool = "@not"
+
+export record BiasedFp {
+  f: Int64,
+  mut e: Int32,
+}
+
+@unsafe
+export let _MINIMUM_EXPONENT = -1023n
+@unsafe
+export let _MIN_EXPONENT_ROUND_TO_EVEN = -4N
+@unsafe
+export let _MAX_EXPONENT_ROUND_TO_EVEN = 23N
+@unsafe
+export let _MIN_EXPONENT_FAST_PATH = -22n
+@unsafe
+export let _MAX_EXPONENT_FAST_PATH = 22n
+@unsafe
+export let _MAX_EXPONENT_DISGUISED_FAST_PATH = 37n
+@unsafe
+export let _MAX_MANTISSA_FAST_PATH = WasmI64.shl(2N, 52N)
+@unsafe
+export let _MANTISSA_EXPLICIT_BITS_64 = 52N
+@unsafe
+export let _MANTISSA_EXPLICIT_BITS_32 = 52n
+@unsafe
+export let _INFINITE_POWER = 0x7FFn
+@unsafe
+export let _SMALLEST_POWER_OF_TEN = -342N
+@unsafe
+export let _LARGEST_POWER_OF_TEN = 308N
+@unsafe
+export let _SMALLEST_POWER_OF_FIVE = -342N
+@unsafe
+export let _LARGEST_POWER_OF_FIVE = 308N
+
+@unsafe
+export let _CHAR_CODE_UNDERSCORE = 0x5fn
+@unsafe
+export let _CHAR_CODE_PLUS = 0x2Bn
+@unsafe
+export let _CHAR_CODE_MINUS = 0x2Dn
+@unsafe
+export let _CHAR_CODE_0 = 0x30n
+@unsafe
+export let _CHAR_CODE_e = 0x65n
+@unsafe
+export let _CHAR_CODE_E = 0x45n
+@unsafe
+export let _CHAR_CODE_DOT = 0x2En
+@unsafe
+export let _CHAR_CODE_A = 0x41n
+@unsafe
+export let _CHAR_CODE_Z = 0x5an
+@unsafe
+export let _CHAR_CODE_a = 0x61n
+@unsafe
+export let _CHAR_CODE_f = 0x66n
+@unsafe
+export let _CHAR_CODE_i = 0x69n
+@unsafe
+export let _CHAR_CODE_n = 0x6en
+@unsafe
+export let _CHAR_CODE_t = 0x74n
+@unsafe
+export let _CHAR_CODE_y = 0x79n
+
+export let fpZero = () => { f: 0L, e: 0l }
+@unsafe
+export let fpInf = () =>
+  {
+    f: 0L,
+    e: WasmI32.toGrain(newInt32(_INFINITE_POWER)): Int32,
+  }
+export let fpErr = () => { f: 0L, e: -1l }
+export let fpNan = () => { f: 1L, e: -1l }
+
+@unsafe
+export let getPowers10 = (i: WasmI32) => {
+  WasmI32.load(get_POWERS10(), WasmI32.mul(4n, i))
+}
+
+@unsafe
+export let getPowers10FastPath = (i: WasmI32) => {
+  WasmF64.load(get_F64_POWERS10_FAST_PATH(), WasmI32.mul(8n, i))
+}
+
+// https://stdrs.dev/nightly/x86_64-unknown-linux-gnu/src/core/num/dec2flt/common.rs.html#165
+@unsafe
+export let is8Digits = (value: WasmI64) => {
+  let (+) = WasmI64.add
+  let (-) = WasmI64.sub
+  let (|) = WasmI64.or
+  let (&) = WasmI64.and
+  let (==) = WasmI64.eq
+
+  let a = value + 0x4646_4646_4646_4646N
+  let b = value - 0x3030_3030_3030_3030N
+  let c = (a | b) & 0x8080_8080_8080_8080N
+
+  c == 0N
+}
+
+// From Rust:
+// Calculate a base 2 exponent from a decimal exponent.
+// This uses a pre-computed integer approximation for
+// log2(10), where 217706 / 2^16 is accurate for the
+// entire range of non-finite decimal exponents.
+@unsafe
+export let power = (q: WasmI32) => {
+  let (+) = WasmI32.add
+  let (*) = WasmI32.mul
+  let (>>) = WasmI32.shrS
+
+  ((q * (152_170n + 65536n)) >> 16n) + 63n
+}
+
+@unsafe
+export let fullMultiplication = (a: WasmI64, b: WasmI64) => {
+  // Adapted from https://www.codeproject.com/Tips/618570/UInt-Multiplication-Squaring
+  let (+) = WasmI64.add
+  let (*) = WasmI64.mul
+  let (&) = WasmI64.and
+  let (>>) = WasmI64.shrU
+  let (<<) = WasmI64.shl
+
+  let aLo = a & 0xffffffffN
+  let bLo = b & 0xffffffffN
+  let aLoxbLo = aLo * bLo
+  let w3 = aLoxbLo & 0xffffffffN
+  let k = aLoxbLo >> 32N
+
+  let aHi = a >> 32N
+  let mid = aHi * bLo + k
+  let k = mid & 0xffffffffN
+  let w1 = mid >> 32N
+
+  let bHi = b >> 32N
+  let mid = aLo * bHi + k
+  let k = mid >> 32N
+
+  let hi = aHi * bHi + w1 + k
+  let lo = (mid << 32N) + w3
+
+  (WasmI32.toGrain(newInt64(lo)): Int64, WasmI32.toGrain(newInt64(hi)): Int64)
+}
+
+@unsafe
+export let biasedFpToNumber = (fp, negative) => {
+  let f = WasmI64.load(WasmI32.fromGrain(fp.f), 8n)
+  let e = WasmI64.extendI32S(WasmI32.load(WasmI32.fromGrain(fp.e), 8n))
+  let word = WasmI64.or(f, WasmI64.shl(e, _MANTISSA_EXPLICIT_BITS_64))
+  let mut float = WasmF64.reinterpretI64(word)
+  if (negative) {
+    float = WasmF64.neg(float)
+  }
+  WasmI32.toGrain(newFloat64(float)): Number
+}

package/runtime/atof/common.md

@@ -0,0 +1,243 @@
+### Common.**BiasedFp**
+
+```grain
+record BiasedFp {
+  f: Int64,
+  e: Int32,
+}
+```
+
+### Common.**_MINIMUM_EXPONENT**
+
+```grain
+_MINIMUM_EXPONENT : WasmI32
+```
+
+### Common.**_MIN_EXPONENT_ROUND_TO_EVEN**
+
+```grain
+_MIN_EXPONENT_ROUND_TO_EVEN : WasmI64
+```
+
+### Common.**_MAX_EXPONENT_ROUND_TO_EVEN**
+
+```grain
+_MAX_EXPONENT_ROUND_TO_EVEN : WasmI64
+```
+
+### Common.**_MIN_EXPONENT_FAST_PATH**
+
+```grain
+_MIN_EXPONENT_FAST_PATH : WasmI32
+```
+
+### Common.**_MAX_EXPONENT_FAST_PATH**
+
+```grain
+_MAX_EXPONENT_FAST_PATH : WasmI32
+```
+
+### Common.**_MAX_EXPONENT_DISGUISED_FAST_PATH**
+
+```grain
+_MAX_EXPONENT_DISGUISED_FAST_PATH : WasmI32
+```
+
+### Common.**_MAX_MANTISSA_FAST_PATH**
+
+```grain
+_MAX_MANTISSA_FAST_PATH : WasmI64
+```
+
+### Common.**_MANTISSA_EXPLICIT_BITS_64**
+
+```grain
+_MANTISSA_EXPLICIT_BITS_64 : WasmI64
+```
+
+### Common.**_MANTISSA_EXPLICIT_BITS_32**
+
+```grain
+_MANTISSA_EXPLICIT_BITS_32 : WasmI32
+```
+
+### Common.**_INFINITE_POWER**
+
+```grain
+_INFINITE_POWER : WasmI32
+```
+
+### Common.**_SMALLEST_POWER_OF_TEN**
+
+```grain
+_SMALLEST_POWER_OF_TEN : WasmI64
+```
+
+### Common.**_LARGEST_POWER_OF_TEN**
+
+```grain
+_LARGEST_POWER_OF_TEN : WasmI64
+```
+
+### Common.**_SMALLEST_POWER_OF_FIVE**
+
+```grain
+_SMALLEST_POWER_OF_FIVE : WasmI64
+```
+
+### Common.**_LARGEST_POWER_OF_FIVE**
+
+```grain
+_LARGEST_POWER_OF_FIVE : WasmI64
+```
+
+### Common.**_CHAR_CODE_UNDERSCORE**
+
+```grain
+_CHAR_CODE_UNDERSCORE : WasmI32
+```
+
+### Common.**_CHAR_CODE_PLUS**
+
+```grain
+_CHAR_CODE_PLUS : WasmI32
+```
+
+### Common.**_CHAR_CODE_MINUS**
+
+```grain
+_CHAR_CODE_MINUS : WasmI32
+```
+
+### Common.**_CHAR_CODE_0**
+
+```grain
+_CHAR_CODE_0 : WasmI32
+```
+
+### Common.**_CHAR_CODE_e**
+
+```grain
+_CHAR_CODE_e : WasmI32
+```
+
+### Common.**_CHAR_CODE_E**
+
+```grain
+_CHAR_CODE_E : WasmI32
+```
+
+### Common.**_CHAR_CODE_DOT**
+
+```grain
+_CHAR_CODE_DOT : WasmI32
+```
+
+### Common.**_CHAR_CODE_A**
+
+```grain
+_CHAR_CODE_A : WasmI32
+```
+
+### Common.**_CHAR_CODE_Z**
+
+```grain
+_CHAR_CODE_Z : WasmI32
+```
+
+### Common.**_CHAR_CODE_a**
+
+```grain
+_CHAR_CODE_a : WasmI32
+```
+
+### Common.**_CHAR_CODE_f**
+
+```grain
+_CHAR_CODE_f : WasmI32
+```
+
+### Common.**_CHAR_CODE_i**
+
+```grain
+_CHAR_CODE_i : WasmI32
+```
+
+### Common.**_CHAR_CODE_n**
+
+```grain
+_CHAR_CODE_n : WasmI32
+```
+
+### Common.**_CHAR_CODE_t**
+
+```grain
+_CHAR_CODE_t : WasmI32
+```
+
+### Common.**_CHAR_CODE_y**
+
+```grain
+_CHAR_CODE_y : WasmI32
+```
+
+### Common.**fpZero**
+
+```grain
+fpZero : () -> BiasedFp
+```
+
+### Common.**fpInf**
+
+```grain
+fpInf : () -> BiasedFp
+```
+
+### Common.**fpErr**
+
+```grain
+fpErr : () -> BiasedFp
+```
+
+### Common.**fpNan**
+
+```grain
+fpNan : () -> BiasedFp
+```
+
+### Common.**getPowers10**
+
+```grain
+getPowers10 : WasmI32 -> WasmI32
+```
+
+### Common.**getPowers10FastPath**
+
+```grain
+getPowers10FastPath : WasmI32 -> WasmF64
+```
+
+### Common.**is8Digits**
+
+```grain
+is8Digits : WasmI64 -> Bool
+```
+
+### Common.**power**
+
+```grain
+power : WasmI32 -> WasmI32
+```
+
+### Common.**fullMultiplication**
+
+```grain
+fullMultiplication : (WasmI64, WasmI64) -> (Int64, Int64)
+```
+
+### Common.**biasedFpToNumber**
+
+```grain
+biasedFpToNumber : (BiasedFp, Bool) -> Number
+```
+