@grain/stdlib 0.5.4 → 0.5.5

package/pervasives.gr

@@ -473,10 +473,11 @@ export primitive ignore: a -> Void = "@ignore"
 
 /**
  * Assert that the given Boolean condition is `true`.
- * Throws an `AssertionError` if the condition is `false`.
  *
  * @param condition: The condition to assert
  *
+ * @throws AssertionError: When the `condition` is false
+ *
  * @example assert 3 > 2
  * @example assert true
  *
@@ -578,7 +579,7 @@ export let cons = (a, b) =>
 export let empty = [] // <- for parity with `cons`, but should be deleted as well
 
 // Setup exception printing
-@disableGC
+@unsafe
 let rec setupExceptions = () => {
   Exception.dangerouslyRegisterPrinter(e => {
     match (e) {
@@ -589,8 +590,6 @@ let rec setupExceptions = () => {
   })
 
   Exception.dangerouslyRegisterBasePrinter(e => Some(toString(e)))
-  Memory.decRef(WasmI32.fromGrain(setupExceptions))
-  void
 }
 
 setupExceptions()

package/pervasives.md

@@ -942,7 +942,6 @@ assert : Bool -> Void
 ```
 
 Assert that the given Boolean condition is `true`.
-Throws an `AssertionError` if the condition is `false`.
 
 Parameters:
 
@@ -950,6 +949,12 @@ Parameters:
 |-----|----|-----------|
 |`condition`|`Bool`|The condition to assert|
 
+Throws:
+
+`AssertionError`
+
+* When the `condition` is false
+
 Examples:
 
 ```grain

package/queue.gr

@@ -2,6 +2,8 @@
  * @module Queue: An immutable queue implementation. A queue is a FIFO (first-in-first-out) data structure where new values are added to the end and retrieved or removed from the beginning.
  * @example import Queue from "queue"
  * @since v0.2.0
+ *
+ * @deprecated This module will be renamed to ImmutableQueue in the v0.6.0 release of Grain.
  */
 import List from "list"
 
@@ -20,7 +22,7 @@ record Queue<a> {
 
 /**
  * An empty queue.
- * 
+ *
  * @since v0.5.4
  */
 export let empty = {
@@ -30,11 +32,11 @@ export let empty = {
 
 /**
  * Creates an empty queue.
- * 
+ *
  * @returns An empty queue
- * 
+ *
  * @deprecated This will be removed in the v0.6.0 release of Grain.
- * 
+ *
  * @since v0.2.0
  */
 export let make = () => {
@@ -43,7 +45,7 @@ export let make = () => {
 
 /**
  * Checks if the given queue contains any values.
- * 
+ *
  * @param queue: The queue to check
  * @returns `true` if the given queue is empty or `false` otherwise
  *
@@ -58,7 +60,7 @@ export let isEmpty = queue => {
 
 /**
  * Returns the value at the beginning of the queue. It is not removed from the queue.
- * 
+ *
  * @param queue: The queue to inspect
  * @returns `Some(value)` containing the value at the beginning of the queue, or `None` if the queue is empty
  *
@@ -76,7 +78,7 @@ export let peek = queue => {
 
 /**
  * Adds a value to the end of the queue.
- * 
+ *
  * @param value: The value to append
  * @param queue: The queue to update
  * @returns An updated queue
@@ -95,7 +97,7 @@ export let push = (value, queue) => {
 
 /**
  * Dequeues the next value in the queue.
- * 
+ *
  * @param queue: The queue to change
  * @returns An updated queue
  *
@@ -119,7 +121,7 @@ export let pop = queue => {
 
 /**
  * Get the number of values in a queue.
- * 
+ *
  * @param queue: The queue to inspect
  * @returns The number of values in the queue
  *

package/queue.md

@@ -2,6 +2,8 @@
 title: Queue
 ---
 
+> **Deprecated:** This module will be renamed to ImmutableQueue in the v0.6.0 release of Grain.
+
 An immutable queue implementation. A queue is a FIFO (first-in-first-out) data structure where new values are added to the end and retrieved or removed from the beginning.
 
 <details disabled>

package/regex.gr

@@ -458,7 +458,10 @@ enum ParsedRegularExpression {
   ), // regex, n-start, num-n, needs-backtrack
   REReference(Number, Bool), // n, case-sensitive
   RERange(RERange),
-  REUnicodeCategories(List<UnicodeCategory>, Bool), // symlist, true=match/false=does-not-match
+  REUnicodeCategories(
+    List<UnicodeCategory>,
+    Bool
+  ), // symlist, true=match/false=does-not-match
 }
 
 let needsBacktrack = (rx: ParsedRegularExpression) => {
@@ -3626,7 +3629,7 @@ export record MatchResult {
   /**
    * Returns the contents of the given group
    */
-   group: Number -> Option<String>,
+  group: Number -> Option<String>,
   /**
    * Returns the position of the given group
    */
@@ -3973,7 +3976,6 @@ let regexReplaceHelp =
     all: Bool,
   ) => {
   let buf = makeMatchBuffer(toSearch)
-  let mut out = []
   let rec loop = searchPos => {
     let state = Array.make(rx.reNumGroups, None)
     let inStart = max(0, searchPos - rx.reMaxLookbehind)
@@ -4067,3 +4069,74 @@ export let replaceAll =
   ) => {
   regexReplaceHelp(rx, toSearch, replacement, true)
 }
+
+let regexSplitHelp = (rx: RegularExpression, str: String, all: Bool) => {
+  // Get list of matches
+  let regexMatches = if (all) {
+    findAll(rx, str)
+  } else {
+    match (find(rx, str)) {
+      None => [],
+      Some(m) => [m],
+    }
+  }
+  // Perform replacements
+  let mut out = []
+  let mut currentLocation = 0
+  List.forEach(regexMatch => {
+    let locations = regexMatch.allGroupPositions()
+    Array.forEachi((pos, i) => {
+      match (pos) {
+        Some((start, end)) => {
+          if (i == 0) {
+            // Add the string between this match and the last match
+            out = [String.slice(currentLocation, start, str), ...out]
+          } else {
+            // This adds the groups back in
+            out = [String.slice(start, end, str), ...out]
+          }
+          if (end > currentLocation) currentLocation = end
+        },
+        None => void,
+      }
+    }, locations)
+  }, regexMatches)
+  out = [String.slice(currentLocation, String.length(str), str), ...out]
+  List.reverse(out)
+}
+
+/**
+ * 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.
+ *
+ * @param rx: The regular expression to match
+ * @param str: The string to split
+ * @returns A list of the split segments
+ *
+ * @example assert Regex.split(Result.unwrap(Regex.make(",")), "a,b,c") == [ "a", "b,c" ]
+ *
+ * @since v0.5.5
+ */
+export let split = (rx: RegularExpression, str: String) => {
+  regexSplitHelp(rx, str, false)
+}
+
+/**
+ * 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.
+ *
+ * @param rx: The regular expression to match
+ * @param str: The string to split
+ * @returns A list of the split segments
+ *
+ * @example assert Regex.splitAll(Result.unwrap(Regex.make(",")), "a,b,c") == [ "a", "b", "c" ]
+ *
+ * @since v0.5.5
+ */
+export let splitAll = (rx: RegularExpression, str: String) => {
+  regexSplitHelp(rx, str, true)
+}

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
+}