@grain/stdlib 0.4.0 → 0.4.4

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

package/runtime/unsafe/conv.gr

@@ -68,3 +68,46 @@ export let fromFloat64 = (n: Float64) => {
   let ptr = WasmI32.fromGrain(n)
   WasmF64.load(ptr, 8n)
 }
+
+/**
+ * Converts a WasmI32 value to Number.
+ * 
+ * This function is meant to be called from a `@disableGC` context without
+ * need to call incRef on the function.
+ * 
+ * @param n: The WasmI32 to convert
+ * @returns The value converted to either a simple or a 32 bit heap allocated number.
+ */
+@disableGC
+export let wasmI32ToNumber = (n: WasmI32) => {
+  // Follows a little optimization. Instead of testing if n is range of allowed
+  // non heap allocated simple numbers (-1073741824n..1073741823n), actually
+  // make a simple number, convert it back to WasmI32, and test if it stayed
+  // the same. This may sound counter intuitive, but for numbers that fit into
+  // the range it is faster than performing the check with WasmI32.geS and
+  // WasmI32.leS by about 20%. An additional ~33% is gained by avoiding a
+  // call to tagSimpleNumber and instead doing it inline. For the case of
+  // numbers not fitting into the range, the cost of these simple ALU
+  // instructions are negligible compared to heap allocations.
+
+  // First step: naively convert to simple number, just like tagSimpleNumber.
+  // This will overflow for values not in the range, but it's fine.
+  let simple = WasmI32.xor(WasmI32.shl(n, 1n), 1n)
+
+  // Untag it, just like numbers.untagSimple.
+  let untagged = WasmI32.shrS(simple, 1n)
+
+  let result = if (WasmI32.eq(untagged, n)) {
+    // Just test if the untagged number is the same. If it didn't overflow, then
+    // we're good. We just need to cast the raw value into a Number at the type
+    // system level.
+    WasmI32.toGrain(simple): (Number)
+  } else {
+    // If it did overflow, then the value differs and we need to discard it and
+    // allocate the number on the heap. A boxed 32 bit number actually is the
+    // same thing as an Int32. It only needs to be cast into Number.
+    let asInt32 = toInt32(n)
+    WasmI32.toGrain(WasmI32.fromGrain(asInt32)): (Number)
+  }
+  result
+}

package/set.gr

@@ -1,5 +1,9 @@
-// Standard library for Set functionality
-
+/**
+ * @module Set: A Set is an unordered collection of unique values. Operations on a Set mutate the internal state, so it never needs to be re-assigned.
+ * @example import Set from "set"
+ * 
+ * @since 0.3.0
+ */
 import List from "list"
 import Array from "array"
 import { hash } from "hash"
@@ -15,14 +19,28 @@ record Set<k> {
 }
 
 // TODO: This could take an `eq` function to custom comparisons
-export let makeSized = (size) => {
-  let buckets = Array.make(size, None);
+/**
+ * Creates a new empty set with an initial storage of the given length. As values are added or removed, the length may grow or shrink. Generally, you won't need to care about the length of your set and can use `Set.make()` instead.
+ *
+ * @param storageLength: The initial storage length of the set
+ * @returns An empty set with the given initial storage length
+ * 
+ * @since 0.3.0
+ */
+export let makeSized = (storageLength) => {
+  let buckets = Array.make(storageLength, None);
   {
     size: 0,
     buckets
   }
 }
-
+/**
+ * Creates a new, empty set.
+ *
+ * @returns An empty set
+ * 
+ * @since 0.3.0
+ */
 export let make = () => {
   makeSized(16)
 }
@@ -92,6 +110,14 @@ let rec nodeInBucket = (key, node) => {
   }
 }
 
+/**
+ * Adds a new value to the set. If the value already exists, nothing happens.
+ *
+ * @param key: The value to add
+ * @param set: The set to update
+ * 
+ * @since 0.3.0
+ */
 export let add = (key, set) => {
   let buckets = set.buckets;
   let idx = getBucketIndex(key, buckets)
@@ -116,6 +142,15 @@ export let add = (key, set) => {
   }
 }
 
+/**
+ * Determines if the set contains the given value.
+ *
+ * @param key: The value to search for
+ * @param set: The set to search
+ * @returns `true` if the set contains the given value or `false` otherwise
+ * 
+ * @since 0.3.0
+ */
 export let contains = (key, set) => {
   let buckets = set.buckets;
   let idx = getBucketIndex(key, buckets);
@@ -140,6 +175,14 @@ let rec removeInBucket = (key, node) => {
   }
 }
 
+/**
+ * Removes the given value from the set. If the value doesn't exist, nothing happens.
+ *
+ * @param key: The value to remove
+ * @param set: The set to update
+ * 
+ * @since 0.3.0
+ */
 export let remove = (key, set) => {
   let buckets = set.buckets;
   let idx = getBucketIndex(key, buckets);
@@ -160,14 +203,37 @@ export let remove = (key, set) => {
   }
 }
 
+/**
+ * Returns the number of values within the set.
+ *
+ * @param set: The set to inspect
+ * @returns The number of elements in the set
+ * 
+ * @since 0.3.0
+ */
 export let size = (set) => {
   set.size
 }
 
