@grain/stdlib 0.4.0 → 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/gc.gr

@@ -40,8 +40,8 @@ primitive unbox : Box<a> -> a = "@unbox"
 
 exception DecRefError
 
-export let decimalCount32 = box((n) => 0n)
-export let utoa32Buffered = box((a, b, c) => void)
+export let decimalCount32 = box((n: WasmI32) => 0n)
+export let utoa32Buffered = box((a: WasmI32, b: WasmI32, c: WasmI32) => void)
 
 let mut _DEBUG = false
 

package/runtime/string.gr

@@ -36,6 +36,8 @@ enum StringList { SLEmpty, SLCons(String, StringList) }
 @disableGC
 let slConsDisableGc = (a, b) => {
   Memory.incRef(WasmI32.fromGrain(SLCons))
+  Memory.incRef(WasmI32.fromGrain(a))
+  // for easier chaining, we don't incRef `b`
   SLCons(a, b)
 }
 
@@ -168,13 +170,16 @@ let join = (list) => {
   WasmI32.toGrain(str): String
 }
 
+@disableGC
 let reverse = (list) => {
+  @disableGC
   let rec iter = (list, acc) => {
     match (list) {
       SLEmpty => acc,
-      SLCons(first, rest) => iter(rest, SLCons(first, acc))
+      SLCons(first, rest) => iter(rest, slConsDisableGc(first, acc))
     }
   }
+  Memory.incRef(WasmI32.fromGrain(SLEmpty))
   iter(list, SLEmpty)
 }
 
