@grain/stdlib 0.4.3 → 0.4.4

package/result.md

@@ -0,0 +1,446 @@
+---
+title: 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.
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+import Result from "result"
+```
+
+```grain
+let success = Ok((x) => 1 + x) // Creates a successful Result containing (x) => 1 + x
+```
+
+```grain
+let failure = Err("Something bad happened") // Creates an unsuccessful Result containing "Something bad happened"
+```
+
+## Values
+
+Functions for working with the Result data type.
+
+### Result.**isOk**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isOk : Result<a, b> -> Bool
+```
+
+Checks if the Result is the `Ok` variant.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`result`|`Result<a, b>`|The result to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the Result is the `Ok` variant or `false` otherwise|
+
+### Result.**isErr**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isErr : Result<a, b> -> Bool
+```
+
+Checks if the Result is the `Err` variant.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`result`|`Result<a, b>`|The result to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the Result is the `Err` variant or `false` otherwise|
+
+### Result.**toOption**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toOption : Result<a, b> -> Option<a>
+```
+
+Converts the Result to an Option. An error value is discarded and replaced with `None`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`result`|`Result<a, b>`|The result to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<a>`|`Some(value)` if the Result is `Ok(value)` or `None` if the Result is an `Err`|
+
+### Result.**flatMap**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+flatMap : ((a -> Result<b, c>), Result<a, c>) -> Result<b, c>
+```
+
+If the Result is `Ok(value)`, applies the given function to the `value` to produce a new Result.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> Result<b, c>`|The function to call on the value of an `Ok` variant|
+|`result`|`Result<a, c>`|The result to map|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<b, c>`|A new Result produced by the mapping function if the variant was `Ok` or the unmodified `Err` otherwise|
+
+### Result.**flatMapErr**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+flatMapErr : ((a -> Result<b, c>), Result<b, a>) -> Result<b, c>
+```
+
+If the Result is an `Err(value)`, applies the given function to the `value` to produce a new Result.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> Result<b, c>`|The function to call on the value of an `Err` variant|
+|`result`|`Result<b, a>`|The result to map|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<b, c>`|A new Result produced by the mapping function if the variant was `Err` or the unmodified `Ok` otherwise|
+
+### Result.**map**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+map : ((a -> b), Result<a, c>) -> Result<b, c>
+```
+
+If the Result is `Ok(value)`, applies the given function to the `value` and wraps the new value in an `Ok` variant.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> b`|The function to call on the value of an `Ok` variant|
+|`result`|`Result<a, c>`|The result to map|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<b, c>`|A new `Ok` variant produced by the mapping function if the variant was `Ok` or the unmodified `Err` otherwise|
+
+### Result.**mapErr**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+mapErr : ((a -> b), Result<c, a>) -> Result<c, b>
+```
+
+If the Result is `Err(value)`, applies the given function to the `value` and wraps the new value in an `Err` variant.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> b`|The function to call on the value of an `Err` variant|
+|`result`|`Result<c, a>`|The result to map|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<c, b>`|A new `Err` variant produced by the mapping function if the variant was `Err` or the unmodified `Ok` otherwise|
+
+### Result.**mapWithDefault**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+mapWithDefault : ((a -> b), b, Result<a, c>) -> b
+```
+
+If the Result is `Ok(value)`, applies the given function to the `value` to produce a new value, otherwise uses the default value.
+Useful for unwrapping a successful Result while providing a fallback for any errors that can occur.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> b`|The function to call on the value of an `Ok` variant|
+|`def`|`b`|A fallback value for an `Err` variant|
+|`result`|`Result<a, c>`|The result to map|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`b`|The value produced by the mapping function if the result is of the `Ok` variant or the default value otherwise|
+
+### Result.**mapWithDefaultFn**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+mapWithDefaultFn : ((a -> b), (c -> b), Result<a, c>) -> b
+```
+
+If the Result is `Ok(value)`, applies the `fnOk` function to the `value` to produce a new value.
+If the Result is `Err(value)`, applies the `fnErr` function to the `value` to produce a new value.
+Useful for unwrapping a Result into a value, whether it is successful or unsuccessful.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fnOk`|`a -> b`|The function to call on the value of an `Ok` variant|
+|`fnErr`|`c -> b`|The function to call on the value of an `Err` variant|
+|`result`|`Result<a, c>`|The result to map|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`b`|The value produced by one of the mapping functions|
+
+### Result.**or**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+( or ) : (Result<a, b>, Result<a, b>) -> Result<a, b>
+```
+
+Behaves like a logical OR (`||`) where the first Result is only returned if it is the `Ok` variant and falling back to the second Result in all other cases.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`result1`|`Result<a, b>`|The first result|
+|`result2`|`Result<a, b>`|The second result|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<a, b>`|The first Result if it is the `Ok` variant or the second Result otherwise|
+
+### Result.**and**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+and : (Result<a, b>, Result<a, b>) -> Result<a, b>
+```
+
+Behaves like a logical AND (`&&`) where the first Result is only returned if it is the `Err` variant and falling back to the second Result in all other cases.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`result1`|`Result<a, b>`|The first result|
+|`result2`|`Result<a, b>`|The second result|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<a, b>`|The second Result if both are the `Ok` variant or the first Result otherwise|
+
+### Result.**peek**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+peek : ((a -> b), (c -> d), Result<a, c>) -> Void
+```
+
+If the Result is `Ok(value)`, applies the `fnOk` function to the `value` without producing a new value.
+If the Result is `Err(value)`, applies the `fnErr` function to the `value` without producing a new value.
+Useful for inspecting Results without changing anything.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fnOk`|`a -> b`|The function to call on the value of an `Ok` variant|
+|`fnErr`|`c -> d`|The function to call on the value of an `Err` variant|
+|`result`|`Result<a, c>`|The result to inspect|
+
+### Result.**peekOk**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+peekOk : ((a -> b), Result<a, c>) -> Void
+```
+
+If the Result is `Ok(value)`, applies the given function to the `value` without producing a new value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> b`|The function to call on the value of an `Ok` variant|
+|`result`|`Result<a, c>`|The result to inspect|
+
+### Result.**peekErr**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+peekErr : ((a -> b), Result<c, a>) -> Void
+```
+
+If the Result is `Err(value)`, applies the given function to the `value` without producing a new value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> b`|The function to call on the value of an `Err` variant|
+|`result`|`Result<c, a>`|The result to inspect|
+
+### Result.**expect**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.4.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+expect : (String, Result<a, b>) -> a
+```
+
+Extracts the value inside an `Ok` result, otherwise throw an
+exception containing the message and contents of the `Err`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`msg`|`String`|The message to prepend if the result contains an `Err`|
+|`result`|`Result<a, b>`|The result to extract a value from|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`a`|The unwrapped value if the Result is the `Ok` variant|
+
+Examples:
+
+```grain
+Result.expect("Unexpected error", Ok(1234)) + 42
+```
+
+### Result.**unwrap**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.4.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+unwrap : Result<a, b> -> a
+```
+
+Extracts the value inside an `Ok` result, otherwise throw an
+exception containing a default message and contents of the `Err`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`result`|`Result<a, b>`|The result to extract a value from|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`a`|The unwrapped value if the result is the `Ok` variant|
+
+Examples:
+
+```grain
+Result.unwrap(Err("This will throw"))
+```
+

package/runtime/stringUtils.gr

@@ -0,0 +1,172 @@
+// TODO(#1050): Remove dependency on Pervasives once Option/Result types are imbedded in the compiler
+
+import WasmI32, {
+  add as (+),
+  sub as (-),
+  gtU as (>),
+  geU as (>=),
+  ltU as (<),
+  shrS as (>>),
+  eq as (==),
+  ne as (!=),
+  and as (&),
+} from "runtime/unsafe/wasmi32"
+import WasmI64 from "runtime/unsafe/wasmi64"
+import Memory from "runtime/unsafe/memory"
+import Tags from "runtime/unsafe/tags"
+import { reducedInteger } from "runtime/numbers"
+
+@disableGC
+export let rec parseInt = (string: String, radix: Number) => {
+  let _CHAR_0 = 0x30n
+  let _CHAR_B = 0x42n
+  let _CHAR_b = 0x62n
+  let _CHAR_O = 0x4fn
+  let _CHAR_o = 0x6fn
+  let _CHAR_X = 0x58n
+  let _CHAR_x = 0x78n
+
+  let _CHAR_A = 0x41n
+  let _CHAR_a = 0x61n
+
+  let _CHAR_UNDERSCORE = 0x5fn
+  let _CHAR_MINUS = 0x2dn
+
+  let _INT_MIN = -9223372036854775808N
+
+  // Don't need to process Unicode length since if the string
+  // contains non-ascii characters, it's not a valid integer
+  let strLen = WasmI32.load(WasmI32.fromGrain(string), 4n)
+
+  // Our pointer within the string we're parsing, offset by the
+  // header
+  let mut offset = WasmI32.fromGrain(string) + 8n
+
+  let strEnd = offset + strLen
+
+  let radix = WasmI32.fromGrain(radix)
+  let result = if (WasmI32.eqz(radix & Tags._GRAIN_NUMBER_TAG_MASK) || radix < WasmI32.fromGrain(2) || radix > WasmI32.fromGrain(36)) {
+    Memory.incRef(WasmI32.fromGrain(Err))
+    Err("Radix must be an integer between 2 and 36")
+  } else if (WasmI32.eqz(strLen)) {
+    Memory.incRef(WasmI32.fromGrain(Err))
+    Err("Invalid input")
+  } else {
+    let mut char = WasmI32.load8U(offset, 0n)
+
+    let mut limit = WasmI64.add(_INT_MIN, 1N)
+
+    // Check for a sign
+    let mut negative = false
+    if (char == _CHAR_MINUS) {
+      negative = true
+      offset += 1n
+      limit = _INT_MIN
+      char = WasmI32.load8U(offset, 0n)
+    }
+
+    let mut radix = WasmI64.extendI32S(radix >> 1n)
+
+    // Check if we should override the supplied radix
+    if (char == _CHAR_0 && strLen > 2n) {
+      match (WasmI32.load8U(offset, 1n)) {
+        c when c == _CHAR_B || c == _CHAR_b => {
+          radix = 2N
+          offset += 2n
+        },
+        c when c == _CHAR_O || c == _CHAR_o => {
+          radix = 8N
+          offset += 2n
+        },
+        c when c == _CHAR_X || c == _CHAR_x => {
+          radix = 16N
+          offset += 2n
+        },
+        _ => void,
+      }
+    }
+
+    let mut value = 0N
+
+    // we use 0 to represent no error, 1 to represent an invalid
+    // input, and 2 to represent an overflow
+    let mut error = 1n
+
+    for (let mut i = offset; i < strEnd; i += 1n) {
+      let char = WasmI32.load8U(i, 0n)
+
+      // Ignore underscore characters
+      if (char == _CHAR_UNDERSCORE) {
+        continue
+      }
+
+      // We've seen at least one non-underscore character, so we'll consider
+      // the input valid until we find out otherwise
+
+      error = 0n
+
+      let mut digit = 0n
+
+      match (char) {
+        c when c - _CHAR_0 < 10n => digit = char - _CHAR_0,
+        c when c - _CHAR_A < 26n => digit = char - _CHAR_A + 10n,
+        c when c - _CHAR_a < 26n => digit = char - _CHAR_a + 10n,
+        _ => {
+          error = 1n
+          // invalid digit
+          break
+        },
+      }
+
+      if (digit >= WasmI32.wrapI64(radix)) {
+        error = 1n
+        // invalid digit
+        break
+      }
+
+      let digit = WasmI64.extendI32U(digit)
+
+      value = WasmI64.mul(value, radix)
+
+      // Check for overflow
+      // 64-bit int min + 1
+      if (WasmI64.ltS(value, WasmI64.add(limit, digit))) {
+        error = 2n
+        // overflow
+        break
+      }
+
+      // To quote the OpenJDK,
+      // "Accumulating negatively avoids surprises near MAX_VALUE"
+      // The minimum value of a 64-bit integer (-9223372036854775808) can't be
+      // represented as a positive number because it would be larger than the
+      // maximum 64-bit integer (9223372036854775807), so we'd be unable to
+      // parse negatives as positives and multiply by the sign at the end.
+      // Instead, we represent all positive numbers as negative numbers since
+      // we have one unit more headroom.
+      value = WasmI64.sub(value, digit)
+    }
+
+    match (error) {
+      1n => {
+        Memory.incRef(WasmI32.fromGrain(Err))
+        Err("Invalid digit in input")
+      },
+      2n => {
+        Memory.incRef(WasmI32.fromGrain(Err))
+        Err("Input out of range of representable integers")
+      },
+      _ => {
+        let value = if (negative) value else WasmI64.mul(value, -1N)
+        let number = WasmI32.toGrain(reducedInteger(value)): (Number)
+        Memory.incRef(WasmI32.fromGrain(Ok))
+        Ok(number)
+      },
+    }
+  }
+
+  Memory.decRef(WasmI32.fromGrain(parseInt))
+  Memory.decRef(radix)
+
+  result
+}