+/**
+ * Determines if the set contains no elements.
+ *
+ * @param set: The set to inspect
+ * @returns `true` if the given set is empty or `false` otherwise
+ * 
+ * @since 0.3.0
+ */
 export let isEmpty = (set) => {
   size(set) == 0
 }
 
+/**
+ * Resets the set by removing all values.
+ *
+ * @param set: The set to reset
+ * 
+ * @since 0.3.0
+ */
 export let clear = (set) => {
   set.size = 0;
   let buckets = set.buckets;
@@ -186,6 +252,14 @@ let rec forEachBucket = (fn, node) => {
   }
 }
 
+/**
+ * Iterates the set, calling an iterator function on each element.
+ *
+ * @param fn: The iterator function to call with each element
+ * @param set: The set to iterate
+ * 
+ * @since 0.3.0
+ */
 export let forEach = (fn, set) => {
   let buckets = set.buckets;
   Array.forEach((bucket) => {
@@ -201,6 +275,16 @@ let rec reduceEachBucket = (fn, node, acc) => {
   }
 }
 
+/**
+ * Combines all elements of a set using a reducer function.
+ *
+ * @param fn: The reducer function to call on each element, where the value returned will be the next accumulator value
+ * @param init: The initial value to use for the accumulator on the first iteration
+ * @param set: The set to iterate
+ * @returns The final accumulator returned from `fn`
+ * 
+ * @since 0.3.0
+ */
 export let reduce = (fn, init, set) => {
   let buckets = set.buckets;
   let mut acc = init;
@@ -210,6 +294,14 @@ export let reduce = (fn, init, set) => {
   acc
 }
 
+/**
+ * Removes elements from a set where a predicate function returns `false`.
+ *
+ * @param fn: The predicate function to indicate which elements to remove from the set, where returning `false` indicates the value should be removed
+ * @param set: The set to iterate
+ * 
+ * @since 0.3.0
+ */
 export let filter = (predicate, set) => {
   let keysToRemove = reduce((list, key) =>
     if (!predicate(key)) {
@@ -222,14 +314,38 @@ export let filter = (predicate, set) => {
   }, keysToRemove);
 }
 
+/**
+ * Removes elements from a set where a predicate function returns `true`.
+ *
+ * @param fn: The predicate function to indicate which elements to remove from the set, where returning `true` indicates the value should be removed
+ * @param set: The set to iterate
+ * 
+ * @since 0.3.0
+ */
 export let reject = (predicate, set) => {
   filter((key) => !predicate(key), set)
 }
 
+/**
+ * Converts a set into a list of its elements.
+ *
+ * @param set: The set to convert
+ * @returns A list containing all set values
+ * 
+ * @since 0.3.0
+ */
 export let toList = (set) => {
   reduce((list, key) => [key, ...list], [], set)
 }
 
+/**
+ * Creates a set from a list.
+ *
+ * @param list: The list to convert
+ * @returns A set containing all list values
+ * 
+ * @since 0.3.0
+ */
 export let fromList = (list) => {
   let set = make();
   List.forEach((key) => {
@@ -238,10 +354,26 @@ export let fromList = (list) => {
   set
 }
 
+/**
+ * Converts a set into an array of its elements.
+ *
+ * @param set: The set to convert
+ * @returns An array containing all set values
+ * 
+ * @since 0.3.0
+ */
 export let toArray = (set) => {
   Array.fromList(toList(set))
 }
 
+/**
+ * Creates a set from an array.
+ *
+ * @param array: The array to convert
+ * @returns A set containing all array values
+ * 
+ * @since 0.3.0
+ */
 export let fromArray = (array) => {
   let set = make();
   Array.forEach((key) => {
@@ -250,6 +382,15 @@ export let fromArray = (array) => {
   set
 }
 
+/**
+ * Combines two sets into a single set containing all elements from both sets.
+ *
+ * @param set1: The first set to combine
+ * @param set2: The second set to combine
+ * @returns A set containing all elements of both sets
+ * 
+ * @since 0.3.0
+ */
 export let union = (set1, set2) => {
   let set = make();
   forEach((key) => {
@@ -261,6 +402,15 @@ export let union = (set1, set2) => {
   set
 }
 
+/**
+ * Combines two sets into a single set containing only the elements not shared between both sets.
+ *
+ * @param set1: The first set to combine
+ * @param set2: The second set to combine
+ * @returns A set containing only unshared elements from both sets
+ * 
+ * @since 0.3.0
+ */
 export let diff = (set1, set2) => {
   let set = make();
   forEach((key) => {
@@ -276,6 +426,15 @@ export let diff = (set1, set2) => {
   set
 }
 
+/**
+ * Combines two sets into a single set containing only the elements shared between both sets.
+ *
+ * @param set1: The first set to combine
+ * @param set2: The second set to combine
+ * @returns A set containing only shared elements from both sets
+ * 
+ * @since 0.3.0
+ */
 export let intersect = (set1, set2) => {
   let set = make();
   forEach((key) => {
@@ -293,6 +452,14 @@ export let intersect = (set1, set2) => {
 
 // TODO: Should return a Record type instead of a Tuple
 // Waiting on https://github.com/grain-lang/grain/issues/190
+/**
+ * Provides data representing the internal state state of the set.
+ *
+ * @param set: The set to inspect
+ * @returns The internal state of the set
+ * 
+ * @since 0.3.0
+ */
 export let getInternalStats = (set) => {
   (set.size, Array.length(set.buckets))
 }