@@ -381,19 +386,24 @@ let rec heapValueToString = (ptr, extraIndents, toplevel) => {
             variantName
           } else {
             let comspace = ", "
+            let rparen = ")"
             Memory.incRef(WasmI32.fromGrain(SLEmpty))
-            let mut strings = slConsDisableGc(")", SLEmpty)
+            let mut strings = slConsDisableGc(rparen, SLEmpty)
             for (let mut i = variantArity * 4n - 4n; i >= 0n; i -= 4n) {
               let tmp = toStringHelp(WasmI32.load(ptr + i, 20n), extraIndents, false)
               strings = slConsDisableGc(tmp, strings)
+              Memory.decRef(WasmI32.fromGrain(tmp))
               if (i > 0n) {
-                Memory.incRef(WasmI32.fromGrain(comspace))
                 strings = slConsDisableGc(comspace, strings)
               }
             }
             Memory.incRef(WasmI32.fromGrain(variantName))
-            strings = slConsDisableGc(variantName, slConsDisableGc("(", strings))
+            let lparen = "("
+            strings = slConsDisableGc(variantName, slConsDisableGc(lparen, strings))
             let string = join(strings)
+            Memory.decRef(WasmI32.fromGrain(variantName))
+            Memory.decRef(WasmI32.fromGrain(lparen))
+            Memory.decRef(WasmI32.fromGrain(rparen))
             Memory.decRef(WasmI32.fromGrain(strings))
             Memory.decRef(WasmI32.fromGrain(comspace))
             string
@@ -418,28 +428,31 @@ let rec heapValueToString = (ptr, extraIndents, toplevel) => {
         Memory.fill(spacePadding + 8n, 0x20n, padAmount) // create indentation
         let spacePadding = WasmI32.toGrain(spacePadding): String
         Memory.incRef(WasmI32.fromGrain(SLEmpty))
-        let mut strings = slConsDisableGc("\n", slConsDisableGc(prevSpacePadding, slConsDisableGc("}", SLEmpty)))
+        let newline = "\n"
+        let rbrace = "}"
+        let mut strings = slConsDisableGc(newline, slConsDisableGc(prevSpacePadding, slConsDisableGc(rbrace, SLEmpty)))
         let colspace = ": "
         let comlf = ",\n"
         for (let mut i = recordArity * 4n - 4n; i >= 0n;  i -= 4n) {
           let fieldName = WasmI32.toGrain(WasmI32.load(fields + i, 8n)): String
           let fieldValue = toStringHelp(WasmI32.load(ptr + i, 16n), extraIndents + 1n, false)
-          Memory.incRef(WasmI32.fromGrain(spacePadding))
-          Memory.incRef(WasmI32.fromGrain(fieldName))
-          Memory.incRef(WasmI32.fromGrain(colspace))
           strings = slConsDisableGc(spacePadding, slConsDisableGc(fieldName, slConsDisableGc(colspace, slConsDisableGc(fieldValue, strings))))
+          Memory.decRef(WasmI32.fromGrain(fieldValue))
           if (i > 0n) {
-            Memory.incRef(WasmI32.fromGrain(comlf))
             strings = slConsDisableGc(comlf, strings)
           }
         }
-        strings = slConsDisableGc("{\n", strings)
+        let lbrace = "{\n"
+        strings = slConsDisableGc(lbrace, strings)
         let string = join(strings)
 
         Memory.decRef(WasmI32.fromGrain(strings))
         Memory.decRef(WasmI32.fromGrain(spacePadding))
         Memory.decRef(WasmI32.fromGrain(colspace))
         Memory.decRef(WasmI32.fromGrain(comlf))
+        Memory.decRef(WasmI32.fromGrain(lbrace))
+        Memory.decRef(WasmI32.fromGrain(rbrace))
+        Memory.decRef(WasmI32.fromGrain(newline))
 
         Memory.free(fields) // Avoid double-free of record field names
 
@@ -449,20 +462,24 @@ let rec heapValueToString = (ptr, extraIndents, toplevel) => {
     t when t == Tags._GRAIN_ARRAY_HEAP_TAG => {
       let arity = WasmI32.load(ptr, 4n)
       Memory.incRef(WasmI32.fromGrain(SLEmpty))
-      let mut strings = slConsDisableGc("]", SLEmpty)
+      let rbrack = "]"
+      let mut strings = slConsDisableGc(rbrack, SLEmpty)
       let comspace = ", "
       for (let mut i = arity * 4n - 4n; i >= 0n; i -= 4n) {
         let item = toStringHelp(WasmI32.load(ptr + i, 8n), extraIndents, false)
         strings = slConsDisableGc(item, strings)
+        Memory.decRef(WasmI32.fromGrain(item))
         if (i > 0n) {
-          Memory.incRef(WasmI32.fromGrain(comspace))
           strings = slConsDisableGc(comspace, strings)
         }
       }
-      strings = slConsDisableGc("[> ", strings)
+      let lbrack = "[> "
+      strings = slConsDisableGc(lbrack, strings)
       let string = join(strings)
       Memory.decRef(WasmI32.fromGrain(strings))
       Memory.decRef(WasmI32.fromGrain(comspace))
+      Memory.decRef(WasmI32.fromGrain(lbrack))
+      Memory.decRef(WasmI32.fromGrain(rbrack))
 
       string
     },
@@ -479,9 +496,13 @@ let rec heapValueToString = (ptr, extraIndents, toplevel) => {
           let numerator = NumberUtils.itoa32(WasmI32.load(ptr, 8n), 10n)
           let denominator = NumberUtils.itoa32(WasmI32.load(ptr, 12n), 10n)
           Memory.incRef(WasmI32.fromGrain(SLEmpty))
-          let strings = slConsDisableGc(numerator, slConsDisableGc("/", slConsDisableGc(denominator, SLEmpty)))
+          let slash = "/"
+          let strings = slConsDisableGc(numerator, slConsDisableGc(slash, slConsDisableGc(denominator, SLEmpty)))
           let string = join(strings)
           Memory.decRef(WasmI32.fromGrain(strings))
+          Memory.decRef(WasmI32.fromGrain(numerator))
+          Memory.decRef(WasmI32.fromGrain(denominator))
+          Memory.decRef(WasmI32.fromGrain(slash))
           string
         },
         t when t == Tags._GRAIN_FLOAT32_BOXED_NUM_TAG => {
@@ -503,30 +524,34 @@ let rec heapValueToString = (ptr, extraIndents, toplevel) => {
         WasmI32.store(ptr, 0x80000000n | tupleLength, 4n)
         let comspace = ", "
         Memory.incRef(WasmI32.fromGrain(SLEmpty))
-        let mut strings = slConsDisableGc(")", SLEmpty)
+        let rparen = ")"
+        let mut strings = slConsDisableGc(rparen, SLEmpty)
         if (tupleLength <= 1n) {
           // Special case: unary tuple
-          strings = slConsDisableGc(",", strings)
+          let comma = ","
+          strings = slConsDisableGc(comma, strings)
+          Memory.decRef(WasmI32.fromGrain(comma))
+          void
         }
         for (let mut i = tupleLength * 4n - 4n; i >= 0n; i -= 4n) {
           let item = toStringHelp(WasmI32.load(ptr + i, 8n), extraIndents, false)
-          Memory.incRef(WasmI32.fromGrain(item))
-          Memory.incRef(WasmI32.fromGrain(strings))
           strings = slConsDisableGc(item, strings)
+          Memory.decRef(WasmI32.fromGrain(item))
           if (i > 0n) {
-            Memory.incRef(WasmI32.fromGrain(comspace))
-            Memory.incRef(WasmI32.fromGrain(strings))
             strings = slConsDisableGc(comspace, strings)
           }
         }
         WasmI32.store(ptr, tupleLength, 4n)
 
         Memory.incRef(WasmI32.fromGrain(strings))
-        strings = slConsDisableGc("(", strings)
+        let lparen = "("
+        strings = slConsDisableGc(lparen, strings)
 
         let string = join(strings)
         Memory.decRef(WasmI32.fromGrain(strings))
         Memory.decRef(WasmI32.fromGrain(comspace))
+        Memory.decRef(WasmI32.fromGrain(rparen))
+        Memory.decRef(WasmI32.fromGrain(lparen))
 
         string
       }
@@ -567,7 +592,9 @@ let rec heapValueToString = (ptr, extraIndents, toplevel) => {
   let mut isFirst = true
 
   Memory.incRef(WasmI32.fromGrain(SLEmpty))
-  let mut strings = slConsDisableGc("[", SLEmpty)
+  let lbrack = "["
+  let commaspace = ", "
+  let mut strings = slConsDisableGc(lbrack, SLEmpty)
 
   while (true) {
     let variantId = WasmI32.load(cur, 12n) >> 1n // tagged number
@@ -575,19 +602,24 @@ let rec heapValueToString = (ptr, extraIndents, toplevel) => {
       break
     } else {
       if (!isFirst) {
-        strings = slConsDisableGc(", ", strings)
+        strings = slConsDisableGc(commaspace, strings)
       }
       isFirst = false
       let item = toStringHelp(WasmI32.load(cur, 20n), extraIndents, false)
       strings = slConsDisableGc(item, strings)
+      Memory.decRef(WasmI32.fromGrain(item))
       cur = WasmI32.load(cur, 24n)
     }
   }
-  strings = slConsDisableGc("]", strings)
+  let rbrack = "]"
+  strings = slConsDisableGc(rbrack, strings)
   let reversed = reverse(strings)
   let string = join(reversed)
   Memory.decRef(WasmI32.fromGrain(strings))
   Memory.decRef(WasmI32.fromGrain(reversed))
+  Memory.decRef(WasmI32.fromGrain(lbrack))
+  Memory.decRef(WasmI32.fromGrain(rbrack))
+  Memory.decRef(WasmI32.fromGrain(commaspace))
   string
 }