@grain/stdlib 0.4.3 → 0.4.4

package/hash.gr

@@ -227,7 +227,7 @@ let rec hashOne = (val, depth) => {
  *
  * @since v0.1.0
  */
-export let hash = (anything) => {
+export let rec hash = (anything) => {
   h = seed
 
   hashOne(WasmI32.fromGrain(anything), 0n)
@@ -235,5 +235,10 @@ export let hash = (anything) => {
 
   // Tag the number on the way out.
   // Since Grain has proper modulus, negative numbers are okay.
-  tagSimpleNumber(h)
+  let result = tagSimpleNumber(h)
+
+  Memory.decRef(WasmI32.fromGrain(hash))
+  Memory.decRef(WasmI32.fromGrain(anything))
+
+  result
 }

package/list.gr

@@ -329,3 +329,57 @@ let join = (separator: String, items: List<String>) => {
     Some(s) => s,
   }
 }
+
+/**
+ * Reverses the first list and appends the second list to the end.
+ * 
+ * @param list1: The list to reverse
+ * @param list2: The list to append
+ * @since v0.4.5
+ */
+let rec revAppend = (list1, list2) => { 
+  match (list1) {
+    [hd, ...tl] => revAppend(tl, [hd, ...list2]),
+    [] => list2
+  }
+}
+
+/**
+ * Sorts the given list based on a given comparator function. The resulting list is sorted in increasing order.
+ * 
+ * Ordering is calculated using a comparator function which takes two list elements and must return 0 if both are equal, a positive number if the first is greater, and a negative number if the first is smaller.
+ * @param comp: The comparator function used to indicate sort order
+ * @param list: The list to be sorted
+ * @since v0.4.5
+ */
+let sort = (comp, list) => { 
+  let rec merge = (left, right, list) => {
+    match((left, right)){
+      (_, []) => {
+        revAppend(list, left)
+      },
+      ([], _) => {
+        revAppend(list, right)
+      },
+      ([lhd, ...ltl], [rhd, ...rtl]) => {
+        if(comp(lhd, rhd) < 0){
+          merge(ltl, right, append([lhd],list))
+        }else{
+          merge(left, rtl, append([rhd], list))
+        }
+      }
+    }
+  }
+
+  let rec mergesort = (list) => {
+    if(length(list) <= 1){
+      list
+    }else{
+      let middle = length(list) / 2
+      let (left, right) = part(middle, list)
+      merge(mergesort(left), mergesort(right), [])
+    }
+  }
+
+  mergesort(list)
+}

package/number.gr

@@ -15,6 +15,7 @@ import {
   isFloat,
   isBoxedNumber
 } from "runtime/numbers"
+import { parseInt } from "runtime/stringUtils"
 import { newFloat64, newInt64 } from "runtime/dataStructures"
 import Tags from "runtime/unsafe/tags"
 
@@ -76,9 +77,9 @@ export let rec sqrt = (x: Number) => {
   let x = WasmI32.fromGrain(x)
   let sqrtd = WasmF64.sqrt(xval)
   let ret = if (!isFloat(x) && WasmF64.eq(sqrtd, WasmF64.trunc(sqrtd))) {
-    WasmI32.toGrain(reducedInteger(WasmI64.truncF64S(sqrtd))): Number
+    WasmI32.toGrain(reducedInteger(WasmI64.truncF64S(sqrtd))): (Number)
   } else {
-    WasmI32.toGrain(newFloat64(sqrtd)): Number
+    WasmI32.toGrain(newFloat64(sqrtd)): (Number)
   }
   Memory.decRef(WasmI32.fromGrain(x))
   Memory.decRef(WasmI32.fromGrain(sqrt))
@@ -119,7 +120,7 @@ export let max = (x: Number, y: Number) => if (x > y) x else y
 export let rec ceil = (x: Number) => {
   let xval = coerceNumberToWasmF64(x)
   let ceiling = WasmI64.truncF64S(WasmF64.ceil(xval))
-  let ret = WasmI32.toGrain(reducedInteger(ceiling)): Number
+  let ret = WasmI32.toGrain(reducedInteger(ceiling)): (Number)
   Memory.decRef(WasmI32.fromGrain(x))
   Memory.decRef(WasmI32.fromGrain(ceil))
   ret
@@ -137,7 +138,7 @@ export let rec ceil = (x: Number) => {
 export let rec floor = (x: Number) => {
   let xval = coerceNumberToWasmF64(x)
   let floored = WasmI64.truncF64S(WasmF64.floor(xval))
-  let ret = WasmI32.toGrain(reducedInteger(floored)): Number
+  let ret = WasmI32.toGrain(reducedInteger(floored)): (Number)
   Memory.decRef(WasmI32.fromGrain(x))
   Memory.decRef(WasmI32.fromGrain(floor))
   ret
@@ -155,7 +156,7 @@ export let rec floor = (x: Number) => {
 export let rec trunc = (x: Number) => {
   let xval = coerceNumberToWasmF64(x)
   let trunced = WasmI64.truncF64S(xval)
-  let ret = WasmI32.toGrain(reducedInteger(trunced)): Number
+  let ret = WasmI32.toGrain(reducedInteger(trunced)): (Number)
   Memory.decRef(WasmI32.fromGrain(x))
   Memory.decRef(WasmI32.fromGrain(trunc))
   ret
@@ -173,7 +174,7 @@ export let rec trunc = (x: Number) => {
 export let rec round = (x: Number) => {
   let xval = coerceNumberToWasmF64(x)
   let rounded = WasmI64.truncF64S(WasmF64.nearest(xval))
-  let ret = WasmI32.toGrain(reducedInteger(rounded)): Number
+  let ret = WasmI32.toGrain(reducedInteger(rounded)): (Number)
   Memory.decRef(WasmI32.fromGrain(x))
   Memory.decRef(WasmI32.fromGrain(round))
   ret
@@ -305,3 +306,20 @@ export let rec isInfinite = (x: Number) => {
   Memory.decRef(WasmI32.fromGrain(isInfinite))
   ret
 }
+
+/**
+ * Parses a string representation of an integer into a `Number` using the
+ * specified radix (also known as a number system "base").
+ * 
+ * If the string has a radix prefix (i.e. "0x"/"0X", "0o"/"0O", or "0b"/"0B"
+ * for radixes 16, 8, or 2 respectively), the supplied radix is ignored in
+ * favor of the prefix. Underscores that appear in the numeric portion of the
+ * input are ignored.
+ * 
+ * @param input: The string to parse
+ * @param radix: The number system base to use when parsing the input string
+ * @returns `Ok(value)` containing the parsed number on a successful parse or `Err(msg)` containing an error message string otherwise
+ * 
+ * @since v0.4.5
+ */
+export parseInt

package/number.md

@@ -422,3 +422,35 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the value is infinite, otherwise `false`|
 
+### Number.**parseInt**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>next</code></summary>
+No other changes yet.
+</details>
+
+```grain
+parseInt : (String, Number) -> Result<Number, String>
+```
+
+Parses a string representation of an integer into a `Number` using the
+specified radix (also known as a number system "base").
+
+If the string has a radix prefix (i.e. "0x"/"0X", "0o"/"0O", or "0b"/"0B"
+for radixes 16, 8, or 2 respectively), the supplied radix is ignored in
+favor of the prefix. Underscores that appear in the numeric portion of the
+input are ignored.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`input`|`String`|The string to parse|
+|`radix`|`Number`|The number system base to use when parsing the input string|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<Number, String>`|`Ok(value)` containing the parsed number on a successful parse or `Err(msg)` containing an error message string otherwise|
+

package/option.gr

@@ -1,78 +1,195 @@
-// Standard library for option functionality
+/**
+ * @module Option: Utilities for working with the Option data type.
+ * 
+ * The Option type is an enum that represents the possibility of something being present (with the `Some` variant), or not (with the `None` variant). There’s no standalone `null` or `nil` type in Grain; use an Option where you would normally reach for `null` or `nil`.
+ * 
+ * @example import Option from "option"
+ * 
+ * @example let hasValue = Some(1234) // Creates an Option containing 1234
+ * @example let noValue = None // Creates an Option containing nothing
+ * 
+ * @since v0.2.0
+ */
 
-export *
+/**
+ * @section Values: Functions for working with the Option data type.
+ */
 
-let isSome = (option) => {
+/**
+ * Checks if the Option is the `Some` variant.
+ *
+ * @param option: The option to check
+ * @returns `true` if the Option is the `Some` variant or `false` otherwise
+ * 
+ * @since v0.2.0
+ */
+export let isSome = (option) => {
   match (option) {
     Some(_) => true,
     None => false
   }
 }
 
-let isNone = (option) => {
+/**
+ * Checks if the Option is the `None` variant.
+ *
+ * @param option: The option to check
+ * @returns `true` if the Option is the `None` variant or `false` otherwise
+ * 
+ * @since v0.2.0
+ */
+export let isNone = (option) => {
   match (option) {
     None => true,
     Some(_) => false
   }
 }
 
-let contains = (val, option) => {
+/**
+ * Checks if the Option is the `Some` variant and contains the given value. Uses the generic `==` equality operator.
+ *
+ * @param value: The value to search for
+ * @param option: The option to search
+ * @returns `true` if the Option is equivalent to `Some(value)` or `false` otherwise
+ * 
+ * @since v0.2.0
+ */
+export let contains = (value, option) => {
   match (option) {
-    Some(x) => x == val,
+    Some(x) => x == value,
     None => false
   }
 }
 
-let expect = (msg, option) => {
+/**
+ * Extracts the value inside a `Some` option, otherwise throws an
+ * exception containing the message provided.
+ *
+ * @param msg: The message to use upon failure
+ * @param option: The option to extract a value from
+ * @returns The unwrapped value if the Option is the `Some` variant
+ * 
+ * @since v0.2.0
+ */
+export let expect = (msg, option) => {
   match (option) {
     Some(x) => x,
     None => fail msg
   }
 }
 
-let unwrap = (option) => {
+/**
+ * Extracts the value inside a `Some` option, otherwise 
+ * throws an exception containing a default message.
+ *
+ * @param option: The option to extract the value from
+ * @returns The unwrapped value if the Option is the `Some` variant
+ * 
+ * @since v0.2.0
+ */
+export let unwrap = (option) => {
   expect("Could not unwrap None value", option)
 }
 
-let unwrapWithDefault = (default, option) => {
+/**
+ * Extracts the value inside a `Some` option or provide the default value if `None`.
+ *
+ * @param default: The default value
+ * @param option: The option to unwrap
+ * @returns The unwrapped value if the Option is the `Some` variant or the default value otherwise
+ * 
+ * @since v0.2.0
+ */
+export let unwrapWithDefault = (default, option) => {
   match (option) {
     Some(x) => x,
     None => default
   }
 }
 
-let map = (fn, option) => {
+/**
+ * If the Option is `Some(value)`, applies the given function to the `value` and wraps the new value in a `Some` variant.
+ *
+ * @param fn: The function to call on the value of a `Some` variant
+ * @param option: The option to map
+ * @returns A new `Some` variant produced by the mapping function if the variant was `Some` or the unmodified `None` otherwise
+ * 
+ * @since v0.2.0
+ */
+export let map = (fn, option) => {
   match (option) {
     Some(x) => Some(fn(x)),
     None => None
   }
 }
 
-let mapWithDefault = (fn, default, option) => {
+/**
+ * If the Option is `Some(value)`, applies the given function to the `value` to produce a new value, otherwise uses the default value.
+ * Useful for unwrapping an Option while providing a fallback for any `None` variants.
+ *
+ * @param fn: The function to call on the value of a `Some` variant
+ * @param default: A fallback value for a `None` variant
+ * @param option: The option to map
+ * @returns The value produced by the mapping function if the Option is of the `Some` variant or the default value otherwise
+ * 
+ * @since v0.2.0
+ */
+export let mapWithDefault = (fn, default, option) => {
   match (option) {
     Some(x) => fn(x),
     None => default
   }
 }
 
-let mapWithDefaultFn = (fn, defaultFn, option) => {
+/**
+ * If the Option is `Some(value)`, applies the `fn` function to the `value` to produce a new value.
+ * If the Option is `None`, calls the `defaultFn` function to produce a new value.
+ * Useful for unwrapping an Option into a value, whether it is `Some` or `None`.
+ *
+ * @param fn: The function to call on the value of a `Some` variant
+ * @param defaultFn: The default function
+ * @param option: The option to map
+ * @returns The value produced by one of the mapping functions
+ * 
+ * @since v0.2.0
+ */
+export let mapWithDefaultFn = (fn, defaultFn, option) => {
   match (option) {
     Some(x) => fn(x),
     None => defaultFn()
   }
 }
 
-let flatMap = (fn, option) => {
+/**
+ * If the Option is `Some(value)`, applies the given function to the `value` to produce a new Option.
+ *
+ * @param fn: The function to call on the value of a `Some` variant
+ * @param option: The option to map
+ * @returns A new Option produced by the mapping function if the variant was `Some` or the unmodified `None` otherwise
+ * 
+ * @since v0.2.0
+ */
+export let flatMap = (fn, option) => {
   match (option) {
     Some(x) => fn(x),
     None => None
   }
 }
 
-let filter = (pred, option) => {
+/**
+ * Converts `Some(value)` variants to `None` variants where the predicate function returns `false`.
+ * if the `fn` return `true` returns `Some(value)`, otherwise returns `None`.
+ *
+ * @param fn: The predicate function to indicate if the option should remain `Some`
+ * @param option: The option to inspect
+ * @returns `Some(value)` if the variant was `Some` and the predicate returns `true` or `None` otherwise
+ * 
+ * @since v0.2.0
+ */
+export let filter = (fn, option) => {
   match (option) {
     Some(x) =>
-      if (pred(x)) {
+      if (fn(x)) {
         Some(x)
       } else {
         None
@@ -81,70 +198,160 @@ let filter = (pred, option) => {
   }
 }
 
-let zip = (optionA, optionB) => {
+/**
+ * Combine two Options into a single Option containing a tuple of their values.
+ *
+ * @param optionA: The first option to combine
+ * @param optionB: The second option to combine
+ * @returns `Some((valueA, valueB))` if both Options are `Some` variants or `None` otherwise
+ * 
+ * @since v0.2.0
+ */
+export let zip = (optionA, optionB) => {
   match ((optionA, optionB)) {
     (Some(a), Some(b)) => Some((a, b)),
     _ => None
   }
 }
 
-let zipWith = (fn, optionA, optionB) => {
+/**
+ * Combine two Options into a single Option. The new value is produced by applying the given function to both values.
+ *
+ * @param fn: The function to generate a new value
+ * @param optionA: The first option to combine
+ * @param optionB: The second option to combine
+ * @returns `Some(newValue)` if both Options are `Some` variants or `None` otherwise
+ * 
+ * @since v0.2.0
+ */
+export let zipWith = (fn, optionA, optionB) => {
   match ((optionA, optionB)) {
     (Some(a), Some(b)) => Some(fn(a, b)),
     _ => None
   }
 }
 
-let flatten = (option) => {
+/**
+ * Flattens nested Options.
+ *
+ * @param option: The option to flatten
+ * @returns `Some(innerValue)` if all nested options were the `Some` variant or `None` otherwise
+ * 
+ * @example Option.flatten(Some(Some(1))) == Some(1)
+ *
+ * @since v0.2.0
+ */
+export let flatten = (option) => {
   match (option) {
     Some(Some(x)) => Some(x),
     _ => None
   }
 }
 
-let toList = (option) => {
+/**
+ * Converts an Option to a list with either zero or one item.
+ *
+ * @param option: The option to convert
+ * @returns `[value]` if the Option was the `Some` variant or `[]` otherwise
+ * 
+ * @since v0.2.0
+ */
+export let toList = (option) => {
   match (option) {
     Some(x) => [x],
     None => []
   }
 }
 
-let toArray = (option) => {
+/**
+ * Converts an Option to an array with either zero or one item.
+ *
+ * @param option: The option to convert
+ * @returns `[> value]` if the Option was the `Some` variant or `[> ]` otherwise
+ * 
+ * @since v0.2.0
+ */
+export let toArray = (option) => {
   match (option) {
     Some(x) => [> x],
     None => [>]
   }
 }
 
-let sideEffect = (fn, option) => {
+/**
+ * Converts the Option to a Result, using the provided error in case of the `None` variant.
+ *
+ * @param err: The error to use if the option is `None`
+ * @param option: The option to convert
+ * @returns `Ok(value)` if the Option is `Some(value)` or `Err(err)` if the Option is `None`
+ * 
+ * @since v0.2.0
+ */
+export let toResult = (err, option) => {
+  match (option) {
+    Some(a) => Ok(a),
+    None    => Err(err)
+  }
+}
+
+/**
+ * If the Option is `Some(value)`, applies the `fn` function to the `value` without producing a new value.
+ *
+ * @param fn: The function to call on the value of a `Some` variant
+ * @param option: The option to inspect
+ * 
+ * @since v0.2.0
+ */
+export let sideEffect = (fn, option) => {
   match (option) {
     Some(x) => fn(x),
     None => void
   }
 }
 
-let peek = (fn, option) => {
+/**
+ * If the Option is `Some(value)`, applies the `fn` function to the `value` without producing a new value.
+ * Useful for inspecting Options without changing anything.
+ *
+ * @param fn: The function to call on the value of a `Some` variant
+ * @param option: The option to inspect
+ * @returns The unmodified option
+ * 
+ * @since v0.2.0
+ */
+export let peek = (fn, option) => {
   sideEffect(fn, option)
   option
 }
 
-let or = (r1, r2) => {
-  match (r1) {
-    Some(x) => r1,
-    None => r2
+/**
+ * Behaves like a logical OR (`||`) where the first Option is only returned if it is the `Some` variant and falling back to the second Option in all other cases.
+ *
+ * @param optionA: The first option
+ * @param optionB: The second option
+ * @returns The first Option if it is the `Some` variant or the second Option otherwise
+ * 
+ * @since v0.2.0
+ */
+export let or = (optionA, optionB) => {
+  match (optionA) {
+    Some(x) => optionA,
+    None => optionB
   }
 }
 
-let and = (r1, r2) => {
-  match (r1) {
-    Some(_) => r2,
-    None => r1
-  }
-}
-
-let toResult = (err, option) => {
-  match (option) {
-    Some(a) => Ok(a),
-    None    => Err(err)
+/**
+ * Behaves like a logical AND (`&&`) where the first Option is only returned if it is the `None` variant and falling back to the second Option Result in all other cases.
+ *
+ * @param optionA: The first option
+ * @param optionB: The second option
+ * @returns The second Option if both are the `Some` variant or the first Option otherwise
+ * 
+ * @since v0.2.0
+ */
+export let and = (optionA, optionB) => {
+  match (optionA) {
+    Some(_) => optionB,
+    None => optionA
   }
 }