@grain/stdlib 0.5.12 → 0.6.0

package/random.gr

@@ -1,58 +1,53 @@
 /**
- * @module Random: Pseudo-random number generation.
- * @example import Random from "random"
+ * Pseudo-random number generation.
+ *
+ * @example from "random" include Random
+ *
  * @since v0.5.0
  */
-import WasiRandom from "sys/random"
-import Result from "result"
-import Int32 from "int32"
-import Int64 from "int64"
-import WasmI32 from "runtime/unsafe/wasmi32"
-import WasmI64 from "runtime/unsafe/wasmi64"
-import Memory from "runtime/unsafe/memory"
-import DS from "runtime/dataStructures"
+module Random
 
-/**
- * @section Types: Type declarations included in the Random module.
- */
+from "wasi/random" include Random as WasiRandom
+from "result" include Result
+from "uint32" include Uint32
+from "uint64" include Uint64
+from "runtime/unsafe/wasmi32" include WasmI32
+from "runtime/unsafe/wasmi64" include WasmI64
+from "runtime/unsafe/memory" include Memory
+from "runtime/dataStructures" include DataStructures as DS
 
-record Random {
-  seed: Int64,
-  mut counter: Int64,
+abstract record Random {
+  seed: Uint64,
+  mut counter: Uint64,
   mut initialized: Bool,
 }
 
-/**
- * @section Values: Functions for working with pseudo-random number generators.
- */
-
 let incCounter = random => {
-  random.counter = Int64.incr(random.counter)
+  random.counter = Uint64.incr(random.counter)
 }
 
 // https://arxiv.org/pdf/2004.06278v3.pdf
 @unsafe
-let squares = (ctr: Int64, key: Int64) => {
+let squares = (ctr: Uint64, key: Uint64) => {
+  use WasmI64.{ (+), (*), (|), (<<), (>>>) }
   // Implemented with @unsafe to boost efficiency
   // and have fine-grained control over overflow semantics
   let ctr = WasmI64.load(WasmI32.fromGrain(ctr), 8n)
   let key = WasmI64.load(WasmI32.fromGrain(key), 8n)
-  let mut x = WasmI64.mul(ctr, key)
+  let mut x = ctr * key
   let mut y = x
-  let mut z = WasmI64.add(y, key)
+  let mut z = y + key
   // round 1
-  x = WasmI64.add(WasmI64.mul(x, x), y)
-  x = WasmI64.or(WasmI64.shrU(x, 32N), WasmI64.shl(x, 32N))
+  x = x * x + y
+  x = x >>> 32N | x << 32N
   // round 2
-  x = WasmI64.add(WasmI64.mul(x, x), z)
-  x = WasmI64.or(WasmI64.shrU(x, 32N), WasmI64.shl(x, 32N))
+  x = x * x + z
+  x = x >>> 32N | x << 32N
   // round 3
-  x = WasmI64.add(WasmI64.mul(x, x), y)
-  x = WasmI64.or(WasmI64.shrU(x, 32N), WasmI64.shl(x, 32N))
-  let ret = WasmI32.wrapI64(
-    WasmI64.shrU(WasmI64.add(WasmI64.mul(x, x), z), 32N)
-  )
-  WasmI32.toGrain(DS.newInt32(ret)): Int32
+  x = x * x + y
+  x = x >>> 32N | x << 32N
+  let ret = WasmI32.wrapI64((x * x + z) >>> 32N)
+  WasmI32.toGrain(DS.newUint32(ret)): Uint32
 }
 
 /**
@@ -63,8 +58,8 @@ let squares = (ctr: Int64, key: Int64) => {
  *
  * @since v0.5.0
  */
-export let make = seed => {
-  { seed, counter: 0L, initialized: false }
+provide let make = seed => {
+  { seed, counter: 0uL, initialized: false }
 }
 
 /**
@@ -74,11 +69,11 @@ export let make = seed => {
  *
  * @since v0.5.0
  */
-export let makeUnseeded = () => {
+provide let makeUnseeded = () => {
   // TODO: Should we just .expect this result for UX's sake?
   Result.map(seed => {
-    { seed, counter: 0L, initialized: false }
-  }, WasiRandom.randomInt64())
+    { seed, counter: 0uL, initialized: false }
+  }, WasiRandom.randomUint64())
 }
 
 /**
@@ -91,8 +86,10 @@ export let makeUnseeded = () => {
  * we do another increment at the end.
  */
 let checkInitialized = (random: Random) => {
+  use Uint32.*
+
   if (!random.initialized) {
-    while (Int32.gt(Int32.clz(squares(random.counter, random.seed)), 0l)) {
+    while (clz(squares(random.counter, random.seed)) > 0ul) {
       incCounter(random)
     }
     // now that it's initialized, increment it again to make it a little more random
@@ -107,9 +104,10 @@ let checkInitialized = (random: Random) => {
  * @param random: The pseudo-random number generator to use
  * @returns The randomly generated number
  *
- * @since v0.5.0
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `nextInt32`
  */
-export let nextInt32 = (random: Random) => {
+provide let nextUint32 = (random: Random) => {
   checkInitialized(random)
   let ret = squares(random.counter, random.seed)
   incCounter(random)
@@ -122,19 +120,21 @@ export let nextInt32 = (random: Random) => {
  * @param random: The pseudo-random number generator to use
  * @returns The randomly generated number
  *
- * @since v0.5.0
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `nextInt64`
  */
-export let nextInt64 = (random: Random) => {
+provide let nextUint64 = (random: Random) => {
+  use Uint64.{ (|), (<<) }
   checkInitialized(random)
-  let ret1 = Int64.fromNumber(
-    Int32.toNumber(squares(random.counter, random.seed))
+  let ret1 = Uint64.fromNumber(
+    Uint32.toNumber(squares(random.counter, random.seed))
   )
   incCounter(random)
-  let ret2 = Int64.fromNumber(
-    Int32.toNumber(squares(random.counter, random.seed))
+  let ret2 = Uint64.fromNumber(
+    Uint32.toNumber(squares(random.counter, random.seed))
   )
   incCounter(random)
-  Int64.lor(Int64.shl(ret1, 32L), ret2)
+  ret1 << 32uL | ret2
 }
 
 /**
@@ -146,23 +146,19 @@ export let nextInt64 = (random: Random) => {
  * @param high: The upper bound of the range (exclusive)
  * @returns The randomly generated number
  *
- * @since v0.5.0
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `nextInt32InRange`
  */
-export let nextInt32InRange = (random: Random, low: Int32, high: Int32) => {
+provide let nextUint32InRange = (random: Random, low: Uint32, high: Uint32) => {
   // Algorithm source: https://www.pcg-random.org/posts/bounded-rands.html#bitmask-with-rejection-unbiased-apples-method
-  let (+) = Int32.add
-  let (-) = Int32.sub
-  let (*) = Int32.mul
-  let (/) = Int32.divU
-  let (&) = Int32.land
-  let (>) = Int32.gtU
-  let range = high - low - 1l
-  let mask = Int32.shrU(Int32.lnot(0l), Int32.clz(Int32.lor(range, 1l)))
-  let mut x = nextInt32(random) & mask
-  let mut iters = 0l
+  use Uint32.*
+  let range = high - low - 1ul
+  let mask = lnot(0ul) >>> clz(range | 1ul)
+  let mut x = nextUint32(random) & mask
+  let mut iters = 0ul
   while (x > range) {
-    x = nextInt32(random) & mask
-    iters += 1l
+    x = nextUint32(random) & mask
+    iters += 1ul
   }
   x + low
 }
@@ -176,21 +172,17 @@ export let nextInt32InRange = (random: Random, low: Int32, high: Int32) => {
  * @param high: The upper bound of the range (exclusive)
  * @returns The randomly generated number
  *
- * @since v0.5.0
+ * @since v0.6.0
+ * @history v0.5.0: Originally named `nextInt64InRange`
  */
-export let nextInt64InRange = (random: Random, low: Int64, high: Int64) => {
+provide let nextUint64InRange = (random: Random, low: Uint64, high: Uint64) => {
   // Algorithm source: https://www.pcg-random.org/posts/bounded-rands.html#bitmask-with-rejection-unbiased-apples-method
-  let (+) = Int64.add
-  let (-) = Int64.sub
-  let (*) = Int64.mul
-  let (/) = Int64.divU
-  let (&) = Int64.land
-  let (>) = Int64.gtU
-  let range = high - low - 1L
-  let mask = Int64.shrU(Int64.lnot(0L), Int64.clz(Int64.lor(range, 1L)))
-  let mut x = nextInt64(random) & mask
+  use Uint64.*
+  let range = high - low - 1uL
+  let mask = lnot(0uL) >>> clz(range | 1uL)
+  let mut x = nextUint64(random) & mask
   while (x > range) {
-    x = nextInt64(random) & mask
+    x = nextUint64(random) & mask
   }
   x + low
 }

package/random.md

@@ -10,7 +10,7 @@ No other changes yet.
 </details>
 
 ```grain
-import Random from "random"
+from "random" include Random
 ```
 
 ## Types
@@ -25,7 +25,7 @@ type Random
 
 ## Values
 
-Functions for working with pseudo-random number generators.
+Functions and constants included in the Random module.
 
 ### Random.**make**
 
@@ -35,7 +35,7 @@ No other changes yet.
 </details>
 
 ```grain
-make : Int64 -> Random
+make : (seed: Uint64) => Random
 ```
 
 Creates a new pseudo-random number generator with the given seed.
@@ -44,7 +44,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`seed`|`Int64`|The seed for the pseudo-random number generator|
+|`seed`|`Uint64`|The seed for the pseudo-random number generator|
 
 Returns:
 
@@ -60,7 +60,7 @@ No other changes yet.
 </details>
 
 ```grain
-makeUnseeded : () -> Result<Random, Exception>
+makeUnseeded : () => Result<Random, Exception>
 ```
 
 Creates a new pseudo-random number generator with a random seed.
@@ -71,15 +71,22 @@ Returns:
 |----|-----------|
 |`Result<Random, Exception>`|`Ok(generator)` of a pseudo-random number generator if successful or `Err(exception)` otherwise|
 
-### Random.**nextInt32**
-
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+### Random.**nextUint32**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.5.0</code></td><td>Originally named `nextInt32`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-nextInt32 : Random -> Int32
+nextUint32 : (random: Random) => Uint32
 ```
 
 Generates a random 32-bit integer from the given pseudo-random number generator.
@@ -94,17 +101,24 @@ Returns:
 
 |type|description|
 |----|-----------|
-|`Int32`|The randomly generated number|
-
-### Random.**nextInt64**
-
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+|`Uint32`|The randomly generated number|
+
+### Random.**nextUint64**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.5.0</code></td><td>Originally named `nextInt64`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-nextInt64 : Random -> Int64
+nextUint64 : (random: Random) => Uint64
 ```
 
 Generates a random 64-bit integer from the given pseudo-random number generator.
@@ -119,17 +133,24 @@ Returns:
 
 |type|description|
 |----|-----------|
-|`Int64`|The randomly generated number|
-
-### Random.**nextInt32InRange**
-
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+|`Uint64`|The randomly generated number|
+
+### Random.**nextUint32InRange**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.5.0</code></td><td>Originally named `nextInt32InRange`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-nextInt32InRange : (Random, Int32, Int32) -> Int32
+nextUint32InRange : (random: Random, low: Uint32, high: Uint32) => Uint32
 ```
 
 Generates a random 32-bit integer from the given pseudo-random number generator
@@ -140,24 +161,31 @@ Parameters:
 |param|type|description|
 |-----|----|-----------|
 |`random`|`Random`|The pseudo-random number generator to use|
-|`low`|`Int32`|The lower bound of the range (inclusive)|
-|`high`|`Int32`|The upper bound of the range (exclusive)|
+|`low`|`Uint32`|The lower bound of the range (inclusive)|
+|`high`|`Uint32`|The upper bound of the range (exclusive)|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Int32`|The randomly generated number|
-
-### Random.**nextInt64InRange**
-
-<details disabled>
-<summary tabindex="-1">Added in <code>0.5.0</code></summary>
-No other changes yet.
+|`Uint32`|The randomly generated number|
+
+### Random.**nextUint64InRange**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.5.0</code></td><td>Originally named `nextInt64InRange`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-nextInt64InRange : (Random, Int64, Int64) -> Int64
+nextUint64InRange : (random: Random, low: Uint64, high: Uint64) => Uint64
 ```
 
 Generates a random 64-bit integer from the given pseudo-random number generator
@@ -168,12 +196,12 @@ Parameters:
 |param|type|description|
 |-----|----|-----------|
 |`random`|`Random`|The pseudo-random number generator to use|
-|`low`|`Int64`|The lower bound of the range (inclusive)|
-|`high`|`Int64`|The upper bound of the range (exclusive)|
+|`low`|`Uint64`|The lower bound of the range (inclusive)|
+|`high`|`Uint64`|The upper bound of the range (exclusive)|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Int64`|The randomly generated number|
+|`Uint64`|The randomly generated number|
 

package/range.gr

@@ -1,24 +1,17 @@
 /**
- * @module Range: Utilities for working with ranges. A range represents an interval—a set of values with a beginning and an end.
- * @example import Range from "range"
+ * Utilities for working with ranges.
+ *
+ * A range represents an interval—a set of values with a beginning and an end.
+ *
+ * All functions in this module treat ranges as exclusive, but inclusive versions
+ * of all APIs are available in the `Inclusive` submodule.
+ *
+ * @example from "range" include Range
+ *
  * @since v0.3.0
+ * @history v0.6.0: Treats all ranges as exclusive
  */
-
-/**
- * @section Types: Type declarations included in the Range module.
- */
-
-/**
- * Ranges can be inclusive or exclusive. When `Inclusive`, the end value will be included in operations. When `Exclusive`, the end value will be excluded from operations.
- */
-export enum Range {
-  Inclusive(Number, Number),
-  Exclusive(Number, Number),
-}
-
-/**
- * @section Values: Functions and constants included in the Range module.
- */
+module Range
 
 /**
  * Checks if the given number is within the range.
@@ -27,55 +20,47 @@ export enum Range {
  * @param range: The range to check within
  * @returns Whether or not the value is within range
  *
- * @example Range.inRange(1, Range.Inclusive(0, 2)) == true
- * @example Range.inRange(10, Range.Inclusive(0, 2)) == false
+ * @example Range.inRange(1, { rangeStart: 0, rangeEnd: 2 }) == true
+ * @example Range.inRange(10, { rangeStart: 0, rangeEnd: 2 }) == false
  *
  * @since v0.3.0
+ * @history v0.6.0: Treats all ranges as exclusive
  */
-export let inRange = (value, range) => {
+provide let inRange = (value, range) => {
   match (range) {
-    Inclusive(lower, upper) when value >= lower && value <= upper => true,
-    Inclusive(upper, lower) when value >= lower && value <= upper => true,
-    Exclusive(lower, upper) when value >= lower && value < upper => true,
-    Exclusive(upper, lower) when value >= lower && value < upper => true,
+    { rangeStart: lower, rangeEnd: upper } when value >= lower && value < upper =>
+      true,
+    { rangeStart: upper, rangeEnd: lower } when value >= lower && value < upper =>
+      true,
     _ => false,
   }
 }
 
 /**
- * Calls the given function with each number in the range. For increasing ranges, the value is increased by `1` in each iteration, and for decreasing ranges, the value is decreased by `1`. The value is always changed by `1`, even if non-integer values were provided in the range.
+ * Calls the given function with each number in the range.
+ *
+ * For increasing ranges, the value is increased by `1` in each iteration,
+ * and for decreasing ranges, the value is decreased by `1`. The value is
+ * always changed by `1`, even if non-integer values were provided in the range.
  *
  * @param fn: The function to be executed on each number in the range
  * @param range: The range to iterate
  *
- * @example Range.forEach(val => print(val), Range.Exclusive(0, 2))
+ * @example Range.forEach(val => print(val), { rangeStart: 0, rangeEnd: 2 })
  *
  * @since v0.3.0
+ * @history v0.6.0: Treats all ranges as exclusive
  */
-export let forEach = (fn: Number -> Void, range) => {
+provide let forEach = (fn: Number => Void, range) => {
   match (range) {
-    Inclusive(lower, upper) when lower <= upper => {
-      let mut idx = lower
-      while (idx <= upper) {
-        fn(idx)
-        idx += 1
-      }
-    },
-    Inclusive(upper, lower) => {
-      let mut idx = upper
-      while (idx >= lower) {
-        fn(idx)
-        idx -= 1
-      }
-    },
-    Exclusive(lower, upper) when lower <= upper => {
+    { rangeStart: lower, rangeEnd: upper } when lower <= upper => {
       let mut idx = lower
       while (idx < upper) {
         fn(idx)
         idx += 1
       }
     },
-    Exclusive(upper, lower) => {
+    { rangeStart: upper, rangeEnd: lower } => {
       let mut idx = upper
       while (idx > lower) {
         fn(idx)
@@ -86,41 +71,32 @@ export let forEach = (fn: Number -> Void, range) => {
 }
 
 /**
- * Produces a list by calling the given function on each number included in the range. For increasing ranges, the value is increased by `1` in each iteration, and for decreasing ranges, the value is decreased by `1`. The value is always changed by `1`, even if non-integer values were provided in the range.
+ * Produces a list by calling the given function on each number included in the range.
+ *
+ * For increasing ranges, the value is increased by `1` in each iteration,
+ * and for decreasing ranges, the value is decreased by `1`. The value is
+ * always changed by `1`, even if non-integer values were provided in the range.
  *
  * @param fn: The function called on each number in the range that returns the value for the output list
  * @param range: The range to iterate
  * @returns A list containing all values returned from the `fn`
  *
- * @example Range.map(val => val * 2, Range.Inclusive(0, 2)) == [0, 2, 4]
+ * @example Range.map(val => val * 2, { rangeStart: 0, rangeEnd: 3 }) == [0, 2, 4]
  *
  * @since v0.3.2
+ * @history v0.6.0: Treats all ranges as exclusive
  */
-export let map = (fn, range) => {
+provide let map = (fn, range) => {
   let mut result = []
   match (range) {
-    Inclusive(lower, upper) when lower <= upper => {
-      let mut idx = upper
-      while (idx >= lower) {
-        result = [fn(idx), ...result]
-        idx -= 1
-      }
-    },
-    Inclusive(upper, lower) => {
-      let mut idx = lower
-      while (idx <= upper) {
-        result = [fn(idx), ...result]
-        idx += 1
-      }
-    },
-    Exclusive(lower, upper) when lower <= upper => {
+    { rangeStart: lower, rangeEnd: upper } when lower <= upper => {
       let mut idx = upper - 1
       while (idx >= lower) {
         result = [fn(idx), ...result]
         idx -= 1
       }
     },
-    Exclusive(upper, lower) => {
+    { rangeStart: upper, rangeEnd: lower } => {
       let mut idx = lower + 1
       while (idx <= upper) {
         result = [fn(idx), ...result]
@@ -130,3 +106,99 @@ export let map = (fn, range) => {
   }
   result
 }
+
+provide module Inclusive {
+  /**
+   * Checks if the given number is within the range.
+   *
+   * @param value: The number being checked
+   * @param range: The range to check within
+   * @returns Whether or not the value is within range
+   *
+   * @example Range.Inclusive.inRange(1, { rangeStart: 0, rangeEnd: 1 }) == true
+   * @example Range.Inclusive.inRange(10, { rangeStart: 0, rangeEnd: 2 }) == false
+   *
+   * @since v0.6.0
+   * @history v0.3.0: Root APIs originally handled Inclusive & Exclusive variants
+   */
+  provide let inRange = (value, range) => {
+    match (range) {
+      { rangeStart: lower, rangeEnd: upper } when value >= lower &&
+        value <= upper => true,
+      { rangeStart: upper, rangeEnd: lower } when value >= lower &&
+        value <= upper => true,
+      _ => false,
+    }
+  }
+
+  /**
+   * Calls the given function with each number in the range.
+   *
+   * For increasing ranges, the value is increased by `1` in each iteration,
+   * and for decreasing ranges, the value is decreased by `1`. The value is
+   * always changed by `1`, even if non-integer values were provided in the range.
+   *
+   * @param fn: The function to be executed on each number in the range
+   * @param range: The range to iterate
+   *
+   * @example Range.Inclusive.forEach(val => print(val), { rangeStart: 0, rangeEnd: 2 })
+   *
+   * @since v0.3.0
+   * @history v0.3.0: Root APIs originally handled Inclusive & Exclusive variants
+   */
+  provide let forEach = (fn: Number => Void, range) => {
+    match (range) {
+      { rangeStart: lower, rangeEnd: upper } when lower <= upper => {
+        let mut idx = lower
+        while (idx <= upper) {
+          fn(idx)
+          idx += 1
+        }
+      },
+      { rangeStart: upper, rangeEnd: lower } => {
+        let mut idx = upper
+        while (idx >= lower) {
+          fn(idx)
+          idx -= 1
+        }
+      },
+    }
+  }
+
+  /**
+   * Produces a list by calling the given function on each number included in the range.
+   *
+   * For increasing ranges, the value is increased by `1` in each iteration,
+   * and for decreasing ranges, the value is decreased by `1`. The value is
+   * always changed by `1`, even if non-integer values were provided in the range.
+   *
+   * @param fn: The function called on each number in the range that returns the value for the output list
+   * @param range: The range to iterate
+   * @returns A list containing all values returned from the `fn`
+   *
+   * @example Range.Inclusive.map(val => val * 2, { rangeStart: 0, rangeEnd: 2 }) == [0, 2, 4]
+   *
+   * @since v0.3.2
+   * @history v0.3.0: Root APIs originally handled Inclusive & Exclusive variants
+   */
+  provide let map = (fn, range) => {
+    let mut result = []
+    match (range) {
+      { rangeStart: lower, rangeEnd: upper } when lower <= upper => {
+        let mut idx = upper
+        while (idx >= lower) {
+          result = [fn(idx), ...result]
+          idx -= 1
+        }
+      },
+      { rangeStart: upper, rangeEnd: lower } => {
+        let mut idx = lower
+        while (idx <= upper) {
+          result = [fn(idx), ...result]
+          idx += 1
+        }
+      },
+    }
+    result
+  }
+}